Skip to content
Star Us On GitHub

Using Liquibase with Apache Cassandra

Verified on: December 7, 2023

Apache Cassandra is an open source, distributed, NoSQL database. It presents a partitioned wide column storage model with consistent semantics.

For more information, see the Apache Cassandra page.

Supported database versions

The extension's JDBC wrapper uses the Java Driver for Apache Cassandra® which is designed for:

  • Apache Cassandra® 2.1+
  • DataStax Enterprise (5.0+)

It will throw "unsupported feature" exceptions if used against an older version of Cassandra cluster.

For more information, please check the compatibility matrix and read the driver 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 Apache Cassandra

  1. Configure the Apache Cassandra environment

    1. Ensure your Cassandra database is installed and configured.

      For more information, see the Installing Cassandra documentation.

    2. If you have Cassandra tools installed locally, check the status of Cassandra

      $ bin/nodetool status

      The status column in the output should report UN, which stands for "Up/Normal":

      # nodetool status

Datacenter: datacenter1
=======================
Status=Up/Down
| / State=Normal/Leaving/Joining/Moving
-- Address    Load        Tokens  Owns (effective)  Host ID                               Rack
UN 172.18.0.6 198.61 KiB  276     100.0%            5rtc74d1-237f-87c0-88eb-72643bd0a8t7  rack1

    3. Create your Keyspace

      The Keyspace will be referenced later in the Liquibase changelog as the schema when managing objects in the datastore.

Install drivers

All users

To use Apache Cassandra with Liquibase, you need to install two additional JAR files.

Note

These instructions assume Liquibase Cassandra extension v4.25.0.1 or newer. This extension was updated to replace the previous Simba JDBC driver with the new Cassandra JDBC wrapper.

  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.11.0</version>
</dependency>
<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-cassandra</artifactId>
    <version>4.25.0.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.

    url: jdbc:cassandra://<host1>[:<port1>][...--<hostN>[:<portN>]]/<keyspace>?compliancemode=Liquibase[&localdatacenter=<datacenter_name>]

    Note

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

    Tip

    For more information, see the specifying Cassandra JDBC connection strings 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!