小心那把锁，尤金

eugene 帮助您为 postgres 编写零停机时间模式迁移。

在 用户文档网站 上有 eugene 可以帮助您采用的模式的实用示例。这个 README 主要用于 eugene 的开发工作，只有少量的方便部分供用户使用。

链接

• 用户文档
• crates.io/crates/eugene
• docs.rs/eugene
• 仓库

安装

在 kaveland.no/eugene 的工具文档是获取使用文档的最佳地方，例如安装说明和示例。

其中一些说明在此重复，以方便用户。

除了 rust 之外，您还需要

• gcc 和 g++ 或 clang 和 clang++
  • 在 macOS 上，您可以通过 xcode-select --install 获取这些。
  • 在 Ubuntu 上，使用 sudo apt install clang 安装。
• cmake
  • 在 macOS 上，您可以通过 brew install cmake 获取。
  • 在 Ubuntu 上，您可以通过 sudo apt install cmake 获取。

cargo install eugene

您可以使用 ghcr.io/kaaveland/eugene 的 Docker 镜像。例如

 docker run --rm -it \
  -v./eugene/examples/:/examples \
  ghcr.io/kaaveland/eugene:latest \
  trace /examples/demo

版本作为无依赖项的二进制文件发布到 GitHub，因此您也可以从 发布页面 下载二进制文件。

二进制文件未签名且未经认证，因此在macos上会发出警告。如果您仍想继续，可以使用以下命令来删除它：xattr -d com.apple.quarantine eugene。

要执行本地安装您的检出仓库，可以使用以下命令：

cargo install --path eugene

用法

eugene有一个帮助命令，应该非常直观，可以显示如何使用此工具。

eugene help

请参阅kaveland.no/eugene/#usage。

在工具文档网站上，每个命令都有输出和帮助，以及如何使用它们的示例。如果您发现文档网站缺少所需的信息，请提出问题或发起拉取请求。

构建代码

您可以使用cargo build来构建项目，并使用cargo test来运行测试。测试需要连接到PostgreSQL数据库。最简单的方法是使用仓库根目录下的docker-compose设置。

docker-compose up -d
cargo test

测试

单元测试位于它们测试的代码相同的文件中。它们可以使用与docker-compose设置或github工作流相对应的数据库连接。

快照测试

某些测试在仓库中生成输出文件，主要位于/docs下。这些是快照测试。如果您发现生成的文件输出有变化，请检查并提交更改，如果更改是故意的。如果更改是非故意的，您需要找出输出为何发生变化。

构建文档

文档依赖于由cargo test生成的文件，因此您必须首先确保可以成功运行测试，请参考上一节构建代码。

工具文档使用mdBook构建，并托管在kaveland.no/eugene上。如果您已经使用cargo test生成了SUMMARY.md文件，可以使用mdbook serve eugene/docs来构建它。请注意，对summary文件的直接更改将被测试覆盖，请在eugene/src/doc_summary.md.hbs中更改模板。

使用cargo doc --open构建crate文档（可选的open指令将在浏览器中打开文档）。crate文档也托管在docs.rs上。

兼容性

eugene在Linux上与postgres版本>= 12进行了测试，并在macos和windows上对更窄的版本范围进行了测试。它没有故意使用任何特定平台的特性或新特性，并且应该与所有这些兼容。我们应该致力于与postgres社区仍支持的各个版本兼容，如果您遇到兼容性问题，请随时提交问题。

贡献

欢迎贡献，但该项目目前还没有路线图。请随时提交问题，欢迎提出想法和讨论。如果您看到您想解决的问题，但不知道从哪里开始，请随时ping @kaaveland寻求帮助，或者只是让他知道您正在处理它。

发布

要发布新版本

1. 更新Cargo.toml中的版本
2. 确保构建以更新Cargo.lock
3. 提交更改并推送到主分支
4. 标记提交并推送标签
5. GitHub Workflows会抓取标签并构建并发布新版本到crates.io

高级设计

1. eugene/src/bin/eugene.rs应仅包含与命令行界面和标准输入/输出相关的代码。
2. 具有公共字段的结构体应位于eugene::output::output_format中，这些是我们可以将其序列化为json或yaml的结构体，因此我们应该将它们视为某种形式的合同。

锁跟踪

核心思想是在事务中运行SQL脚本语句，并检查它们对数据库状态的 影响。

• 获取了哪些锁
• 对表、约束、列做了哪些更改
• 创建或删除了哪些索引

tracing模块负责在事务中运行SQL语句后存储此类状态。

代码审查

pg_query.rs将脚本拆分为语句，并将每个语句转换为语法树。这些树非常复杂，因为它们可以包含所有可能的语法，所以它们被转换为更适合编写代码审查规则的更轻量级的表示，请参阅eugene/src/linting/ast.rs。代码审查规则需要一个上下文，它是通过每个脚本中的语句逐步构建的，并且除了轻量级语法树外还需要工作。这通过允许代码审查跳过检查并发事务无法看到的对象的语句，避免了某些误报。这意味着eugene lint不会在创建表的同一事务中的create index语句上触发。

致谢

我从strong_migrations等启发性的项目以及PostgreSQL at Scale: Database Schema Changes Without Downtime等博客文章中毫无愧色地窃取了许多迁移模式。

许可

本项目采用MIT许可证 - 请参阅LICENSE.md文件了解详细信息。