Phalanx 是一个用 Swift 编写的 Cassandra 迁移工具，其人体工程学设计灵感来源于 flyway。

Phalanx 专为已经编写 Swift 后端/微服务的开发者设计，他们可能希望留在熟悉的工具链/生态系统的范围内。

.package(url: "https://github.com/jmfieldman/phalanx.git", from: "1.0.0")

Swift PM 将自动检测可执行目标，因此您现在可以通过您自己的包运行 phalanx 可执行文件

$ swift run phalanx ...

如果 Phalanx 与您的项目存在依赖冲突，或者您只是想要更精简的执行体验，请尝试使用非常出色的 Mint 包管理器安装 Phalanx。

Mint 在其自己的环境中构建每个 Swift 可执行文件，跟踪版本，并通过 Mintfile 支持本地化的版本锁定。这避免了在您自己的项目的 Package.swift 更改时，持续不断的、不必要的重新构建检查。

# Install mint on your system, e.g.
$ brew install mint

# Install Phalanx
$ mint install jmfieldman/phalanx

# Run Phalanx using Mint. This is the recommended method if you plan
# on using a Mintfile for version-pegging
$ mint run phalanx <..>

# Or run it directly if you have the Mint bin directory in your path
$ phalanx <..>

# Phalanx will use the keyspace associated
# with the command to `DROP KEYSPACE <keyspace>`
$ phalanx clean

# Phalanx will use the detected migration files to bring your
# keyspace up to the most recent version.
$ phalanx migrate

Phalanx 通常使用配置文件进行配置。可用配置选项的详细信息，包括所有命令行覆盖选项，请参见示例配置。

# Phalanx looks for phalanx.yml by default, but you can override
# that with the --config parameter, e.g.
$ phalanx --config conf/phalanx.yml migrate

$ phalanx --help

迁移文件应全部分组到一个目录中。 Phalanx 将在迁移目录的内容中查找与迁移文件模式匹配的任何文件。

您可以配置定义迁移文件名称结构的文件前缀、扩展名和版本描述符分隔符。

# Prefix = null
# Separatpr = "-"
# Extension = "cql"

$ ls
000-create_keyspace.cql
001-create_user_table.cql
002-add_password_column_to_users.cql
003-create_device_table.cql
README.md # This file will be ignored as it does not match migration patterns

迁移文件可以包含其自己唯一的元数据，这些元数据仅影响其特定的调用。此元数据必须包含在迁移文件的顶部。它被格式化为 CQL 注释的 YAML。

-- metadata:
--   description: This overrides the filename-based description
--   invocationDelay: <int> # Overrides the global invocation delay
--   consistency: <string> # Overrides the global consistency config

CREATE TABLE ...

任何单个 Phalanx 调用都将仅在配置或命令行中定义的一个 keyspace 上运行。如果您想为多个 keyspace 设置迁移，它们需要位于隔离的目录中，并且您需要为每个 keyspace 单独调用 Phalanx。

Phalanx 期望初始迁移从一个空白状态开始，并且在迁移 0 之前没有 keyspace 准备就绪。由于 keyspace 创建可能涉及复杂的自定义参数，因此 Phalanx 保留迁移 0 用于 keyspace 创建。

这意味着标记为版本 0 的迁移（例如000-create_keyspace.cql）只能包含以 CREATE KEYSPACE 开头的命令。

如果您不希望 Phalanx 负责 keyspace 创建，您可以自己创建 keyspace，然后从版本 1 开始迁移文件。

在某些情况下，您可能希望相同的迁移链存在于多个 keyspace 中。例如，您可以使用单个本地 Cassandra 节点进行本地开发、单元测试和本地 CI 代理。

为了使这些范围中的数据得到正确的隔离，您将为每个范围使用不同的 keyspace（例如，project_local、project_tests、project_ci 等）。

在这种情况下，您可以在迁移文件中使用占位符 $${{KEYSPACE}}$$，迁移引擎会自动将其替换为当前正在执行的 keyspace。这对于创建 keyspace 的零版本迁移尤其有用。

由于 Cassandra 没有传统的多命令事务，因此将多个命令放在单个迁移版本中是不安全的。例如，如果一个迁移文件包含 10 个命令，而第 5 个命令失败，则无法清楚地记录某个迁移文件“完成了一半”。

通过将迁移文件限制为每个文件一个命令，我们可以确保各个命令成功并锁定到状态表中。

$ swift test

这些测试期望 Cassandra 节点在 127.0.0.1:9042 上可用，并且将在 phalanx_test_keyspace keyspace 上运行（多次删除和创建它）。

动机

安装

Swift 包管理器 (Swift Package Manager)

独立安装 (Mint)

用法

配置

迁移文件

重要概念

单元测试