Priam is the sidecar process that runs next to Cassandra and does the dull work

A co-process, not a library

Priam is a process and tool that runs alongside Apache Cassandra to automate a specific list of things: backup and recovery, complete and incremental, token management, seed discovery, configuration, and support for the AWS environment.

The co-process model is the design decision that everything else follows from. Priam is not a library your application calls, it is a sidecar on every node that talks to the cluster, does the work on a schedule, and exposes the results over HTTP. That is why there is a web module, a REST API, and a configuration file that is shared across the cluster rather than per application.

The name is a piece of history. Priam refers to the King of Troy in Greek mythology, who was the father of Cassandra, and the project is described as actively developed and used at Netflix.

Apache Cassandra itself is characterised in the readme as a highly available, column oriented database, and that framing explains why the tool exists at all. A distributed database with its own token ring does not have a single place where a backup is taken, and its configuration is spread across every node. Doing either of those things properly needs something that knows the topology, and that is Priam.

The implementation is Java, the licence is Apache-2.0, and the default branch is 4.x.

What the sidecar actually automates

The five areas from the overview are worth unpacking, because two of them are not things most people expect a backup tool to do.

Backup and recovery, complete and incremental, is the headline. Token management is the second, and it is the one that only makes sense for Cassandra. In a distributed database the tokens decide which node owns which slice of the ring, and a token change is a coordinated operation across the whole cluster. Doing it by hand is how you get an unbalanced cluster, and a cluster that is unbalanced is a cluster where a single node is a hot spot.

Seed discovery is the third. When you add a node to a Cassandra cluster, the new node needs to be told where the existing data is before it can take part. That is a bootstrap problem, and automating it removes a step that is easy to get wrong under pressure.

Configuration is the fourth, and here the README is more specific than the word suggests. The features list mentions support for multi-region Cassandra deployment in AWS via public IP, and automated security group update in a multi-region environment. The second of those is a security control that updates itself, which matters because a Cassandra cluster in EC2 whose security groups drift from the topology is a cluster with an unintended path in.

The fifth is the AWS support itself, which is the boundary of the project. Priam is built for Cassandra running in EC2, not for Cassandra in general.

Backup internals: SSTables to S3, compressed on the fly

The backup mechanism is described in the features list, and it is specific.

Backup SSTables from local ephemeral disks to S3. The source is the local disk, and the destination is object storage, which is what makes the backup durable and what makes it survive the instance.

Uses Snappy compression to compress backup data on the fly. So the data is compressed as it is written rather than afterwards, which means the bytes on the wire to S3 are already compressed and there is no second pass over the data.

Backup throttling is the third of the group, and it is the one that shows the tool has been run in production. A node with a fast disk and a fast link can saturate the network it shares with the rest of the cluster, and a backup that starves the live traffic is worse than no backup. Throttling turns the backup into something a cluster can tolerate.

Around those there are APIs to list and restore backup data, and REST APIs for backup and restore and other operations. The distinction between the two is worth noticing, because one of them is the safe path and the other is the automation path. A human-facing API for browsing what backups exist is a different thing from the endpoint a script calls to trigger a restore.

Pluggable modules for future enhancements, with support for multiple data storage, is the extension point. The wording says future enhancements, which tells you the module system exists but that the set of storage backends is still small.

Token management backed by SimpleDB

The first item on the features list is token management using SimpleDB, and that detail says a lot about the design.

SimpleDB is an AWS service, and it is a deliberately boring place to keep a small amount of state. Using it means the token metadata for the cluster lives outside the cluster, in a service that is available when a node is being replaced and when the cluster itself is in pieces.

That is the whole point. A token assignment that is stored only on the cluster is a token assignment you cannot recover when the cluster is broken, and the recovery scenario is exactly when you need it. A small, highly available, external store for the ring metadata is what makes the automated token movement safe to attempt.

It also means the design is not portable. Priam assumes a place to keep that state, and the assumption is an AWS service, so running the tool in another environment is not a supported configuration even if the backup half would work there.

The multi-region support follows from the same assumption. Deploying Cassandra across regions in AWS means nodes talking to each other over public IP addresses, which means the security groups have to permit exactly the right traffic between regions, and the automated security group update in a multi-region environment is what keeps that configuration in step with a topology that changes as nodes come and go.

Two branches, two Cassandra generations

The Important Notice at the top of the readme is short and it is the most important thing for anyone evaluating the project.

Priam 3.11 branch supports Cassandra 3.x, and Netflix internally uses Apache Cassandra 3.0.19.

So the branch structure mirrors the Cassandra versions rather than the Priam versions, and the default branch in the repository is 4.x while the build badge points at the 4.x branch and the Travis badge variant points at 3.11. The release list makes the same split visible. v3.1.133 came on 2026-09-18 with the note that it removes Astyanax and makes cass_turtle start, v4.1.33 on 2026-06-01 prohibits using a reusable ByteBuffer for compressed backups, and v3.1.132 on 2026-02-24 ensures backup grooming works in the local bootstrap case.

Two things stand out in those release notes. The first is that a 3.x release removes a client library, which suggests the older branch is being pruned of dependencies that no longer work with a current Cassandra. The second is that the 4.x branch spends a release on a rule about buffer reuse, which is the kind of change that only matters when you are moving compressed data through a shared buffer and a bug there corrupts a backup.

The practical consequence is that you pick the branch that matches your Cassandra version and stay there, and that the tool is versioned against the database rather than independently.

The repository is several modules and a Gradle build

The top level listing shows how the pieces are arranged, and it is a conventional multi-module Gradle project.

There is build.gradle and settings.gradle at the root, with the gradlew and gradlew.bat launchers and a gradle/ directory, so the build is the standard Gradle wrapper setup.

The modules are named after what they do. priam/ is the core, the sidecar itself. priam-web/ is the web layer, which is the part that serves the REST APIs and the configuration interface. Then there are two extension modules that follow the pattern of the Cassandra ecosystem: priam-cass-extensions/ and priam-dse-extensions/, the latter being for DataStax Enterprise.

The separation between priam and priam-web is the one that matters operationally. The core is the thing that talks to Cassandra and does the backups, and the web module is the thing that answers HTTP. Splitting them means the control plane and the data plane can be reasoned about separately, and it is what lets the same core serve a REST API, a command line and whatever the cluster management tooling ends up needing.

There is also a codequality/ directory, which is a separate configuration for static analysis rather than part of the build itself, plus the images/ directory for the logo and a CHANGELOG.md that the readme points to, along with a LICENSE file and a .github/ directory.

Most of the documentation lives outside the repository

The readme is a summary, and it says so by pointing elsewhere for everything that matters operationally.

Compatibility is at netflix.github.io/Priam/#compatibility, installation is at the setup page, and cluster management, described as basic configuration and REST APIs to manage the Cassandra cluster, is at the management page. The wiki link at the top of the readme goes to the same site.

That arrangement is common for a project that has been running inside a large organisation for years, where the knowledge has accumulated in a wiki rather than in the repository. The cost is that a reader without internet access, or a reader who wants the version history of a configuration option, has to work without it.

The repository does carry one document of its own, the CHANGELOG.md, and the release notes are the richest part of what the git history tells you, since the release titles are specific about behaviour. Three of them in the recent list are about a client library removal, a buffer reuse prohibition for compressed backups, and backup grooming in the local bootstrap case, which is the level of detail you would want in a changelog for a tool that writes your backups.

So the practical reading order is the readme for the shape, the release notes for the behaviour, and the wiki for the configuration, which is a slightly inverted order from the one most people would choose.

Editorial conclusion

Adopt Priam when you run Cassandra on AWS and want backup, token management and seed discovery automated rather than scripted, and you are willing to operate a sidecar process per node. Do not adopt it if you run Cassandra anywhere other than EC2, since the AWS-specific behaviour is built in rather than optional. Verify first which branch matches your Cassandra version, because the 3.11 branch supports Cassandra 3.x while the default branch is 4.x, and that you can reach the installation and cluster management documentation, since the README defers both to the externally hosted wiki.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Netflix/Priam on GitHub
4. README
5. Releases