Using Liquibase with Cassandra
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 versions
- 4.X
- 3.11.X
Prerequisites
- Introduction to Liquibase – Dive into Liquibase concepts.
- Install Liquibase – Download Liquibase on your machine.
- Get Started with Liquibase – Learn how to use Liquibase with an example database.
- Design Your Liquibase Project – Create a new Liquibase project folder and organize your changelogs
- How to Apply Your Liquibase Pro License Key – If you use Liquibase Pro, activate your license.
Install drivers
To use Liquibase and Apache Cassandra, you need two JAR files: a JDBC driver and the Liquibase Cassandra extension:
- Download the Simba JDBC driver JAR
file and select Simba JDBC Driver for Apache Cassandra from the dropdown menu. Select the default
package option unless you need a specific package. The driver downloads as a ZIP file named
SimbaCassandraJDBC42-x.x.x.zip
. - Extract the
CassandraJDBCxx.jar
file and place it in theliquibase/lib
directory. - Open the Liquibase properties file and specify the driver, as follows:
- Go to the liquibase-cassandra
repository and download the latest released Liquibase extension JAR file:
liquibase-cassandra-version.jar
.
driver: com.simba.cassandra.jdbc42.Driver
Place your JAR
file(s) in the liquibase/lib
directory.
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.datastax.jdbc</groupId>
<artifactId>CassandraJDBC42</artifactId>
<version>4.2</version>
<scope>system</scope>
<systemPath>${basedir}/lib/CassandraJDBC42.jar</systemPath>
</dependency>
<dependency>
<groupId>org.liquibase.ext</groupId>
<artifactId>liquibase-cassandra</artifactId>
<version>4.20.0</version>
</dependency>
You need to specify that the scope is system
and provide the systemPath
in
pom.xml
. In the example, the ${basedir}/lib
is the location of the driver JAR file.
Test your connection
- Ensure your Cassandra database is configured. If you have Cassandra tools locally and want to check
the status of Cassandra, run
$ 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 |
Note: For more information, see the Installing Cassandra documentation.
- Specify the database 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. You can either specify the full database connection string or specify the URL using your database's standard JDBC format:
url: jdbc:cassandra://localhost:9042/myKeyspace;DefaultKeyspace=myKeyspace
Tip: To
apply a Liquibase Pro key to your project, add the
following property to the Liquibase properties file:
licenseKey: <paste code here>
- Create a text file called changelog
(
.xml
,.sql
,.json
, or.yaml
) in your project directory and add a changeset. - Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:
- Inspect the SQL with the update-sql command. Then make changes to your database with the update command.
- From a database UI tool, ensure that your database contains the
test_table
you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.
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.
<?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="Liquibase">
<createTable tableName="test_table">
<column name="test_id" type="int">
<constraints primaryKey="true"/>
</column>
<column name="test_column" type="varchar"/>
</createTable>
</changeSet>
</databaseChangeLog>
SQL example
-- liquibase formatted sql
-- changeset liquibase:1
CREATE TABLE test_table (test_id INT, test_column VARCHAR(255), PRIMARY KEY (test_id))
Tip: Formatted
SQL changelogs generated from Liquibase versions before 4.2 might cause
issues because of the lack of space after a double dash ( --
). To fix this, add a space
after the double dash. For example: -- liquibase formatted sql
instead of --liquibase
formatted sql
and -- changeset myname:create-table
instead of --changeset
myname:create-table
.
databaseChangeLog:
- changeSet:
id: 1
author: Liquibase
changes:
- createTable:
tableName: test_table
columns:
- column:
name: test_column
type: INT
constraints:
primaryKey: true
nullable: false
JSON example
{
"databaseChangeLog": [
{
"changeSet": {
"id": "1",
"author": "Liquibase",
"changes": [
{
"createTable": {
"tableName": "test_table",
"columns": [
{
"column": {
"name": "test_column",
"type": "INT",
"constraints": {
"primaryKey": true,
"nullable": false
}
}
}
]
}
}
]
}
}
]
}
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:
4 changesets have not been applied to <your_jdbc_url>
Liquibase command 'status' was executed successfully.
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.
Now you're ready to start making deployments with Liquibase!
Related links
- Get Up and Running with Liquibase and Apache Cassandra
- Change Types
- Concepts
- Liquibase Commands
- Workflows
Created: April 26, 2023