How to Configure ScyllaDB Schema Migration

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a scylladb schema migration by running versioned query files in order. A migration tool tracks each change in a dedicated table inside your cluster. Most teams run these updates from an automated deployment pipeline. They often use a shared admin role so every script can create or alter tables. When that role has broad permissions, one bad script can drop production data. How a native scylladb schema migration works ScyllaDB stores structure definitions across all nodes in the clus

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up a scylladb schema migration by running versioned query files in order. A migration tool tracks each change in a dedicated table inside your cluster. Most teams run these updates from an automated deployment pipeline. They often use a shared admin role so every script can create or alter tables. When that role has broad permissions, one bad script can drop production data.

How a native scylladb schema migration works

ScyllaDB stores structure definitions across all nodes in the cluster. When you change a keyspace or table, the cluster shares that update with every node. You must run schema changes one by one to avoid conflicts across the ring.

To manage this, teams use a migration runner alongside their code repo. You write each schema change as a numbered query file in source control. Next, you create a dedicated database role for the migration runner. You grant this role permissions to alter keyspaces, create tables, and read system metadata.

When the runner starts, it logs in with that role and checks a tracking table. That tracking table lists every file that ran in past deployments. The runner compares your code files against the tracking table rows. It then runs only the new files in strict order. Before moving to the next file, the runner waits for all nodes to agree. This step prevents schema mismatches when multiple nodes update at the same time.

Where native database roles fall short in practice

Native roles in ScyllaDB work well for basic login checks. You can pick which role can alter a keyspace or read a specific table. This setup blocks unauthorized users from logging in to the cluster at all. It also separates normal app traffic from admin tasks that alter tables.

Still, native roles only check permissions at the table or keyspace level. They cannot inspect the exact intent of a query while it runs in flight. A role that can add a new column can often drop a column too. If a developer needs to fix a stuck migration, they often use this admin role. Once logged in, nothing stops an accidental table drop or a bulk read of data.

End-to-End Encryption + API Schema Validation: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Shared pipeline credentials also make auditing very hard for security teams. Database logs show the shared role name instead of the person who ran the command. Also, anyone using that role to check a failed run can query raw user rows. Native permissions do not rewrite sensitive fields like emails, phone numbers, or card numbers. Teams end up choosing between slow manual reviews and risky direct sessions.

Best practices for safer schema updates

You should keep schema changes separate from normal data updates whenever possible. Mixing table alterations and heavy writes in one step can overload the cluster. Instead, run structural changes first and update row data in a later job.

Always test new migration files against a staging cluster before production runs. Check that every node reaches schema agreement after each single statement finishes. You should also remove direct admin credentials from developer laptops. When engineers must inspect production tables, require approval for individual statements and mask sensitive fields.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits inline in the protocol beside the service as an open-source proxy, a sidecar for your database or API. On every production query an agent or human runs, hoop.dev decides whether to pass, mask, block, or escalate it for review.

Before a query runs, hoop.dev guardrails check the statement against your rules, an AI Analyzer you configure can score intent or hold risky calls for human approval, and hoop.dev data masking rewrites sensitive fields in responses in memory. Explore the MIT-licensed project on GitHub.

Frequently asked questions

Why should scylladb schema migration steps run one at a time?

ScyllaDB copies schema changes across every node in the cluster ring. Running two changes at once can cause conflicting table definitions across different nodes. Waiting for schema agreement between statements keeps the cluster state consistent.

What database permissions does a migration runner need?

The runner needs permissions to create, alter, and drop tables in the target keyspace. It also needs read and write permissions on the tracking table that logs past runs.

How do you fix a failed schema migration in ScyllaDB?

First, check the cluster status to ensure all nodes agree on the current schema. Then, inspect the tracking table to see which file failed during the run. You can apply a forward fix script to complete the change and update the log.

The query runs. The emails stay hidden.