pg-schema-diff

GitHub 发布

计算 Postgres 数据库架构之间的差异，并生成从 A 点到 B 点迁移数据库架构所需的 SQL，同时最小化停机时间和锁定。这使您能够将数据库迁移到任何用普通 DDL 定义的所需架构。

该工具尽可能使用原生 Postgres 迁移操作来执行在线迁移并避免锁定。并非所有迁移都能做到无锁，有些可能需要停机，但危险系统会提前警告您这种情况。尚不支持有状态的在线迁移技术，如影子表。

在线索引替换

您项目的差异：

$ git diff
diff --git a/schema/schema.sql b/schema/schema.sql
index cc3a14b..cf4b32d 100644
--- a/schema/schema.sql
+++ b/schema/schema.sql
@@ -2,5 +2,5 @@ CREATE TABLE foobar(
  	created_at timestamp,
	message text
);
-CREATE INDEX message_idx ON foobar(message);
+CREATE INDEX message_idx ON foobar(message, created_at);

生成的计划（即使在构建新索引时，使用 message_idx 的查询也始终有索引支持）：

$ pg-schema-diff plan --dsn "postgres://postgres:postgres@localhost:5432/postgres" --schema-dir ./schema
################################ 生成的计划 ################################
1. ALTER INDEX "message_idx" RENAME TO "pgschemadiff_tmpidx_message_idx_IiaKzkvPQtyA7ob9piVqiQ";
        -- 语句超时：3秒

2. CREATE INDEX CONCURRENTLY message_idx ON public.foobar USING btree (message, created_at);
        -- 语句超时：20分钟
        -- 锁定超时：3秒
        -- 危险 INDEX_BUILD：这可能会影响数据库性能。并发索引构建需要大量 CPU，可能影响数据库性能。它们也可能需要一段时间，但不会锁定写入操作。

3. DROP INDEX CONCURRENTLY "pgschemadiff_tmpidx_message_idx_IiaKzkvPQtyA7ob9piVqiQ";
        -- 语句超时：20分钟
        -- 锁定超时：3秒
        -- 危险 INDEX_DROPPED：删除此索引意味着使用此索引的查询可能会性能下降，因为它们将无法再利用它。

在线创建 `NOT NULL` 约束

您项目的差异：

diff --git a/schema/schema.sql b/schema/schema.sql
index cc3a14b..5a1cec2 100644
--- a/schema/schema.sql
+++ b/schema/schema.sql
@@ -1,5 +1,5 @@
 CREATE TABLE foobar(
- 	created_at timestamp,
+ 	created_at timestamp NOT NULL,
 	message text
 );
 CREATE INDEX message_idx ON foobar(message);

生成的计划（利用检查约束来消除对表的长期访问独占锁的需求）：

$ pg-schema-diff plan --dsn "postgres://postgres:postgres@localhost:5432/postgres" --schema-dir ./schema
################################ 生成的计划 ################################
1. ALTER TABLE "public"."foobar" ADD CONSTRAINT "pgschemadiff_tmpnn_BCOxMXqAQwaXlKPCRXoMMg" CHECK("created_at" IS NOT NULL) NOT VALID;
        -- 语句超时：3秒

2. ALTER TABLE "public"."foobar" VALIDATE CONSTRAINT "pgschemadiff_tmpnn_BCOxMXqAQwaXlKPCRXoMMg";
        -- 语句超时：3秒

3. ALTER TABLE "public"."foobar" ALTER COLUMN "created_at" SET NOT NULL;
        -- 语句超时：3秒

4. ALTER TABLE "public"."foobar" DROP CONSTRAINT "pgschemadiff_tmpnn_BCOxMXqAQwaXlKPCRXoMMg";
        -- 语句超时：3秒

主要特点

声明式架构迁移
尽可能使用 PostgreSQL 原生操作实现零停机迁移：
- 并发索引构建
- 在线索引替换：如果某个索引发生变更，新版本将在旧版本被删除之前构建，避免查询无索引支持的窗口期
- 在线约束构建：约束（检查、外键）先以 INVALID 状态添加，然后再验证，消除对表的长时间排他锁定需求
- 使用检查约束在线创建 NOT NULL 约束，消除对表的排他锁定需求
- 优先构建新索引：始终优先构建新索引，而非删除旧索引
全面的功能集确保计划迁移的安全性：
- 对危险操作向操作员发出警告
- 迁移计划首先在临时数据库上验证，与在实际数据库上执行的方式完全一致
对分区的强大支持

安装

命令行界面

go install github.com/stripe/pg-schema-diff/cmd/pg-schema-diff

库

go get -u github.com/stripe/pg-schema-diff

使用命令行界面

1. 将架构应用到新数据库

创建一个目录来存放架构文件。然后，生成 SQL 文件并将它们放入架构目录。

mkdir schema
echo "CREATE TABLE foobar (id int);" > schema/foobar.sql
echo "CREATE TABLE bar (id varchar(255), message TEXT NOT NULL);" > schema/bar.sql

将架构应用到新数据库。连接字符串规范可以在这里找到。设置 PGPASSWORD 环境变量将覆盖连接字符串中设置的任何密码，推荐使用此方法。

pg-schema-diff apply --dsn "postgres://postgres:postgres@localhost:5432/postgres" --schema-dir schema

2. 更新架构

更新 SQL 文件

echo "CREATE INDEX message_idx ON bar(message)" >> schema/bar.sql

应用架构。生成的计划中的任何危险操作都必须得到批准

pg-schema-diff apply --dsn "postgres://postgres:postgres@localhost:5432/postgres" --schema-dir schema --allow-hazards INDEX_BUILD

使用库

使用库的文档可以在这里找到。查看命令行界面以获取使用库的示例实现

1. 生成计划

// tempDbFactory 用于计划生成过程中提取新架构并验证计划
tempDbFactory, err := tempdb.NewOnInstanceFactory(ctx, func(ctx context.Context, dbName string) (*sql.DB, error) {
	copiedConfig := connConfig.Copy()
	copiedConfig.Database = dbName
	return openDbWithPgxConfig(copiedConfig)
})
if err != nil {
	panic("生成 TempDbFactory 失败")
}
defer tempDbFactory.Close()
// 生成迁移计划
plan, err := diff.Generate(ctx, connPool, diff.DDLSchemaSource(ddl),
	diff.WithTempDbFactory(tempDbFactory),
	diff.WithDataPackNewTables(),
)
if err != nil {
	panic("生成计划失败")
}

2. 应用计划

我们将计划应用留给用户。例如，如果您担心数据库上的并发迁移，可能想要获取会话级别的建议锁。您可能还希望由第二个用户在应用计划之前批准它。

应用示例：

for _, stmt := range plan.Statements {
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION statement_timeout = %d", stmt.Timeout.Milliseconds())); err != nil {
		panic(fmt.Sprintf("设置语句超时：%s", err))
	}
	if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET SESSION lock_timeout = %d", stmt.LockTimeout.Milliseconds())); err != nil {
		panic(fmt.Sprintf("设置锁超时：%s", err))
	}
	if _, err := conn.ExecContext(ctx, stmt.ToSQL()); err != nil {
		panic(fmt.Sprintf("执行迁移语句。数据库可能处于不一致状态：%s：%s", stmt, err))
	}
}