本页介绍如何使用 Liquibase 管理 Spanner 数据库架构更改。
Liquibase 是一个与数据库无关的开源库,用于跟踪、管理和应用数据库架构更改。它支持 SQL 以及声明性格式(如 XML、YAML 和 JSON)。
Liquibase 以 Spanner 数据库为目标。它支持所有 Spanner 功能,但存在一些限制。
- 如需查看一般限制,请参阅限制。
- 如需了解 PostgreSQL 方言数据库的更多信息(例如 Liquibase 要求、支持的更改类型和限制),请参阅 PGAdapter 和 Liquibase。
安装 Liquibase
如需将 Liquibase 与 GoogleSQL 方言数据库搭配使用,您必须安装 Spanner Liquibase 扩展程序。对于 PostgreSQL 方言数据库,Liquibase 可以与 PGAdapter 结合使用其内置 PostgreSQL 支持。
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
确保在将安装 Liquibase 的机器上启动并运行 PGAdapter。如需了解详情,请参阅启动 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 方言数据库,请确保在安装 Liquibase 的同一台机器上启动并运行 PGAdapter。如需了解详情,请参阅启动 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 使用入门