How to Configure Couchbase Schema Migration

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a couchbase schema migration by running versioned scripts that update buckets, scopes, collections, and documents. You track each applied script in a dedicated metadata collection so changes run once. Most teams give a build runner a shared admin role to run these updates. Broad roles create huge risk because one bad script can drop live data. How a couchbase schema migration workflow operates Document databases do not force a strict table layout by default. Yet apps still depend o

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 couchbase schema migration by running versioned scripts that update buckets, scopes, collections, and documents. You track each applied script in a dedicated metadata collection so changes run once. Most teams give a build runner a shared admin role to run these updates. Broad roles create huge risk because one bad script can drop live data.

How a couchbase schema migration workflow operates

Document databases do not force a strict table layout by default. Yet apps still depend on clear field names, data types, and indexes. A couchbase schema migration brings order to these changing data structures over time. Teams store change files in source control right next to their app code.

Each file holds a version number, a clear name, and the query steps. When a deployment starts, the runner reads a state document inside the cluster. This state document lists every version that ran in the past. The runner compares the folder of files against that stored state list.

It then runs only the new files in strict numeric order. A typical run might create a new scope or add a collection. Another step might build a secondary index or update fields across old JSON documents. Once a step finishes, the runner writes a new record to the state collection.

Planning document updates and index changes

Structural changes and data changes need different care during a release. Creating a new collection is fast and rarely slows down live traffic. Updating millions of existing JSON documents takes much more cluster compute and disk work. Teams split structure creation and bulk document updates into separate version files.

You can also use rolling updates for document shape changes. In this pattern, the app code learns to read both old and new fields. When a user saves a record, the app writes the new document shape. A background job then updates the remaining old records during quiet hours.

Index updates also require careful timing during a release. Building a large index on a busy collection can spike CPU and memory usage. Teams often defer index building so several indexes build together in one scan. This simple habit keeps query speeds steady for active users during deployments.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native roles solve and where gaps remain

Couchbase includes role-based access control to limit what users and apps can do. You can scope a role down to a single bucket, scope, or collection. You can also split roles between data readers, data writers, and cluster admins. This native setup works well for normal app traffic.

Still, a migration runner needs elevated privileges to create collections, build indexes, and alter data. Native roles decide who can log in and which buckets they can touch. They do not inspect what individual statements or queries do in flight. If a human or script logs in with that high role, every command runs.

A flawed script can delete a whole collection or overwrite sensitive fields across a bucket. Also, engineers who debug failed runs often query live records directly. Those records frequently hold raw emails, phone numbers, card numbers, or national IDs. Without query-level checks and field masking, broad migration roles leave production data exposed.

Check database and API queries on the wire

Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev sits inline in the wire protocol beside those services as an open-source proxy, a sidecar for your Postgres or API. On every query an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.

Frequently asked questions

Why does a schemaless database like Couchbase need schema migrations?

Apps still expect specific JSON fields, scopes, collections, and indexes to exist at runtime. Versioned update steps make sure every cluster has the exact structure the code needs.

How do you handle rollbacks if a migration script fails?

You write a matching down script that reverses the structural or document change. For bulk data changes, teams test on staging first and take a backup before running.

Should the app or a separate job run schema updates?

Run schema updates in a separate deployment step rather than inside the starting app. This prevents multiple app instances from racing to run the same update at once.

The query runs. The emails stay hidden.