Migration overview

Cross-database migration between MongoDB and PostgreSQL.

DBdock can move data between MongoDB and PostgreSQL in either direction. It’s designed for the case where you’ve outgrown MongoDB and want to land on Postgres (or vice versa) — not as a live replication tool.

What gets migrated

Schema

MongoDB collections → Postgres tables (or the reverse). Field types inferred from the source.

Data

Every document/row streamed in configurable batches.

References

Best-effort detection of relationships to set up foreign keys.

Errors

Failed rows are collected in a _migration_errors table/collection for review.

Workflow

1. Analyze the source

   Scan the source database to understand shape, types, and reference patterns.

   npx dbdock analyze "mongodb://localhost:27017/myapp"
   

   See dbdock analyze.

2. Plan the migration

   DBdock generates a schema mapping proposal you can review and customize.

   See Schema mapping.

3. Dry run

   Validate the mapping against a temporary schema — no production writes.

   npx dbdock migrate "$MONGO_URL" "$POSTGRES_URL" --dry-run
   

   See Dry runs.

4. Run the migration

   Execute against the real target with your confirmation.

   npx dbdock migrate "$MONGO_URL" "$POSTGRES_URL"
   

   See dbdock migrate.

5. Keep things in sync (optional)

   Run incremental migrations to pull only new/changed data.

   npx dbdock migrate "$MONGO_URL" "$POSTGRES_URL" --incremental --since 2026-04-01
   

   See Incremental migration.

Directions

MongoDB → PostgreSQL

The most common direction. DBdock:

• Flattens nested documents up to a configurable depth (default: 2 levels)
• Stores deeper nesting as jsonb columns
• Infers column types from observed values
• Creates indexes for commonly-queried fields

PostgreSQL → MongoDB

Also supported. DBdock:

• Maps tables to collections
• Converts rows to documents, preserving column types
• Optionally embeds related rows (one-to-many) into parent documents
• Translates Postgres JSON/JSONB columns to native MongoDB documents

Core principles

1. Nothing runs without confirmation. Every migration shows you the plan and waits for you to approve it.
2. Errors don’t halt the migration. Failed rows go to _migration_errors so you can address them post-hoc without redoing the whole thing.
3. Idempotent where possible. Re-running a migration with the same config reuses existing tables rather than duplicating.
4. You own the schema. The generated mapping is a proposal — save it, edit it, commit it.

See also

dbdock analyze

Understand the source first.

dbdock migrate

The migration command itself.

Schema mapping

How MongoDB types become Postgres types.

Dry runs

Validate without touching production.