This page describes how to use the open source Cloud Spanner Liquibase Extension to manage database schema changes with Liquibase.
Liquibase is an open-source database-independent library for tracking, managing, and applying database schema changes. It supports SQL as well as declarative formats such as XML, YAML, and JSON. With the Cloud Spanner Liquibase Extension you can enable Liquibase to target Cloud Spanner. All Cloud Spanner features, with the exception of some limitations, are supported.
Installing Liquibase
Follow the instructions in the Liquibase documentation to install and configure Liquibase.
Installing the extension
Navigate to the Cloud Spanner Liquibase Extension releases page on GitHub and select the latest release.
Select and download the JAR file with the name
liquibase-spanner-x.y.z-all.jar
, where x.y.z represents the extension version number. For example, liquibase-spanner-1.0.2-all.jar.Place the downloaded JAR file in the Liquibase lib directory. The JAR file includes the extension, the Cloud Spanner SDK, and the Cloud Spanner JDBC driver.
Configure the URL for Liquibase in the format
jdbc:cloudspanner:/projects/<project>/instances/<instance>/databases/<database>
Using the extension
The example changelog.yaml included with the Cloud Spanner Liquibase Extension demonstrates many of the features of Liquibase and how to use them with Cloud Spanner.
Before you begin
Make sure you have completed the preceding steps to install the extension.
Make sure you have created a Cloud Spanner instance.
Make sure you have created a Cloud Spanner database.
Give the extension temporary use of your own Cloud Spanner user credentials for API access by running the following
gcloud
command:gcloud auth application-default login
Creating a changelog.yaml
Enter the following YAML into your favorite editor.
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 - column: name: Name type: STRING(255)
This YAML defines a table called
Singers
with a primary keySingerId
and a column calledName
to store the singer's name.Save your changes as changelog.yaml.
Running Liquibase
Execute these commands against Liquibase using the following command, replacing
<URL>
with the JDBC connection string, in the format jdbc:cloudspanner:/projects/<project>/instances/<instance>/databases/<database>
.
liquibase --changeLogFile changelog.yaml --url <URL> update
Verifying your changes
The updates in the preceding step caused three new tables to be added to your
database: Singer
, DATABASECHANGELOG
, and DATABASECHANGELOGLOCK
.
You can verify the existence of these tables through the Google Cloud console
or gcloud CLI. For example, running the SQL query SELECT * FROM
INFORMATION_SCHEMA.TABLES
returns a list of all tables in your database.
gcloud spanner databases execute-sql <DB> --instance=<INSTANCE> \
--sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'
You can see a record of the changes that were applied by querying the contents
of DATABASECHANGELOG
.
What's next
For more documentation, visit the Cloud Spanner Liquibase Extension GitHub repo.
To learn more about Liquibase, see Getting Started with Liquibase