将 Spanner 与 Liquibase 集成

本页面介绍了如何使用 Liquibase 为 GoogleSQL 方言数据库和 PostgreSQL 方言数据库管理 Spanner 数据库架构更改。

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

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

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

安装 Liquibase

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

GoogleSQL

1. 按照 Liquibase 文档中的说明安装和配置 Liquibase，并为数据库拍摄快照。在 liquibase.properties 配置文件中，按如下所示设置 url 属性。

 jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
 

Your `liquibase.properties` configuration file can contain only this
property. Other properties are optional.

1. 前往 GitHub 上的 Spanner Liquibase 扩展程序版本页面，然后选择最新版本。

2. 选择并下载名称为 liquibase-spanner-x.y.z-all.jar 的 JAR 文件，其中 x.y.z 代表扩展程序版本号。例如 liquibase-spanner-4.17.0-all.jar。

3. 将下载的 JAR 文件放在 Liquibase lib 目录中。JAR 文件包含扩展程序、Spanner SDK 和 Spanner JDBC 驱动程序。

PostgreSQL

1. 确保 PGAdapter 已在安装 Liquibase 的机器上启动并运行。如需了解详情，请参阅启动 PGAdapter。

2. 按照 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

1. 在您惯用的编辑器中输入以下 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。

2. 将更改保存为 changelog.yaml。

运行 Liquibase

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

liquibase --changeLogFile changelog.yaml update

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

--url URL

验证您的更改

前面步骤中的更新导致向数据库中添加了 Singer 表。此外，还添加（GoogleSQL 方言数据库）或更新（PostgreSQL 方言数据库）了 DATABASECHANGELOG 和 DATABASECHANGELOGLOCK 表。

您可以通过 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 使用入门。