Include Cloud Spanner databases in your CI/CD process with the Liquibase extension

In February, we announced the beta version of the Liquibase Cloud Spanner extension that allows developers to use Liquibase’s open-source database library to manage and automate schema changes in Cloud Spanner. We’re happy to share that the Liquibase Cloud Spanner extension is now GA.

What is Liquibase?

Liquibase, an open-source library that works with a wide variety of databases, can be used for tracking, managing, and automating database schema changes. By providing the ability to integrate databases into your CI/CD process, Liquibase helps you more fully adopt DevOps practices. It supports SQL as well as declarative formats such as XML, YAML, and JSON. Liquibase includes support for reviewing changes before applying them, incrementally applying needed changes to different databases in different environments, and rolling back changes.

When you use Liquibase, every database schema change you make is called a changeset, and all of the changesets are tracked in changelogs. These changesets and changelogs make it possible to do version control on your database and make it easier to integrate database schema migrations with your CI/CD process.

What are the supported features of the Liquibase Cloud Spanner extension?

The Cloud Spanner Liquibase extension allows you to use Liquibase to target Cloud Spanner databases. The extension supports most of the available features of both Liquibase and Cloud Spanner and supports most DML and DDL commands. 

The following Liquibase ChangeTypes are supported by the extension:

createTable, dropTable, addColumn, modifyDataType, addNotNullConstraint, dropColumn, createIndex, dropIndex, addForeignKeyConstraint, dropForeignKeyConstraint, dropAllForeignKeyConstraints, addLookupTable

The following data DML ChangeTypes are supported by the extension:
insert, update, loadData, loadUpdateData

Best practices and limitations

While the Cloud Spanner Liquibase extension supports as many of the features of Cloud Spanner and Liquibase as possible, there are some features that cannot be supported or can only be supported through custom SQL changes. To use Liquibase effectively with Spanner, review this summary of best practices and limitations. See this page for the full list of limitations.

Use ModifySql commands for Cloud Spanner features without a corresponding Liquibase change type

There are some Cloud Spanner features that don’t have a corresponding change type in Liquibase. Support for these features can be accomplished by adding a ModifySql command to your change set to modify the generated SQL.

DDL limits and best practices for schema updates

Cloud Spanner recommends some best practices for schema updates including limiting the frequency of schema updates and considering the impact of large scale schema changes. One approach is to apply a small number of change sets. Alternatively, you can use SQL change and batch the DDL using batch statements.

Liquibase change types with limited or no Cloud Spanner support

There are some change types that Liquibase supports that either aren’t supported by Cloud Spanner or have certain limitations. For example, addPrimaryKey and dropPrimaryKey are not supported, because Cloud Spanner requires all tables to have a primary key. The primary key has to be defined when the table is created, and can’t be added or dropped later.

For a full list of these change types and potential workarounds, see this section of the documentation.

Database features that aren’t supported by Cloud Spanner

There are some database features that are not supported by Spanner. If you try to use any of the following through Liquibase, an error will occur:

• Auto increment columns
• Sequences
• Default value definition for a column
• Unique constraints (use UNIQUE INDEX instead)
• Stored procedures
• Views
• Table and column remarks

How to get started

Using Cloud Spanner and Liquibase together allows you to integrate database schema migrations in your CI/CD pipelines. If you’re ready to try out the Cloud Spanner Liquibase extension for yourself, download the latest release here. Then, head over to the Liquibase with Cloud Spanner integration guide, which will walk you through how to create a changelog, how to run the changelog with Liquibase, and how to verify the changes. You can use the Liquibase extension with your actual Spanner instances or with the emulator.

For even more information and additional changelog examples, visit the liquibase-spanner GitHub repository. We would love to hear your feedback, so please share any suggestions, issues, or questions in the issue tracker.