Cosmos DB schema migrations with DBLift

Cosmos DB schema migrations with DBLift are Python files that change containers, indexing, throughput and documents. DBLift uses the Azure Cosmos DB for NoSQL API through the azure-cosmos SDK. It does not use the MongoDB API or vCore. MongoDB is a separate engine. DBLift does not copy data between databases.

The engine is open source and needs no licence. Settings for Cosmos DB schema migrations are on the engine page. Before you apply, check pending database migrations with info and validate. The dry-run tutorial shows that flag on SQL engines. The notes below match DBLift 4.11.1. This page shows the commands and the migration file, and it does not include command output.

Step 1: Install Cosmos DB schema migrations

pip install "dblift[cli,analysis,cosmosdb]"

Set the engine type to cosmosdb.

Step 2: Configure the account for Cosmos DB schema migrations

Config keys are account_endpoint (or url), account_key (or password), database_name (or database), and use_managed_identity.

Environment variables are DBLIFT_DB_ACCOUNT_ENDPOINT, DBLIFT_DB_ACCOUNT_KEY, DBLIFT_DB_DATABASE_NAME, and DBLIFT_DB_USE_MANAGED_IDENTITY.

use_managed_identity: true uses Azure DefaultAzureCredential. A localhost endpoint is auto-detected as the emulator.

database:
  type: cosmosdb
  account_endpoint: "https://account.documents.azure.com:443/"
  database_name: app
  account_key: "your-key"
migrations:
  directory: "./migrations"

To use a managed identity, set use_managed_identity: true. That setting uses Azure DefaultAzureCredential.

Step 3: Write a Cosmos DB schema migration

File names are V<version>__<desc>.py, optional undo U<version>__<desc>.py, and repeatable R__<desc>.py.

Each file defines migrate(context). context.db is the azure-cosmos DatabaseProxy. Anything the SDK can do goes in a script: containers with a partition key, throughput or autoscale, indexing policy or TTL via replace_container, and documents. DBLift has no operation list of its own. SQL write statements are rejected.

from azure.cosmos import PartitionKey
def migrate(context):
    if context.dry_run:
        context.log.info("[DRY-RUN] would create container 'users'"); return
    context.db.create_container(id="users", partition_key=PartitionKey(path="/tenant_id"), offer_throughput=400)

--dry-run connects but creates nothing and takes no lock. It still runs scripts with context.dry_run=True, so scripts must check that flag before writing. The guard in the file above is that check.

Step 4: History and lock for Cosmos DB schema migrations

Applied Cosmos DB schema migrations are stored in the history container dblift_schema_history. The lock is a document in dblift_migration_lock. The lease is 5 minutes. migrate waits up to 60 seconds, then fails.

There are no transactions. A script that fails partway leaves its completed operations in place, so write idempotent migrations. 429 throttling retries come from the azure-cosmos SDK defaults.

Step 5: Run Cosmos DB schema migrations

Open-source commands are migrate, info, validate, undo (via U files), baseline, repair, and clean. clean drops every container in the database.

validate-sql does not support Cosmos DB. diff and drift detection are Pro.

dblift info
dblift validate
dblift migrate --dry-run
dblift migrate

info and validate are the same open-source commands as check pending database migrations with info and validate. The dry-run tutorial covers --dry-run on SQL engines. On Cosmos DB the flag still connects, creates nothing, and takes no lock, and the script must check context.dry_run before it writes.

Make it a habit: Cosmos DB schema migrations

dblift info
dblift validate
dblift migrate --dry-run
dblift migrate

Run info and validate before migrate when you apply Cosmos DB schema migrations. Keep the context.dry_run check in every script that writes.

FAQ

How do Cosmos DB schema migrations work?

They are Python files named V<version>__<desc>.py. migrate(context) receives an azure-cosmos DatabaseProxy as context.db. The engine page is Cosmos DB schema migrations.

Do Cosmos DB schema migrations copy data?

No. DBLift does not copy data between databases. There is no data copy from SQL Server, MongoDB, or any other database.

What does dry-run do for Cosmos DB schema migrations?

dblift migrate --dry-run connects, creates nothing, and takes no lock. It still runs each script with context.dry_run=True. The script has to check that flag before it writes.

Read next

• Cosmos DB schema migrations
• Check pending database migrations with info and validate
• Dry-run tutorial
• DBLift on GitHub