本页面介绍如何使用 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 使用入门