Using Liquibase with Cassandra on DataStax Astra

The purpose of this document is to guide you through the process of creating a new Liquibase project with Cassandra. In this tutorial, you will generate an example project and follow the instructions to apply and learn concepts associated with creating new Liquibase projects with Cassandra on DataStax Astra.

Prerequisites

  • If you have not installed the latest version of Liquibase, navigate to https://www.liquibase.org/download to install Liquibase latest release.
  • Ensure the Liquibase install directory path is set to a location in the PATH System variable.
  • Navigate to https://downloads.datastax.com/#odbc-jdbc-drivers and download the Simba jdbc jar driver file for Apache Cassandra.
  • Navigate to https://github.com/liquibase/liquibase-cassandra/releases/ and download the liquibase-cassandra-<version>.jar latest release extension jar file.
  • Place the two jar files in the liquibase/lib install directory.
  • Log into your DataStax Astra account from the following URL https://astra.datastax.com/. From Dashboard click connect on the desired Database > download the Connect Bundle by clicking the link in step 1 under Prerequisites.
  • Once the secure-connect-<dbname>.zip is fully downloaded, place it somewhere in a secure place in your file system.
  • Unzip the secure-connect-<dbname>.zip file. Open the config.json file in a text editor and leave it open. We will use that information in this file later to configure our Liquibase project.

Tutorial

To create a Liquibase project with Cassandra on DataStax Astra on your machine, begin with the following steps:

  1. Create a new project folder and name it LiquibaseProj.
  2. In your LiquibaseProj folder, create a new text file and name it dbchangelog.sql.
  3. Open the dbchangelog.sql file and update the changelog file with the following code snippet:
--liquibase formatted sql
  1. In your LiquibaseProj folder, create a new text file and name it liquibase.properties.
  2. Edit the liquibase.properties file to add the following properties:
  3. changeLogFile: dbchangelog.sql
    url: jdbc:cassandra://host:port/keyspace;AuthMech=2;UID=username;PWD=password;SecureConnectionBundlePath=path/to/secure-connect-database_name.zip;TunableConsistency=6
    username: username
    password: password
    driver: com.simba.cassandra.jdbc42.Driver
    defaultSchemaName: keyspace
    

In liquibase.properties above, please replace host, keyspace and port with the values from your config.json file. Replace UID, PWD, username and password with real username and password. Finally replace path/to/secure-connect-database_name.zip with the path to your secure connect zip file (double slashes for Windows).

Note: If you already have a Liquibase Pro key and want to apply it to your project, add the following property to your liquibase.properties. Ex: liquibaseProLicenseKey: <paste code here>.

  1. Add a changeset to the changelogchangeset are uniquely identified by author and id attributes. Liquibase attempts to execute each changeset in a transaction that is committed at the end. In the dbchangelog.sql file line 3 add a new department create table changeset as follows:
  2. 
    --liquibase formatted sql
    
    --changeset bob:1
    CREATE TABLE keyspace.DEPARTMENT (id int, NAME text, ACTIVE BOOLEAN);
  3. Open the command prompt. Navigate to the LiquibaseProj directory.
    Run the following command: liquibase update
  4. From a SQL Client User Interface, check your database changes. You should see a new department table added to the database. For example:
SELECT * FROM "keyspace"."department";
ID NAME ACTIVE
NULL NULL NULL

Also, you should see two more tables:

  • DATABASECHANGELOG tracking table – This table keeps a record of all the changesets that were deployed. This way, next time when you deploy again, the changesets in the changelog will be compared with the DATABASECHANGELOG tracking table and only the new changesets that were not found in the DATABASECHANGELOG will be deployed. You will notice that a new row was created in that table with the changeset information we have just deployed. For this example:
ID AUTHOR FILENAME DATEEXECUTED ORDEREXECUTED EXECTYPE MDSUM
1 bob dbchangelog.sql date&time 1 EXECUTED checksumvalue
  • DATABASECHANGELOGLOCK – This table is used internally by Liquibase to manage access to the changelog table during deployment.