Using Liquibase with Cloud Spanner
Cloud Spanner is a fully managed relational database with unlimited scale and strong consistency. It optimizes performance by automatically sharding the data based on request load and size of the data.
You can use the Cloud Spanner Liquibase Extension to manage database schema changes with Liquibase. 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.
Additionally, the example changelog.yaml included with the Cloud Spanner Liquibase extension demonstrates Liquibase features and how to use them with Cloud Spanner.
Install Drivers
To use Liquibase and Cloud Spanner, you need to have the Cloud Spanner Liquibase extension file, which includes the extension, the Cloud Spanner SDK, and the Cloud Spanner JDBC driver:
- Go to the liquibase-spanner repository.
- Download the latest released extension
liquibase-spanner-version-all.jar
file. - Place the
liquibase-spanner-version-all.jar
file in theliquibase/lib
install directory.
Test Your Connection
- Ensure you have created the Cloud Spanner instance and 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
- Configure URL in the format:
-
Create a
changelog.yaml
file, enter the following information, and save the changes: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)
Note: The YAML file defines a table called
Singers
with a primary keySingerId
and a column calledName
to store the singer's name. - Run the Liquibase
update
command, replacing<URL>
with the JDBC connection string, in the formatjdbc:cloudspanner:/projects/<project>/instances/<instance>/databases/<database>
. You can also specify the database URL in Liquibase properties file. For more information, see Specifying Properties in a Connection Profile.
jdbc:cloudspanner:/projects/<project>/instances/<instance>/databases/<database>
liquibase --changelog-file=changelog.yaml --url=<URL> update
- Verify your changes. After running the first update, you will see three new tables added to your database:
Singer
, DATABASECHANGELOG, and DATABASECHANGELOGLOCK. You can verify the existence of these tables through the Cloud Console orgcloud
tool. For example, running the SQL querySELECT * FROM INFORMATION_SCHEMA.TABLES
returns a list of all tables in your database.
Also, you can see a record of the changes that were applied by querying the contents of DATABASECHANGELOG.gcloud spanner databases execute-sql <DB> --instance=<INSTANCE> \ --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'
Supported Change Types
The following LiquibaseChange Types are supported: createTable
, dropTable
, addColumn
, modifyDataType
, addNotNullConstraint
, dropColumn
, createIndex
, dropIndex
, addForeignKeyConstraint
, dropForeignKeyConstraint
, dropAllForeignKeyConstraints
, addLookupTable
.
The following data DML Change Types are supported: insert
, update
, loadData
, loadUpdateData
.