scylla-migrate

README

Scylla-Migrate 🚀

A low-latency, schema-agreement-aware database migration CLI tool for ScyllaDB and Apache Cassandra, built in Go.

Scylla-Migrate is designed to handle schema migrations safely by verifying 100% Schema Agreement across all active nodes in the cluster before and after each migration step, preventing read/write inconsistencies or partial-agreement states.

---

✨ Features

• Node-by-Node Schema Agreement Verification: Automatically polls system tables (system.local and system.peers) to confirm that all nodes share the same schema version UUID before proceeding.
• ScyllaDB 6.0+ Tablet Support: Configured out-of-the-box to handle tablet replication constraints when using SimpleStrategy in single-node or local development settings.
• Cobra-Powered CLI: Features a structured, nested subcommand interface (init, create, up, down, status) with configuration file support and flag overrides.
• Failed Migration Safety: Automatically marks a migration version as failed in the metadata tracking table if a statement fails, preventing subsequent migration runs until manual validation is performed.

---

🛠️ Architecture

graph TD
    CLI[scylla-migrate CLI] -->|1. Check Agreement| DB_Client[db.Client]
    DB_Client -->|Query system.local & system.peers| Nodes[Cluster Nodes]
    CLI -->|2. Run CQL queries| DB_Client
    CLI -->|3. Register State| Migrate_Table[schema_migrations table]
    Migrate_Table -->|4. Re-Verify Agreement| Nodes

---

📦 Installation

To install the CLI globally on your machine, run:

go install github.com/nedunchezhiyan2002/scylla-migrate@latest

---

💻 Local Developer Workflow

1. Initialize Workspace

Run the initialization command in the root of your project:

scylla-migrate init

This generates:

• A migrations/ directory to store your CQL files.
• A default scylla-migrate.yaml configuration file.

2. Configure Your Database Connection

Open scylla-migrate.yaml and configure your database parameters:

hosts:
  - 127.0.0.1
port: 9042
keyspace: my_keyspace
dir: migrations

3. Create a New Migration Pair

Generate timestamped up and down migration templates:

scylla-migrate create "create_users_table"

This creates:

• migrations/<timestamp>_create_users_table.up.cql (Write table/column creation queries here)
• migrations/<timestamp>_create_users_table.down.cql (Write rollback/drop queries here)

4. Run Up Migrations

Apply all pending CQL migration files:

scylla-migrate up

5. Check Database Migration Status

View migration history and inspect cluster diagnostics:

scylla-migrate status

6. Roll Back the Last Migration

To revert the last applied migration:

scylla-migrate down

To roll back all migrations, add the --all flag:

scylla-migrate down --all

---

📄 License

This project is licensed under the MIT License.