DocumentDB — Compatibility Assessor

Assess whether an existing MongoDB workload will run on Amazon DocumentDB. Clone the amazon-documentdb-tools repo, run the compat tool and index tool, triage findings, and produce artifacts/{app-name}/compatibility-report.md.

What to ask upfront

app_name (lowercase with hyphens, used for artifacts/{app-name}/)
One of: MongoDB connection string, log files path, or source code directory
target_version (default: 8.0)

Workflow

Step 0: Clone tools and create artifact directory

if [ ! -d "amazon-documentdb-tools" ]; then
  git clone https://github.com/awslabs/amazon-documentdb-tools amazon-documentdb-tools
  (cd amazon-documentdb-tools/index-tool && python3 -m pip install -r requirements.txt -q)
fi
mkdir -p artifacts/<app-name>

If git clone fails, tell the user and ask them to clone it manually.

Step 1: Run the compat tool

Pick one input mode:

A — Live MongoDB URI (most accurate):

python3 amazon-documentdb-tools/compat-tool/compat.py \
  --uri "mongodb://<user>:<pass>@<host>:<port>/admin?directConnection=true" \
  --version 8.0

B — Source directory:

python3 amazon-documentdb-tools/compat-tool/compat.py \
  --version 8.0 --directory /path/to/app/src \
  --excluded-extensions txt,md

C — MongoDB log file:

python3 amazon-documentdb-tools/compat-tool/compat.py \
  --file /path/to/mongod.log --version 8.0

Capture the full output. If URI auth fails, retry with --directory or --file mode. directConnection=true is needed for replica-set members.

Step 2: Run the index tool (URI mode only)

cd amazon-documentdb-tools/index-tool
python3 migrationtools/documentdb_index_tool.py \
  --dump-indexes --dir ../index-export \
  --uri "mongodb://<user>:<pass>@<host>:<port>"

python3 migrationtools/documentdb_index_tool.py \
  --show-issues --dir ../index-export

If no URI provided, skip this step and note "Index analysis skipped — no MongoDB URI provided" in the report.

Step 3: Verify operator support against live docs

Mandatory — do this BEFORE stating any operator is unsupported. DocumentDB adds operator support across versions; hardcoded lists go stale. Always check live status.

For every operator the compat tool flags, call web_fetch(url="https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html") and search for the operator name. The page has Yes/No tables per version (3.6 / 4.0 / 5.0 / 8.0 / Elastic). If the aws-documentation plugin is available, prefer aws___search_documentation for the same page.

State support as: "$operator is [supported / not supported] on DocumentDB 8.0 per the checked compatibility reference. Verify at the MongoDB API compatibility page for the latest status."

If web_fetch is unavailable, add to the report: "Operator support status based on bundled reference data — may not reflect recent additions. Verify current status at https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html".

Step 4: Triage every finding

BLOCKER — not supported in target version (verify via Step 3 first); app code must change before migration
WARNING — supported with behavioral differences; test before cutover
SAFE — fully supported, no changes needed

Step 5: Write the compatibility report

Write artifacts/{app-name}/compatibility-report.md with this structure:

# Compatibility Report: {app-name}
**Date:** {today}
**Target:** DocumentDB 8.0
**Method:** [live URI / source scan / log analysis]

## Summary
- Blockers: N
- Warnings: N
- Safe: N

## Blockers (must fix before migration)
### {operator or feature}
- **Found in:** {file:line or query pattern}
- **Issue:** {why it doesn't work}
- **Workaround:** {concrete alternative with code}

## Warnings (test carefully)
### {operator or feature}
- **Found in:** ...
- **Behavioral difference:** ...
- **Recommendation:** ...

## Index Issues
- **Incompatible indexes:** {list from --show-issues}
- **Action:** Use `--skip-incompatible` during restore; recreate equivalents manually

## Safe
{list of confirmed-supported operators}

Summarize the key findings to the user (blocker count, warning count, critical items).

Common blockers and workarounds

`$where` (JS in queries)

// BLOCKED
db.col.find({ $where: "this.price > this.cost" })
// Fix — use $expr with native operators
db.col.find({ $expr: { $gt: ["$price", "$cost"] } })

MapReduce (blocked on 3.6 / 4.0 / 5.0 — works on 8.0)

Rewrite as aggregation for 5.0:

db.orders.aggregate([
  { $group: { _id: "$category", total: { $sum: "$amount" } } },
  { $out: "category_totals" }
])

`$accumulator` / `$function` (custom JS)

Rewrite with native operators: $sum, $avg, $reduce, $map, $filter, $switch.

Hashed indexes

// BLOCKED: db.col.createIndex({ userId: "hashed" })
db.col.createIndex({ userId: 1 })    // single-field ascending

Wildcard indexes (verify current support status)

Check the MongoDB API compatibility page — wildcard indexes may not be supported on all DocumentDB versions, and DocumentDB adds index types across versions.

// If unsupported: create explicit indexes for the specific fields you filter on
// db.col.createIndex({ "$**": 1 })  <- check support status before attempting

2d (legacy) geospatial indexes

// BLOCKED: db.places.createIndex({ location: "2d" })
db.places.createIndex({ location: "2dsphere" })    // works, supports GeoJSON

`$lookup` with pipeline (blocked on 5.0, works on 8.0)

// For 5.0, rewrite as localField/foreignField:
{ $lookup: { from: "orders", localField: "_id", foreignField: "userId", as: "orders" } }

`$graphLookup` (verify current support status — workaround below)

Check the MongoDB API compatibility page before advising. If unsupported, use the materialized path pattern — store the ancestor list at write time (this is often the better design regardless of $graphLookup availability):

// Each doc carries its ancestors array
{ _id: "cat3", name: "Shoes", ancestors: ["cat1", "cat2", "cat3"] }
// All ancestors:
db.categories.find({ _id: { $in: doc.ancestors } })
// All descendants of cat1:
db.categories.find({ ancestors: "cat1" })

`$facet` (verify current support status — workaround below)

Check the MongoDB API compatibility page before advising. If unsupported: split into separate aggregation pipelines and merge results in application code.

Common warnings (behavioral differences)

explain() output structure differs — do not parse it programmatically assuming MongoDB format
Collation support is limited for locale-specific string comparison — test before cutover
$regex flags x (extended) and s (dotAll) not supported — remove them
Transaction scope has limits on collection and operation counts — test complex multi-collection transactions

Index restore — skipping incompatibles

# Dry run first
python3 amazon-documentdb-tools/index-tool/migrationtools/documentdb_index_tool.py \
  --restore-indexes --skip-incompatible --dry-run \
  --dir amazon-documentdb-tools/index-export \
  --uri "mongodb://admin:<pw>@<docdb-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false"

# Actual restore
python3 amazon-documentdb-tools/index-tool/migrationtools/documentdb_index_tool.py \
  --restore-indexes --skip-incompatible \
  --dir amazon-documentdb-tools/index-export \
  --uri "mongodb://admin:<pw>@<docdb-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false"

After restore, manually recreate the skipped indexes using the DocumentDB-supported equivalents above.

/amazon-documentdb

referencescompatibility.md