Migrate MongoDB to DynamoDB: Plan, Import, and Cut Over

Migrating from MongoDB to DynamoDB requires redesigning queries and keys, converting BSON values, and moving data with a controlled cutover. Use AWS DMS for supported source deployments that need ongoing change capture, or transform an export and import it through S3 when a bulk load into a new table fits. Copying documents alone does not migrate MongoDB indexes, aggregation pipelines, or application behavior.

Outline

Keep the original migration sequence, but give each stage a measurable exit condition:

1. Study: identify which MongoDB features the application actually uses.
2. Plan: map every required read and write to a DynamoDB key, index, or transaction.
3. Code: implement type conversion and the new application access layer.
4. Migrate: backfill records and capture changes, or stop writes for an offline migration.
5. Monitor: reconcile data and compare application behavior before switching traffic.
6. Cleanup: retire the old path only after the rollback window and recovery checks pass.

The DynamoDB vs MongoDB comparison covers the product tradeoffs. A migration is justified when the resulting design fits the application, not merely because both products accept documents.

Server

MongoDB can be self-managed or hosted through MongoDB Atlas. Atlas already handles substantial infrastructure work, so moving to DynamoDB is not necessarily a move from unmanaged to managed storage. It changes APIs, identity, capacity planning, and operational responsibilities.

DynamoDB's production service runs on AWS. Choose the Region, IAM permissions, capacity mode, backup settings, and deployment process before loading data. On-demand capacity is useful when measuring a new workload, but hot keys and throughput quotas still matter.

Use DynamoDB Local for fast application tests. Also test against a real AWS table before cutover because local behavior does not reproduce every managed-service limit, identity rule, or failure mode.

Items and BSON type mapping

MongoDB stores BSON, not plain JSON. Its type system includes ObjectId, Date, Decimal128, binary subtypes, and other values that need an explicit destination representation. DynamoDB supports strings, numbers, binary values, booleans, nulls, lists, maps, and sets, but has no native BSON ObjectId or date type.

DynamoDB's item limit is 400 KB, including names and values, and numbers have up to 38 digits of precision. MongoDB allows 16 MiB BSON documents. Check the DynamoDB constraints and MongoDB limits before a bulk run. A document fitting MongoDB may require several DynamoDB items or an S3 object plus metadata.

Do not flatten all missing values into nulls, or all numeric values into strings. Those choices affect filters, indexes, sorting, and application deserialization. Define the contract first and test malformed and boundary values.

Querying and access-pattern redesign

Write down each operation's inputs, output, ordering, pagination, consistency, and expected traffic. Include less visible paths such as scheduled jobs, support tools, exports, and uniqueness checks.

For an order summary, one possible model is:

This deliberately uses a stable order ID in the base key. Changing a customer's ownership or a timestamp can update index attributes without changing the order's primary key. The GSI is eventually consistent, so use the table key for read-after-write checks that require a strong read.

DynamoDB read APIs have distinct purposes:

• GetItem: fetch one item with its full primary key.
• BatchGetItem: fetch several known keys; retry unprocessed keys and do not rely on response order.
• Query: read a partition-key value and optional sort-key range from a table or index.
• Scan: evaluate every item in the selected table or index, page by page. Useful for controlled administrative work, but usually a poor replacement for an indexed MongoDB application query.

A filter applies after DynamoDB reads candidate items. It does not save the read capacity used to evaluate them. Follow pagination even when a filtered page contains no results. MongoDB $lookup and aggregation stages do not become equivalent operations merely by switching to DynamoDB PartiQL.

Application reads with AWS SDK for JavaScript v3

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb in the application. This ES module reads the Orders model above and pages through its customer index:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, GetCommand, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

export async function getOrder(orderId) {
  const result = await client.send(new GetCommand({
    TableName: "Orders",
    Key: { pk: `ORDER#${orderId}`, sk: "METADATA" },
    ConsistentRead: true,
  }))
  return result.Item
}

export async function* customerOrders(customerId) {
  let lastKey
  do {
    const page = await client.send(new QueryCommand({
      TableName: "Orders",
      IndexName: "ByCustomer",
      KeyConditionExpression: "gsi1pk = :customer",
      ExpressionAttributeValues: { ":customer": `CUSTOMER#${customerId}` },
      ScanIndexForward: false,
      ExclusiveStartKey: lastKey,
    }))
    for (const item of page.Items ?? []) yield item
    lastKey = page.LastEvaluatedKey
  } while (lastKey)
}
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, GetCommand, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

export async function getOrder(orderId) {
  const result = await client.send(new GetCommand({
    TableName: "Orders",
    Key: { pk: `ORDER#${orderId}`, sk: "METADATA" },
    ConsistentRead: true,
  }))
  return result.Item
}

export async function* customerOrders(customerId) {
  let lastKey
  do {
    const page = await client.send(new QueryCommand({
      TableName: "Orders",
      IndexName: "ByCustomer",
      KeyConditionExpression: "gsi1pk = :customer",
      ExpressionAttributeValues: { ":customer": `CUSTOMER#${customerId}` },
      ScanIndexForward: false,
      ExclusiveStartKey: lastKey,
    }))
    for (const item of page.Items ?? []) yield item
    lastKey = page.LastEvaluatedKey
  } while (lastKey)
}

Use the application's AWS profile or workload role and Region configuration; do not embed credentials. Test authorization and decimal handling in the real application, not only the migration script.

Migration: choose a transfer path

Option 1: AWS DMS with a MongoDB source

AWS documents MongoDB source support and a DynamoDB target. Check the current supported-source matrix for your MongoDB and DMS versions; the matrix checked for this update lists MongoDB through 8.0, not 9.0. Do not assume support for a newer server release.

DMS offers document and table metadata modes. Document mode places the source document in _doc; table mode exposes fields and imposes type-consistency requirements. For ongoing document-mode changes, configure _id as a separate column as documented. CDC needs a suitable replica-set/change-history configuration and sufficient retained history to survive backfill and interruptions.

For the target, object mappings determine keys and attributes. DMS can create target tables, but it does not automatically implement the application model above. Review its restrictions around changing primary-key values, unsupported task settings, and source field names before running the task.

A practical sequence is to test endpoints, load a representative collection, inspect the resulting types and keys, and exercise inserts, updates, and deletes. Then run the production full load with CDC, monitor lag and errors, and reconcile against a defined source checkpoint. Do not assume a successful transfer has reproduced MongoDB indexes or query semantics.

Option 2: transform an export and import from S3

DynamoDB's S3 import accepts CSV, DynamoDB JSON, or Amazon Ion and creates a new table. It does not import into an existing table and does not consume the new table's write capacity. Storage and import charges still apply.

MongoDB Extended JSON is not DynamoDB JSON. For this offline example, pause writes and background mutations for the exported dataset, or use a separately designed consistent extraction process. The source must remain stable until cutover unless you also capture and apply subsequent changes.

Export the orders collection with mongoexport. Configure MONGODB_EXPORT_HOST and MONGODB_EXPORT_USER for your deployment; omitting the password lets the tool prompt for it. Adjust the authentication database if needed:

mongoexport   --host "$MONGODB_EXPORT_HOST"   --tls   --username "$MONGODB_EXPORT_USER"   --authenticationDatabase admin   --db shop   --collection orders   --jsonFormat canonical   --out orders.mongo.jsonl
mongoexport   --host "$MONGODB_EXPORT_HOST"   --tls   --username "$MONGODB_EXPORT_USER"   --authenticationDatabase admin   --db shop   --collection orders   --jsonFormat canonical   --out orders.mongo.jsonl

mongoexport is a data export tool, not a deployment backup. Retain an actual source backup for rollback. Canonical Extended JSON helps preserve BSON type information; decode it with PyMongo's BSON utilities.

The following Python script requires pymongo and boto3. Save it as convert_orders.py. It intentionally handles a bounded order-summary schema, not arbitrary MongoDB documents: _id is an ObjectId, customerId and status are strings, createdAt is a BSON Date, and total is Decimal128. Other fields are omitted deliberately; extend and validate the mapping before using it for your own dataset.

import json
from datetime import datetime, timezone
from pathlib import Path

from bson import ObjectId, json_util
from bson.decimal128 import Decimal128
from boto3.dynamodb.types import TypeSerializer

serializer = TypeSerializer()


def map_order(doc):
    if not isinstance(doc.get("_id"), ObjectId):
        raise ValueError("Expected an ObjectId _id")
    for name in ("customerId", "status"):
        value = doc.get(name)
        if not isinstance(value, str) or not value:
            raise ValueError(f"Expected a nonempty string for {name}")
    if len(doc["customerId"].encode("utf-8")) > 256:
        raise ValueError("customerId exceeds this example's application limit")
    if not isinstance(doc.get("createdAt"), datetime):
        raise ValueError("Expected a BSON Date createdAt")
    if not isinstance(doc.get("total"), Decimal128):
        raise ValueError("Expected a Decimal128 total")

    order_id = str(doc["_id"])
    created = doc["createdAt"]
    if created.tzinfo is None:
        created = created.replace(tzinfo=timezone.utc)
    created = created.astimezone(timezone.utc).isoformat(timespec="milliseconds")
    created = created.replace("+00:00", "Z")
    total = doc["total"].to_decimal()
    if not total.is_finite():
        raise ValueError("Non-finite total is not supported")

    item = {
        "pk": f"ORDER#{order_id}",
        "sk": "METADATA",
        "gsi1pk": f"CUSTOMER#{doc['customerId']}",
        "gsi1sk": f"{created}#{order_id}",
        "orderId": order_id,
        "customerId": doc["customerId"],
        "createdAt": created,
        "status": doc["status"],
        "total": total,
    }
    # A deliberately conservative bound for this flat, string/number schema.
    upper_bound = sum(
        len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
        for key, value in item.items()
    )
    if upper_bound > 350_000:
        raise ValueError("Summary exceeds this example's size safety margin")
    return item


def main():
    output = Path("orders.ddb.jsonl")
    temporary = Path("orders.ddb.jsonl.partial")
    count = 0
    with open("orders.mongo.jsonl", encoding="utf-8") as source:
        with temporary.open("w", encoding="utf-8") as target:
            for line_number, line in enumerate(source, start=1):
                try:
                    item = map_order(json_util.loads(line))
                    attributes = {
                        key: serializer.serialize(value)
                        for key, value in item.items()
                    }
                except Exception as exc:
                    raise ValueError(f"Invalid record on line {line_number}") from exc
                target.write(json.dumps({"Item": attributes}) + "\n")
                count += 1
    temporary.replace(output)
    print(f"Converted {count} order summaries")


if __name__ == "__main__":
    main()
import json
from datetime import datetime, timezone
from pathlib import Path

from bson import ObjectId, json_util
from bson.decimal128 import Decimal128
from boto3.dynamodb.types import TypeSerializer

serializer = TypeSerializer()


def map_order(doc):
    if not isinstance(doc.get("_id"), ObjectId):
        raise ValueError("Expected an ObjectId _id")
    for name in ("customerId", "status"):
        value = doc.get(name)
        if not isinstance(value, str) or not value:
            raise ValueError(f"Expected a nonempty string for {name}")
    if len(doc["customerId"].encode("utf-8")) > 256:
        raise ValueError("customerId exceeds this example's application limit")
    if not isinstance(doc.get("createdAt"), datetime):
        raise ValueError("Expected a BSON Date createdAt")
    if not isinstance(doc.get("total"), Decimal128):
        raise ValueError("Expected a Decimal128 total")

    order_id = str(doc["_id"])
    created = doc["createdAt"]
    if created.tzinfo is None:
        created = created.replace(tzinfo=timezone.utc)
    created = created.astimezone(timezone.utc).isoformat(timespec="milliseconds")
    created = created.replace("+00:00", "Z")
    total = doc["total"].to_decimal()
    if not total.is_finite():
        raise ValueError("Non-finite total is not supported")

    item = {
        "pk": f"ORDER#{order_id}",
        "sk": "METADATA",
        "gsi1pk": f"CUSTOMER#{doc['customerId']}",
        "gsi1sk": f"{created}#{order_id}",
        "orderId": order_id,
        "customerId": doc["customerId"],
        "createdAt": created,
        "status": doc["status"],
        "total": total,
    }
    # A deliberately conservative bound for this flat, string/number schema.
    upper_bound = sum(
        len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
        for key, value in item.items()
    )
    if upper_bound > 350_000:
        raise ValueError("Summary exceeds this example's size safety margin")
    return item


def main():
    output = Path("orders.ddb.jsonl")
    temporary = Path("orders.ddb.jsonl.partial")
    count = 0
    with open("orders.mongo.jsonl", encoding="utf-8") as source:
        with temporary.open("w", encoding="utf-8") as target:
            for line_number, line in enumerate(source, start=1):
                try:
                    item = map_order(json_util.loads(line))
                    attributes = {
                        key: serializer.serialize(value)
                        for key, value in item.items()
                    }
                except Exception as exc:
                    raise ValueError(f"Invalid record on line {line_number}") from exc
                target.write(json.dumps({"Item": attributes}) + "\n")
                count += 1
    temporary.replace(output)
    print(f"Converted {count} order summaries")


if __name__ == "__main__":
    main()

The required import format is one Item object per line containing typed DynamoDB attributes. Do not wrap the output in an array or put BatchWrite request objects around it. Only upload output from a successful conversion run. Check primary-key uniqueness separately; duplicate destination keys can overwrite records during import.

Save this table definition as orders-table.json. Its key and index names match the converter and SDK example:

{
  "TableName": "Orders",
  "BillingMode": "PAY_PER_REQUEST",
  "AttributeDefinitions": [
    { "AttributeName": "pk", "AttributeType": "S" },
    { "AttributeName": "sk", "AttributeType": "S" },
    { "AttributeName": "gsi1pk", "AttributeType": "S" },
    { "AttributeName": "gsi1sk", "AttributeType": "S" }
  ],
  "KeySchema": [
    { "AttributeName": "pk", "KeyType": "HASH" },
    { "AttributeName": "sk", "KeyType": "RANGE" }
  ],
  "GlobalSecondaryIndexes": [
    {
      "IndexName": "ByCustomer",
      "KeySchema": [
        { "AttributeName": "gsi1pk", "KeyType": "HASH" },
        { "AttributeName": "gsi1sk", "KeyType": "RANGE" }
      ],
      "Projection": { "ProjectionType": "ALL" }
    }
  ]
}
{
  "TableName": "Orders",
  "BillingMode": "PAY_PER_REQUEST",
  "AttributeDefinitions": [
    { "AttributeName": "pk", "AttributeType": "S" },
    { "AttributeName": "sk", "AttributeType": "S" },
    { "AttributeName": "gsi1pk", "AttributeType": "S" },
    { "AttributeName": "gsi1sk", "AttributeType": "S" }
  ],
  "KeySchema": [
    { "AttributeName": "pk", "KeyType": "HASH" },
    { "AttributeName": "sk", "KeyType": "RANGE" }
  ],
  "GlobalSecondaryIndexes": [
    {
      "IndexName": "ByCustomer",
      "KeySchema": [
        { "AttributeName": "gsi1pk", "KeyType": "HASH" },
        { "AttributeName": "gsi1sk", "KeyType": "RANGE" }
      ],
      "Projection": { "ProjectionType": "ALL" }
    }
  ]
}

With a dedicated S3 prefix, appropriate S3/DynamoDB permissions, and an AWS CLI v2 profile and Region configured, start the import. Set MIGRATION_BUCKET to a bucket you control. The Orders table must not already exist:

set -euo pipefail
python3 convert_orders.py
aws s3 cp orders.ddb.jsonl "s3://$MIGRATION_BUCKET/orders-snapshot/orders.ddb.jsonl"
aws dynamodb import-table   --s3-bucket-source "S3Bucket=$MIGRATION_BUCKET,S3KeyPrefix=orders-snapshot/"   --input-format DYNAMODB_JSON   --table-creation-parameters file://orders-table.json
set -euo pipefail
python3 convert_orders.py
aws s3 cp orders.ddb.jsonl "s3://$MIGRATION_BUCKET/orders-snapshot/orders.ddb.jsonl"
aws dynamodb import-table   --s3-bucket-source "S3Bucket=$MIGRATION_BUCKET,S3KeyPrefix=orders-snapshot/"   --input-format DYNAMODB_JSON   --table-creation-parameters file://orders-table.json

Wait for the returned import's status to become COMPLETED using describe-import. Inspect error counts and logs before accepting the table, then enable the required backups, alarms, and access policies. Keep unrelated or older files out of the imported prefix.

For a smaller load into an existing table, a custom writer can use boto3's batch_writer, which buffers writes and retries unprocessed items. Batch writes overwrite matching keys and do not support per-item conditions. Use conditional individual writes when source-version checks are required; do not race an unconditional backfill against live updates.

Option 3: backfill with application change processing

A custom pipeline fits when one MongoDB document becomes several items or needs data from other collections. Capture a durable change boundary before the snapshot, retain events until applied, checkpoint progress, and make replay idempotent.

Plain dual writes are not enough. MongoDB can succeed while DynamoDB fails, and a slow backfill can overwrite a newer value. Keep one authoritative writer during migration and use an outbox or durable change capture with retries and reconciliation. Preserve version ordering per record and handle deletes explicitly, including deletes that occur before the backfill reaches a record.

Cut over, monitor, and clean up

For an offline migration, keep writes paused until validation finishes and the new application path is ready. For an online migration, briefly fence source writes, drain changes to a known boundary, reconcile, and then switch the authoritative writer. Switching reads first is useful for testing only when you understand the remaining replication lag.

Validate more than a row count:

• Compare source IDs with destination keys, including missing and duplicate records.
• Compare canonical field values after the agreed type mapping, especially decimals and dates.
• Run every access pattern, including pagination, sort order, conditional conflicts, and deletes.
• Measure latency, throttling, consumed capacity, GSI lag, and migration backlog under load.
• Restore a backup and exercise the application routing needed to use it.

DynamoDB's reported table item count is not a real-time reconciliation proof. Use a controlled read of the migrated key set or application-level reconciliation against the frozen source boundary.

After DynamoDB accepts new writes, rolling back to MongoDB requires those writes to reach MongoDB or be replayed there. Keeping an old snapshot alone is insufficient. Define rollback and reconciliation before cutover, then retain the source and migration artifacts for the agreed period. Remove obsolete credentials, connections, jobs, and infrastructure only after that period and the verification gates pass.

Dynamoose

Dynamoose is a DynamoDB modeling library inspired by Mongoose. It provides schema validation and a higher-level interface, but it is not a drop-in implementation of Mongoose queries, population, middleware, or transactions.

If you use it, review each model and operation against the destination access patterns. A familiar method name does not guarantee the same query cost or consistency. The direct SDK v3 example above keeps those operations explicit while the model is being validated. The DynamoDB ORM comparison runs Dynamoose, ElectroDB and DynamoDB Toolbox against the same model.

DynamoDB starting tips and checks

Start with one representative collection and its application endpoints. Include large documents, unusual BSON values, old records, and active writes in the rehearsal. Keep a repeatable conversion and a record of the source boundary, mapping version, destination table, and validation results.

Use the DynamoDB tutorials for individual APIs. Dynobase's data-modeling workspace can help record access patterns and indexes, and its S3 import workflow can help inspect the bulk-import setup. Neither replaces application-level reconciliation or a cutover plan.