Phalanx (2023)

Around 2023 I fell down a pretty deep time series database rabbit hole. I had been reading about how Discord, Netflix, and a few other big names were stuffing absurd volumes of timestamped data into Cassandra, and I got really curious about whether the wide-column model was actually as nice for time series workloads as everyone claimed. So I spent a few weeks prototyping schemas, running benchmarks against a local cluster, and generally messing around with CQL.

Pretty quickly I hit a wall that had nothing to do with time series: I wanted versioned, repeatable schema migrations, and every tool I could find was written in Java or Python. Flyway is great if you live in the JVM, but I was prototyping in Swift and didn’t want to drag a whole separate toolchain into my project just to manage CREATE TABLE statements. I had also been wanting an excuse to play with Apple’s open source Cassandra client library. So I wrote Phalanx.

It’s a small command line tool. migrate applies your versioned .cql files in order, clean drops the keyspace so you can start over. The ergonomics are shamelessly cribbed from Flyway, because Flyway got most of them right.

A few opinionated design choices

A few things I picked that aren’t necessarily obvious from the outside:

• One keyspace per invocation. Multi-keyspace setups just run Phalanx multiple times with different config files. I considered baking multi-keyspace support into the tool itself, but it complicated the mental model way more than it was worth.
• Version 0 is reserved for keyspace creation. It’s a chicken-and-egg problem — you can’t USE a keyspace that doesn’t exist yet — so carving out version 0 for the CREATE KEYSPACE statement keeps it cleanly separated from the rest of the migration flow.
• One CQL command per migration file. Cassandra doesn’t give you transactions across statements, so a multi-statement migration that partially fails leaves you in a really annoying half-applied state with no great way to recover. Forcing one command per file makes the unit of failure unambiguous.
• $${{KEYSPACE}}$$ placeholder substitution. So you can write a migration once and run it against differently-named keyspaces per environment without copy-pasting files.

My time series obsession faded after a couple months and I ended up moving on to other things, but Phalanx was a fun little side effect. Source on github.