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.

Supported versions

  • 2.7.3

Verification level

Compatible: This database is widely reported by the community to work with Liquibase. Automated testing may verify partial Liquibase Open Source and Liquibase Pro functionality. The Liquibase support team provides best-effort usage support to Commercial users.

Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Open Source and Liquibase Pro. For more information, see Liquibase Database Tutorials.


Install drivers

To use Liquibase and Cloud Spanner, you need the Cloud Spanner Liquibase extension file, liquibase-spanner-version-all.jar, which includes the extension, the Cloud Spanner SDK, and the Cloud Spanner JDBC driver. You can also download the JDBC driver from the Central Maven Repository.

Place your JAR file(s) in the liquibase/lib directory. Read more: Adding and Updating Liquibase Drivers.

If you use Maven, you must include the driver JAR as a dependency in your pom.xml file. Read more: Configuring Liquibase Attributes in your Maven POM File.


Test your connection

  1. Ensure you have created the Cloud Spanner instance and database. Then give the extension temporary use of your own Cloud Spanner user credentials for API access by running the following gcloud command:
  2. gcloud auth application-default login
  3. Specify the database URL in the Liquibase properties file. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard JDBC format:
  4. url: jdbc:cloudspanner:/projects/<project>/instances/<instance>/databases/<database>

    Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: liquibaseProLicenseKey: <paste code here>

  1. Create a text file called changelog (.xml, .sql, .json, or .yaml) in your project directory and add a changeset.
  2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
  3. liquibase --username=test --password=test --changelog-file=<changelog.xml> status

    Note: You can pass arguments in the CLI or keep them in the Liquibase properties file.

  4. Inspect the SQL with the update-sql command. Then make changes to your database with the update command.
  5. liquibase --changelog-file=<changelog.xml> update-sql
    liquibase --changelog-file=<changelog.xml> update
  6. From a database UI tool, ensure that your database contains the test_table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

You can verify the existence of these tables through the Cloud Console or gcloud tool. 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> \

Related links