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 > Under "Connect using an API, choose "Java" > 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 theconfig.json
file in a text editor and leave it open. We will use that information in this file later to configure our Liquibase project. - Clone this repository to set up CQL-Proxy which is a sidecar that enables unsupported CQL drivers to work with DataStax Astra.
- You need your Astra Token and Astra Database ID to use CQL-Proxy
- Follow the steps in the repo to spin up CQL-Proxy using Terminal/Command Line. Once successfully running, you should see the following output:
{"level":"info","ts":1651012815.176512,"caller":"proxy/proxy.go:222","msg":"proxy is listening","address":"[::]:9042"}
Tutorial
To create a Liquibase project with Cassandra on DataStax Astra on your machine, begin with the following steps:
- Create a new project folder and name it
LiquibaseProj
. - In your
LiquibaseProj
folder, create a new text file and name itdbchangelog.sql
. - Open the
dbchangelog.sql
file and update the changelog file with the following code snippet:
--liquibase formatted sql
- In your
LiquibaseProj
folder, create a new text file and name itliquibase.properties
. - Add the following properties to the newly created Liquibase properties file:
changelog-file: dbchangelog.sql
changelog-file: dbchangelog.sql
url: jdbc:cassandra://localhost:9042/test;DefaultKeyspace=test;TunableConsistency=6
driver: com.simba.cassandra.jdbc42.Driver
defaultSchemaName: test
liquibase.hub.mode=off
In the Liquibase liquibase.properties file, replace test with your own keyspace name
Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: liquibaseProLicenseKey: <paste code here>
- Add a changeset to the changelog – changeset are uniquely identified by
author
andid
attributes. Liquibase attempts to execute each changeset in a transaction that is committed at the end. In thedbchangelog.sql
file, add a new changeset with acreate table
statement. We will create a new table department using a changeset as follows: - Open the command prompt. Navigate to the
LiquibaseProj
directory.
Run the following command:liquibase update
- From a SQL Client User Interface, check your database changes. You should see a new department table added to the database. For example:
--liquibase formatted sql
--changeset bob:1
CREATE TABLE keyspace.DEPARTMENT (id int, NAME text, ACTIVE BOOLEAN);
SELECT * FROM "keyspace"."department";
ID | NAME | ACTIVE |
---|---|---|
NULL | NULL | NULL |
From a database UI tool, ensure that your database contains the table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.