将 Spanner 与 Liquibase 集成

本页面介绍如何使用 Liquibase 管理 Spanner 数据库架构更改。

Liquibase 是一个与数据库无关的开源库，用于跟踪、管理和应用数据库架构更改。它支持 SQL 以及声明性格式（如 XML、YAML 和 JSON）。

Liquibase 能够以 Spanner 数据库为目标平台。它支持所有 Spanner 功能，但存在一些限制。

如需了解一般限制，请参阅限制。
如需查看 PostgreSQL 方言数据库的其他信息，例如 Liquibase 的要求、支持的更改类型和限制，请参阅 PGAdapter 和 Liquibase。

安装 Liquibase

如需将 Liquibase 与 GoogleSQL 方言数据库搭配使用，您必须安装 Spanner Liquibase 扩展程序。对于 PostgreSQL 方言数据库，Liquibase 可以将内置的 PostgreSQL 支持与 PGAdapter 结合使用。

GoogleSQL

按照 Liquibase 文档中的说明安装和配置 Liquibase，并截取数据库的快照。在 liquibase.properties 配置文件中，按如下方式设置 url 属性。
```
jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
```
您的 liquibase.properties 配置文件只能包含此属性。其他属性是可选的。
导航到 GitHub 上的 Spanner Liquibase 扩展程序版本页面，然后选择最新版本。
选择并下载名称为 liquibase-spanner-x.y.z-all.jar 的 JAR 文件，其中 xyz 代表扩展程序版本号。例如 liquibase-spanner-4.17.0-all.jar。
将下载的 JAR 文件放在 Liquibase lib 目录中。JAR 文件包含扩展程序、Spanner SDK 和 Spanner JDBC 驱动程序驱动程序。

PostgreSQL

确保 PGAdapter 在要安装 Liquibase 的机器上已启动并运行。如需了解详情，请参阅启动 PGAdapter。
按照 Liquibase 文档中的说明安装和配置 Liquibase，并截取数据库的快照。在 liquibase.properties 配置文件中，按如下方式设置 url 属性。
```
jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
```
您的 liquibase.properties 配置文件只能包含此属性。其他属性是可选的。

url 字符串必须包含 options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction，因为 Spanner 不支持 DDL 事务，这将确保 DDL 事务自动转换为 DDL 批次。如需了解详情，请参阅 PGAdapter 的 DDL 选项。

查看 Liquibase 示例

GoogleSQL

GoogleSQL Liquibase 扩展程序随附的更改日志文件 changelog.yaml 示例展示了 Liquibase 的许多功能以及如何将其与 Spanner 结合使用。

PostgreSQL

PGAdapter 和 Liquibase GitHub 代码库中提供的示例变更日志文件 dbchangelog.xml 演示了 Liquibase 的许多功能以及如何将这些功能与 Spanner 搭配使用。

Liquibase 快速入门

本快速入门介绍如何使用 Liquibase 将 Singers 表添加到数据库。

准备工作

确保您已完成上述安装 Liquibase 的步骤。
创建 Spanner 实例。
创建 GoogleSQL 方言数据库或 PostgreSQL 方言数据库。
仅适用于 PostgreSQL 方言数据库，请确保 PGAdapter 已在安装 Liquibase 的同一机器上启动并运行。如需了解详情，请参阅启动 PGAdapter。
仅适用于 PostgreSQL 方言数据库，请使用 create_database_change_log.sql 脚本创建 databasechangeloglock 和 databasechangelog 元数据表。您必须创建这些表来替换 Liquibase 在您的数据库中自动创建的表。这是为了确保在这些表中使用 Spanner 的正确 PostgreSQL 数据类型。

您可以使用以下命令运行该脚本：
```
psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
```
通过运行以下 gcloud 命令，允许 Spanner Liquibase 扩展程序暂时使用您自己的 Spanner 用户凭据进行 API 访问：
```
gcloud auth application-default login
```

创建 changelog.yaml

在您惯用的编辑器中输入以下 YAML。

databaseChangeLog:
  - preConditions:
     onFail: HALT
     onError: HALT

  - changeSet:
     id: create-singers-table
     author: spanner-examples
     changes:
       - createTable:
          tableName: Singers
          columns:
            -  column:
                name:    SingerId
                type:    BIGINT
                constraints:
                  primaryKey: true
                  primaryKeyName: pk_Singers
            -  column:
                name:    Name
                type:    VARCHAR(255)

此 YAML 定义了一个名为 Singers 的表，它具有主键 SingerId 和 Name 列来存储歌手的姓名。

对于 PostgreSQL 方言数据库，建议表和列名称全部使用小写形式。如需了解详情，请参阅 PostgreSQL 区分大小写。

请注意，createTable 更改集必须包含主键限制条件，并且主键限制条件的名称必须为 pk_table_name。

将您所做的更改保存为 changelog.yaml。

运行 Liquibase

执行以下命令，在 changelog.yaml 中应用更改集：

liquibase --changeLogFile changelog.yaml update

Liquibase 会使用您在 liquibase.properties 文件中定义的网址。您可以通过将以下参数添加到上述命令来替换文件中的值：

--url URL

验证您的更改

上一步中的更新会导致系统将 Singer 表添加到数据库中。此外，还添加了 DATABASECHANGELOG 和 DATABASECHANGELOGLOCK 表（GoogleSQL 方言数据库）或更新（PostgreSQL 方言数据库）。

您可以通过 Google Cloud 控制台或 gcloud CLI 验证这些表是否存在。例如，运行 SQL 查询 SELECT * FROM INFORMATION_SCHEMA.TABLES 会返回数据库中所有表的列表。

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

您可以通过查询 DATABASECHANGELOG 的内容来查看已应用的更改的记录。

后续步骤

如需查看更多文档，请访问 Spanner Liquibase 扩展程序 GitHub 代码库。
如需详细了解 Liquibase，请参阅 Liquibase 使用入门