<div align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/20c0f798-5d8d-46e4-8882-047566cba38f.png" alt="pgroll标志" /> </div> <p align="center"> <a href="https://github.com/xataio/pgroll/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-green" alt="许可证 - Apache 2.0"></a>&nbsp; <a href="https://github.com/xataio/pgroll/actions?query=branch%3Amain"><img src="https://yellow-cdn.veclightyear.com/835a84d5/cc509b60-8479-476b-95eb-36dd32110b0e.svg" alt="CI构建"></a> &nbsp; <a href="https://github.com/xataio/pgroll/releases"><img src="https://yellow-cdn.veclightyear.com/835a84d5/b43a13ef-a163-4ba5-b4d6-41acd3f2589a.svg?label=Release" alt="发布"></a> &nbsp; <a href="https://xata.io/discord"><img src="https://img.shields.io/discord/996791218879086662?label=Discord" alt="Discord"></a> &nbsp; <a href="https://twitter.com/xata"><img src="https://img.shields.io/twitter/follow/xata?style=flat" alt="X（前Twitter）关注" /> </a> </p>

pgroll - Postgres的零停机时间、可逆的架构迁移

pgroll是一个开源命令行工具，通过同时提供多个架构版本，为PostgreSQL提供安全且可逆的架构迁移。它负责处理复杂的迁移操作，以确保在更新数据库架构时客户端应用程序持续运行。这包括确保在不锁定数据库的情况下应用更改，并使新旧架构版本同时工作（即使在进行破坏性更改时也是如此！）。这消除了与架构迁移相关的风险，并大大简化了客户端应用程序的部署，同时还允许即时回滚。

有关pgroll解决的问题的更多信息，请参阅介绍性博客文章。

特性

• 零停机时间迁移（无数据库锁定，无破坏性更改）。
• 保持新旧架构版本同时工作。
• 需要时自动列回填。
• 迁移过程中出现问题时可即时回滚。
• 适用于现有架构，无需从头开始。
• 适用于Postgres 14.0或更高版本。
• 适用于任何Postgres服务（包括RDS和Aurora）。
• 用Go编写，跨平台单一二进制文件，无外部依赖。

pgroll的工作原理

pgroll通过在物理表之上使用视图来创建虚拟架构。这允许执行迁移所需的所有必要更改，而不影响现有客户端。

pgroll遵循扩展/收缩工作流。在迁移开始时，它将在物理架构中执行所有增量更改（创建表、添加列等），而不会破坏它。

当列需要进行破坏性更改时，它将在物理架构中创建一个新列，并从旧列回填数据。同时，配置触发器以确保在整个活动迁移期间，对旧/新列的所有写入都会传播到其对应列。然后，新列将在新版本的架构中公开。

一旦开始阶段完成，新架构版本就准备就绪，将所有视图映射到适当的表和列。客户端应用程序随后可以访问新架构版本，而旧版本仍然可用。这是开始推出新版本客户端应用程序的时机。

当没有更多客户端应用程序使用旧架构版本时，可以完成迁移。这将移除旧架构，新架构将成为唯一可用的版本。不再需要的表和列将被删除（此时没有客户端使用它们），新的表和列将被重命名为最终名称。在此阶段，客户端应用程序仍然可以正常工作，因为视图仍然映射到适当的表和列。

目录

• 安装
• 使用
• 文档
• 贡献
• 许可证
• 支持

安装

二进制文件

Linux、macOS和Windows的二进制文件可在我们的发布页面获取。

从源代码

要从源代码安装 pgroll，请运行以下命令：

go install github.com/xataio/pgroll@latest

注意：需要 Go 1.21 或更高版本。

通过包管理器 - Homebrew 安装

要使用 homebrew 安装 pgroll，请运行以下命令：

# macOS 或 Linux
brew tap xataio/pgroll
brew install pgroll

使用方法

按照以下步骤使用 pgroll 执行您的第一次架构迁移：

准备数据库

pgroll 需要在数据库中存储一些内部状态。将创建一个表来跟踪当前架构版本并存储版本历史。要准备数据库，请运行以下命令：

pgroll init --postgres-url postgres://user:password@host:port/dbname

开始迁移

创建一个迁移文件。您可以查看 examples 文件夹中的一些示例。例如，使用此迁移文件创建一个新的 customers 表：

<details> <summary>initial_migration.json</summary>

{
  "name": "initial_migration",
  "operations": [
    {
      "create_table": {
        "name": "customers",
        "columns": [
          {
            "name": "id",
            "type": "integer",
            "pk": true
          },
          {
            "name": "name",
            "type": "varchar(255)",
            "unique": true
          },
          {
            "name": "bio",
            "type": "text",
            "nullable": true
          }
        ]
      }
    }
  ]
}

</details>

然后运行以下命令开始迁移：

pgroll --postgres-url postgres://user:password@host:port/dbname start initial_migration.json

这将在数据库中创建一个新的架构版本，并应用迁移操作（创建表）。此命令完成后，旧版架构（没有 customers 表）和新版架构（有 customers 表）将同时可访问。

配置客户端应用程序

开始迁移后，客户端应用程序可以开始使用新的架构版本。为此，需要配置它们以访问新版本。这可以通过将 search_path 设置为新架构版本名称（由 pgroll start 输出提供）来完成，例如：

SET search_path TO 'public_initial_migration';

完成迁移

当没有更多客户端应用程序使用旧架构版本时，可以完成迁移。这将删除旧架构。要完成迁移，请运行以下命令：

pgroll --postgres-url postgres://user:password@host:port/dbname complete

回滚迁移

在迁移过程中的任何时候，都可以回滚到前一个版本。这将删除新架构，并将旧架构保留为迁移开始前的状态。要回滚迁移，请运行以下命令：

pgroll --postgres-url postgres://user:password@host:port/dbname rollback

文档

有关更高级的用法、教程和详细选项，请参阅完整的文档。

贡献

我们欢迎社区的贡献！如果您想为 pgroll 做出贡献，请遵循以下准则：

• 为任何问题、错误报告或功能请求创建一个issue。
• 在打开新的 issue 之前，请查看文档和现有 issues。

贡献代码

1. Fork 仓库。
2. 为您的功能或错误修复创建一个新分支。
3. 进行更改并编写测试（如果适用）。
4. 确保您的代码通过 linting 和测试。
5. 提交拉取请求。

对于这个项目，我们承诺以有助于建立开放、友好、多样化、包容和健康的社区的方式行动和互动。

参考

这是一份帮助我们获得灵感或与 pgroll 类似的项目和文章列表：

• Fabian Lindfors 的 Reshape
• PgHaMigrations
• 大规模 PostgreSQL：无停机时间的数据库架构更改
• 高可用性数据库中的零停机时间架构迁移
• 扩展和收缩模式

许可证

本项目采用 Apache License 2.0 许可 - 有关详细信息，请参阅 LICENSE 文件。

支持

如果您有任何问题、遇到问题或需要帮助，请在此仓库中开启一个 issue 或加入我们的 Discord，我们的社区将很乐意为您提供帮助。

<br> <p align="right">由 <a href="https://xata.io">Xata 🦋</a> 用 :heart: 制作</p>