Skip to content
Star Us On GitHub

Using Liquibase with ScyllaDB

ScyllaDB is a high-performance NoSQL database that offers drop-in compatibility with Apache Cassandra. ScyllaDB implements the Cassandra Query Language (CQL) and uses the same wire protocol, making it fully compatible with the Liquibase Cassandra extension without any code modifications.

For more information about ScyllaDB, see the ScyllaDB Documentation.

Compatibility

ScyllaDB works seamlessly with the Liquibase Cassandra extension as a drop-in replacement for Apache Cassandra. All core Liquibase operations are supported, including:

  • Schema migrations (DDL operations)
  • Data manipulation (DML operations)
  • Changelog tracking
  • Distributed locking
  • Rollback functionality

For detailed compatibility information and test results, see the ScyllaDB Compatibility section in the extension repository.

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 ScyllaDB

  1. Using Docker (recommended for local development)

    ScyllaDB can be easily run using Docker:

    Standard setup: 

    docker run --name scylladb -p 9042:9042 -d scylladb/scylla --smp 1

    macOS setup (requires additional flag): 

    docker run --name scylladb -p 9042:9042 -d scylladb/scylla --reactor-backend=epoll --smp 1

    Note

    macOS users must include the --reactor-backend=epoll flag due to reactor backend requirements.

    Wait 15-20 seconds for ScyllaDB to fully initialize before connecting.

  2. Production deployments

    For production environments, follow the official ScyllaDB Installation Guide.

  3. Create your Keyspace

    Connect to ScyllaDB using cqlsh and create a keyspace:

    docker exec -it scylladb cqlsh

    CREATE KEYSPACE my_keyspace
  WITH REPLICATION = {
   'class' : 'SimpleStrategy',
   'replication_factor' : 1
  };

    The keyspace will be referenced in your Liquibase configuration as the schema.

Install drivers

ScyllaDB uses the same drivers and extension as Apache Cassandra. No ScyllaDB-specific drivers are needed.

Follow the installation instructions in the Apache Cassandra tutorial, which covers:

  • Downloading the Cassandra JDBC wrapper
  • Downloading the Liquibase Cassandra extension
  • Placing JAR files in the correct directory
  • Configuring the JDBC driver
  • Maven configuration (if applicable)

Database connection

Configure connection

ScyllaDB uses the same JDBC connection format as Apache Cassandra.

  1. Specify the database JDBC URL in the liquibase.properties file:

    url: jdbc:cassandra://<host>[:<port>]/<keyspace>?compliancemode=Liquibase&localdatacenter=<datacenter_name>

    Example for local Docker setup: 

    url: jdbc:cassandra://localhost:9042/my_keyspace?compliancemode=Liquibase&localdatacenter=datacenter1

  2. Configure credentials:

    username: cassandra
password: cassandra

    Note

    ScyllaDB uses cassandra/cassandra as default credentials. For production, configure appropriate authentication following the ScyllaDB Security Guide.

    Note

    Always specify the compliancemode=Liquibase parameter to ensure correct behavior.

    Tip

    For complete JDBC connection string options, see the 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!

Additional resources