将 Spanner 与 Liquibase 集成

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

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

    您的 liquibase.properties 配置文件只能包含以下内容 属性。其他属性是可选的。

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

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

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

PostgreSQL

  1. 确保在您要安装 Liquibase 的机器上启动并运行 PGAdapter。如需了解详情，请参阅 启动 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

示例更改日志文件 changelog.yaml（随附在 GoogleSQL Liquibase 扩展程序展示了 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。

    您可以使用以下命令运行该脚本：

    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 表。此外，DATABASECHANGELOG 和 DATABASECHANGELOGLOCK 表 已添加（GoogleSQL-dialect 数据库）或更新（PostgreSQL-dialect 数据库）。

您可以通过 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 的内容来查看已应用的更改的记录。

后续步骤