Welcome to Cassper, Cassandra migrations made easy

3 min readMay 27, 2020

Overview

Cassper is a database migration tool. It strongly favors simplicity and convention over configuration.
Migrations can be written in CQL . All the CQL database syntax are supported. You can use the Maven plugin.
Supported database is Cassandra.
Written in Scala.

Migration

Cassper is supported for versioned migrations. Versioned migrations have a version, a checksum, a description and etc. The version must be unique.

The description is purely informative for you to be able to remember what each migration does.

The checksum is there to detect accidental changes.

They are applied in order exactly once.

Features

Creating/altering/dropping tables/UDT
Reference data updates
User data corrections

Samples

These are two samples we can do a migration using Cassper.

CREATE KEYSPACE IF NOT EXISTS mykeyspace
WITH replication = {
'class':'NetworkTopologyStrategy',
'DC1':'1'
};CREATE TYPE IF NOT EXISTS mykeyspace.transaction (
  execer TEXT,
  id TEXT,
  actor TEXT,
  message_type TEXT,
  message TEXT,
  digsig TEXT,
  timestamp TIMESTAMP
);

Naming

In order to be picked up by Cassper, CQL migrations must comply with the following naming pattern:

The file name consists of the following parts:

Prefix- V for versioned.
Version- Cassper has two versions.

Examples- 1_1 , 1_2, 2_1, 2_2 ………….. 400_1

Seperator1- This is used to seperate version and prefix.
Seperator2- This is used to seperate version and description.
Description- Underscores separate the words.

Examples- Add_new_keyspace, initialization, Create_table

Suffix- .cql

Examples for naming-

V_1_1__my_create_keyspace.cql
V_1_2__my_create_udt.cql
V_1_3__my_create_tables.cql

Discovery

Cassper discovers all the migration files within cassper directory inside resources.

Usage

Cassper can be used in Java and scala

First add Cassper as dependency

Maven

<dependency>
  <groupId>io.github.dataoperandz</groupId>
  <artifactId>cassper</artifactId>
  <version>0.3</version>
</dependency>

libraryDependencies += "io.github.dataoperandz" % "cassper" % "0.3"

https://mvnrepository.com/artifact/io.github.dataoperandz/cassper

2) Use keyspace name as parameter

val builder = new Cassper().build("keyspace", session)
builder.migrate("keyspace")

session- com.datastax.driver.core.Session
keyspace- keyspace name

3) Uses keyspace of session

val builder = new Cassper().build(session)
builder.migrate("keyspace")

How it works

When we use Cassper, it is created table called “schema_version”

Scripts are running ascending order by using version of the file. So we must use correct version when adding the new script file. Always it should be greater than existing latest version.