将 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. 导航到 Spanner Liquibase GitHub 上的“扩展程序版本”页面,然后选择 最新版本

  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. 确保 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

示例更改日志文件 changelog.yaml(随附在 GoogleSQL Liquibase 扩展程序展示了 Liquibase 以及如何将其与 Spanner 搭配使用。

PostgreSQL

示例变更日志文件 dbchangelog.xml,可通过 PGAdapter 和 Liquibase GitHub 代码库 演示了 Liquibase 的许多功能,以及如何将这些功能与 Spanner。

Liquibase 快速入门

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

准备工作

  • 请确保您已完成前面的安装步骤。 Liquibase。

  • 创建 Spanner 实例。

  • 创建 GoogleSQL 方言数据库或 PostgreSQL 方言数据库。

  • 仅限 PostgreSQL 方言数据库,请确保 PGAdapter 已启动并运行 安装在 Liquibase 的同一台计算机上。如需了解详情,请参阅 启动 PGAdapter

  • 仅适用于 PostgreSQL 方言数据库,请创建 databasechangeloglockdatabasechangelog元数据表 create_database_change_log.sql 脚本。 您必须创建这些表才能 覆盖 Liquibase 在您的数据库中自动创建的表。 这是为了确保 这些表中使用了 Spanner。

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

    psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
    
  • 暂时使用您自己的 Spanner Liquibase 扩展程序 运行以下命令来进行 API 访问的 Spanner 用户凭据 gcloud 命令:

    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 的表,它具有主键 SingerIdName 列来存储歌手的姓名。

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

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

  2. changelog.yaml 格式保存您所做的更改。

运行 Liquibase

通过执行以下命令,在 changelog.yaml 中应用更改集:

liquibase --changeLogFile changelog.yaml update

Liquibase 会使用您在 liquibase.properties 文件中定义的网址。您 可以通过将以下参数添加到 前面的命令:

--url URL

验证您的更改

上一步中的更新导致 Singer 表被添加到 数据库。此外,DATABASECHANGELOGDATABASECHANGELOGLOCK 表 已添加(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 的内容来查看已应用的更改的记录。

后续步骤