Skip to content
Star Us On GitHub

Using Liquibase with Amazon Keyspaces (for Apache Cassandra)

Amazon Keyspaces is a DBaaS compatible with Apache Cassandra. For more information, see Amazon Keyspaces Documentation.

Prerequisites

Setup Liquibase

  1. Dive into Liquibase concepts with an Introduction to Liquibase.
  2. Download and install Liquibase on your machine.

  3. (optional) Enable Liquibase Pro capabilities

    To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file:

    liquibase.licenseKey: <paste key here>

Setup Amazon Keyspaces

Configure your Amazon Keyspaces instance following the official documentation.

Install drivers

All users

To use Liquibase and Cassandra on Amazon Keyspaces, you need two JAR files: a JDBC driver and the Liquibase Cassandra extension:

Note

These instructions assume Liquibase Cassandra extension v4.29.0 or newer. Prior versions are not compatible with Amazon Keyspaces.

  1. Download the jar files

  2. Place your JAR file(s) in the <liquibase_install_dir>/lib directory.

    • cassandra-jdbc-wrapper-<version>-bundle.jar
    • liquibase-cassandra-<version>.jar

  3. Open the Liquibase properties file and specify the driver, as follows:

    driver: com.ing.data.cassandra.jdbc.CassandraDriver

Maven users (additional step)

If you use Maven, note that this database does not provide its driver JAR on a public Maven repository, so you must install a local copy and add it as a dependency to your pom.xml file.

<dependency>
    <groupId>com.ing.data</groupId>
    <artifactId>cassandra-jdbc-wrapper</artifactId>
    <version>4.13.0</version>
</dependency>
<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-cassandra</artifactId>
    <version>4.29.1</version>
</dependency>

Database connection

Configure connection

  1. Specify the database JDBC URL in the liquibase.properties file (defaults file), along with other properties you want to set a default value for. Liquibase does not parse the URL.

    Please specify the URL using this JDBC format:

    url: jdbc:cassandra://cassandra.<aws-region>.amazonaws.com:9142/<keyspace>?compliancemode=Liquibase&user=<username>&password=<password>

    Replace <keyspace> with your own keyspace name and <aws-region> by the AWS region where your Keyspaces instance is deployed (for example us-east-1, eu-west-1, ...).

    Note

    Be careful to always specify the compliancemode parameter with the value Liquibase to avoid any unexpected behaviour when running the changelog.

  2. Add the following property in the liquibase.properties file to activate the compatibility mode with Amazon Keyspaces:

    liquibase.cassandra.awsKeyspacesCompatibilityModeEnabled: true

    Tip

    For more information about the available options regarding the JDBC connection string for Amazon Keyspaces, please check the driver documentation.

Test connection

  1. Create a text file called changelog (.xml, .sql, .json, or .yaml) in your project directory and add a changeset.

    If you already created a changelog using the init project command, you can use that instead of creating a new file. When adding onto an existing changelog, be sure to only add the changeset and to not duplicate the changelog header.

    -- liquibase formatted sql

-- changeset my_name:1
CREATE TABLE test_table 
(
  test_id INT, 
  test_column INT, 
  PRIMARY KEY (test_id)
)

    <?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
  xmlns:pro="http://www.liquibase.org/xml/ns/pro"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
    http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
    http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">

  <changeSet id="1" author="my_name">
    <createTable tableName="test_table">
      <column name="test_id" type="int">
        <constraints primaryKey="true"/>
      </column>
      <column name="test_column" type="INT"/>
    </createTable>
  </changeSet>

</databaseChangeLog>

    databaseChangeLog:
  - changeSet:
    id: 1
    author: my_name
    changes:
    - createTable:
      tableName: test_table
      columns:
      - column:
        name: test_column
          type: INT
          constraints:
            primaryKey:  true
            nullable:  false

    {
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "my_name",
        "changes": [
          {
            "createTable": {
              "tableName": "test_table",
              "columns": [
                {
                  "column": {
                    "name": "test_column",
                    "type": "INT",
                    "constraints": {
                      "primaryKey": true,
                      "nullable": false
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

  2. Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

    liquibase status --username=test --password=test --changelog-file=<changelog.xml>

    Note

    You can specify arguments in the CLI or keep them in the Liquibase properties file.

    If your connection is successful, you'll see a message like this:

    1 changeset has not been applied to <your_jdbc_url>
Liquibase command 'status' was executed successfully.

  3. Inspect the SQL with the update-sql command. Then make changes to your database with the update command.

    liquibase update-sql --changelog-file=<changelog.xml>
liquibase update --changelog-file=<changelog.xml>

    If your update is successful, Liquibase runs each changeset and displays a summary message ending with:

    Liquibase: Update has been successful.
Liquibase command 'update' was executed successfully.

  4. From a database UI tool, ensure that your database contains the test_table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Now you're ready to start making deployments with Liquibase!