Skip to content
Star Us On GitHub

Using Liquibase with DataStax Astra DB (powered by Apache Cassandra)

DataStax Astra DB is a multi-cloud DBaaS built on Apache Cassandra. Astra DB simplifies cloud-native Cassandra application development and reduces deployment time from weeks to minutes. For more information, see DataStax Astra DB 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 DataStax Astra DB

  1. Configure the DataStax Astra DB database environment:
    1. Log into your DataStax Astra DB account.
      1. From Dashboard, select the needed database
      2. Go to the Connect tab.
      3. Under Connect using an API, select Java
      4. Download the Connect Bundle by following the link in step 1 under Prerequisites.
    2. Once the secure-connect-<dbname>.zip file is fully downloaded, place it in a secure place in your file system.

Install drivers

All users

To use Liquibase and Cassandra on DataStax Astra DB, you need two JAR files: a JDBC driver and the Liquibase Cassandra extension:

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.

    To configure the JDBC URL, you will need the following information:

    • secureconnectbundle: the fully qualified path of the cloud secure connect bundle file
    • keyspace: the keyspace to connect to
    • user: the username
    • password: the password (if you are using a token, you can specify it here and set user value to token)

    Please specify the URL using this JDBC format:

    url: jdbc:cassandra:dbaas:///<keyspace>?compliancemode=Liquibase&secureconnectbundle=<bundle_name>&user=token&password=<token>

    Replace <keyspace> with your own keyspace name, <bundle_name> by the real location of your secure connect bundle, and the password <token> value with your Astra DB token.

    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 about the available options regarding the JDBC connection string for Astra DB, 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!