How to Configure Cosmos DB Schema Migration

Published
Length
3 min read

Luis Felipe Dias

All posts

You run a cosmos db schema migration by adding version fields to documents. Then you update old items in the background or when your app reads them. Since this database does not force a fixed table shape, your app code manages the structure. Teams often use a single shared master key to run these big update scripts. Still, broad permissions let a bad script ruin live items across every container at once. How a cosmos db schema migration works in practice In a document database, items in the s

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 run a cosmos db schema migration by adding version fields to documents. Then you update old items in the background or when your app reads them. Since this database does not force a fixed table shape, your app code manages the structure. Teams often use a single shared master key to run these big update scripts. Still, broad permissions let a bad script ruin live items across every container at once.

How a cosmos db schema migration works in practice

In a document database, items in the same container can have different fields. You do not lock a table to add a column like in relational systems. Instead, your team updates the app code to handle both old and new document shapes. Putting a version number on each document helps the app know which shape it is reading.

You have two main ways to move data to the new version. The first way is a lazy update during normal app reads. When the app reads an old document, it converts the fields and writes the item back. This spreads the work over time and saves database capacity for active users.

The second way is a batch update using the native change feed. A background worker reads items from the container, updates their structure, and saves them back. You must watch your request units during a batch run so you do not slow down live traffic. If a migration changes the partition key, you must copy items into a brand new container.

Choosing between lazy updates and background jobs

Lazy updates work well when you only rename a field or set a default value. You do not pay extra request units to rewrite cold records that nobody ever reads. The downside is that your app code must keep supporting old versions for a very long time.

Background jobs are better when every single document must match the new shape right away. Analytics tools and search indexes often need uniform fields across the whole container. Before you start a batch job, check your container size and set a safe rate limit. Running the job during slow traffic hours prevents sudden errors for your main app.

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 what they leave open

Azure provides role-based rules to control who can manage accounts and containers. You can assign a data role to a worker identity instead of sharing primary account keys. This setup stops unauthorized users from deleting whole databases or changing network rules.

Still, native data roles still decide who logs in, not what individual statements do in flight. Once an engineer or script gets write permissions on a container, it can read or overwrite every field. Native roles cannot rewrite sensitive fields like emails, phone numbers, card numbers, or national IDs in query results. They also cannot pause a risky batch update for human approval right before it runs.

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

How do you change a partition key during a migration?

You cannot change the partition key of an existing container in place. You must create a new container and use the change feed to copy all items over.

How do you avoid hitting rate limits during a batch update?

Spread your background writes over time and cap the throughput your worker script uses. You can also raise the container limit for a few hours while the job finishes.

Should engineers use primary account keys to run migration scripts?

No, primary keys grant full control over every container and are hard to rotate. Use short-lived identity tokens and limit each job to the exact container it needs.

The query runs. The emails stay hidden.