Welcome to Cassper, Cassandra migrations made easy

Pramod Shehan
3 min readMay 27, 2020



  • 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.


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.


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


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

WITH replication = {
CREATE TYPE IF NOT EXISTS mykeyspace.transaction (
execer TEXT,
id TEXT,
actor TEXT,
message_type TEXT,
message TEXT,
digsig TEXT,
timestamp TIMESTAMP


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


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


Cassper can be used in Java and scala

  1. First add Cassper as dependency
  • Maven
  • SBT
libraryDependencies += "io.github.dataoperandz" % "cassper" % "0.3"


2) Use keyspace name as parameter

val builder = new Cassper().build("keyspace", session)
  • session- com.datastax.driver.core.Session
  • keyspace- keyspace name

3) Uses keyspace of session

val builder = new Cassper().build(session)

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.

We can not change existing script files in Cassper. It will end up with exception because it is checked checksum of the all the files

Cassper Github repository