Amazon DocumentDB - MongoDB's Evil Twin

DocumentDB is AWS's homegrown database that speaks MongoDB but thinks differently. Launched in 2019 after AWS got tired of paying MongoDB licensing fees - basically their "we'll build our own MongoDB, with blackjack and auto-scaling" solution. Classic AWS move, honestly.

Here's the thing - it's not actually MongoDB, no matter what the marketing says. It's Amazon's custom database engine that happens to understand some MongoDB queries when it feels like it. Think of it like a really sophisticated translator that usually gets the meaning right, but sometimes completely fucks up the nuance and you end up ordering fish instead of chicken. And then arguing with the waiter about why your chicken tastes fishy.

The Architecture Story

The clever part is how AWS separated compute from storage - something MongoDB didn't figure out until much later. Your app talks to compute instances, but all the data lives in a shared storage layer that auto-replicates across three availability zones.

• Primary Instance: Where your writes go (and reads if you want)
• Up to 15 Read Replicas: All share the same storage, so no data copying bullshit
• Cluster Volume: The magic sauce - grows from 10GB to 128TB automatically

This means adding a read replica takes minutes, not hours of copying data around. Pretty neat engineering, honestly.

The "MongoDB Compatible" Reality Check

DocumentDB claims compatibility with MongoDB 3.6, 4.0, and 5.0 APIs. In practice, your basic CRUD operations work fine, MongoDB Compass connects without issue, and most drivers just work.

But here's where you get fucked:

• Multi-document transactions? Works in 4.0+ but didn't exist in 3.6. Half our legacy shit still runs on 3.6 clusters, so good luck with that. And even in 4.0+, the transaction performance is... questionable.
• Advanced aggregation pipelines? Hit or miss. Some work great, others timeout mysteriously.
• Change streams? Work differently and have weird edge cases.
• GridFS? Forget about it.
• Full-text search? Not the MongoDB way - you'll need OpenSearch.

I've seen teams spend fucking forever debugging why their perfectly working MongoDB aggregation pipeline runs like absolute shit in DocumentDB, only to discover it's hitting completely different optimization paths that make no goddamn sense. Had this one team - took them like a month, maybe six weeks? Honestly felt like longer - trying to figure out why this query that was blazing fast in MongoDB suddenly turned into molasses in DocumentDB. Something like 50ms to... I don't know, 8 seconds? Maybe 15? Point is, it was way slower and we never figured out exactly why because DocumentDB's optimizer is basically a different animal that speaks its own weird dialect of performance.

Migration War Stories

Companies switching from self-managed MongoDB usually love not dealing with replica set configuration and automatic failover. The ops team definitely sleeps better.

But the dev team? They discover that "compatible" doesn't mean "identical" when their integration tests start failing in mysterious ways that make no fucking sense. Had this one client - we migrated their e-commerce platform and it was a complete shitshow. Took us like 6 weeks, maybe 8, just to fix the broken aggregations, and then another month trying to explain to the CEO why features that worked perfectly before suddenly didn't work anymore. Those were some really fun meetings. And by fun I mean I wanted to hide under my desk.

Another team migrated their analytics pipeline and their daily reports went from... I think it was like 5 minutes to a couple hours. Maybe three hours? Could've been longer, honestly. Same fucking data, same queries, completely different performance that made zero sense. We spent weeks trying to optimize it, ended up rewriting most of their aggregation logic from scratch. Still not sure we got it right, but the client ran out of budget to keep trying.

Pro tip: that "seamless migration" marketing is complete bullshit designed to get you locked in. Whatever time you think you need, triple it. Actually, maybe quadruple it if you're feeling optimistic. Or just multiply by 10 and save yourself the surprise.

Document

DB shines in very specific scenarios, but it's definitely not the silver bullet AWS marketing makes it seem.

Here's the real talk on when to use it and when to run the fuck away screaming.

DocumentDB's Sweet Spot

Read-Heavy Apps with Simple Queries are where DocumentDB absolutely kills it. Think product catalogs, content management, user profiles

• stuff where you write once and read a thousand times. The shared storage architecture means adding read replicas is stupid fast, and you can scale reads almost infinitely.

I've seen e-commerce sites handle Black Friday traffic spikes just by spinning up more read replicas. Takes like 5-10 minutes, way faster than traditional MongoDB setups where you're copying data around for hours.

Prototyping and MVPs benefit from the "just works" factor. No need to configure replica sets, figure out sharding, or worry about automated backups. Your startup can go from idea to database in about 10 minutes. Great for proving concepts before you know what your real data patterns look like.

AWS-Native Applications where you're already deep in the AWS ecosystem. If you're using Lambda, API Gateway, and S3, DocumentDB fits right in. The IAM integration alone saves weeks of security setup.

Performance Reality Check

DocumentDB provides Performance Insights for query-level visibility, showing top statements, wait events, and database load. Elastic clusters can scale write performance by distributing across multiple shards.

The performance numbers look great on paper, but reality is messier:

• Read Performance:

Actually pretty impressive. We've seen apps go from like 500ms to maybe 50ms response times just by adding read replicas. Sometimes better, sometimes not as much.

• Write Performance: Decent, but not amazing.

Heavy write workloads hit that single primary bottleneck fast

• Replica Lag: Usually pretty low
• under 100ms most of the time
• but can spike to like 2 seconds or more when writes get heavy
• Connection Limits: 30,000 connections sounds like a lot until you're running a bunch of microservices and suddenly it's not

When DocumentDB Goes Wrong

Multi-Document Transactions:

This is where Document

DB breaks hearts and dreams. If you're stuck on 3.6 clusters (which a shitload of legacy apps still are), no multi-document transactions means you can't do atomic operations across documents, which is fucking insane for a "MongoDB compatible" database. Had this one team spend like 3 months

• felt like forever
• rewriting their entire order processing logic because they couldn't atomically update inventory and create orders anymore. Kept getting WriteConflictException errors that made no sense until we realized their 3.6 cluster just... doesn't support it. Even upgraded to 4.0+, transactions work but performance is dogshit compared to real MongoDB. Another client discovered this during a live demo to their biggest customer. That was... not a good meeting. CEO was not happy.

Complex Aggregation Pipelines: Your Mongo

DB aggregation that runs in like 200ms might take 2 seconds in DocumentDB, or just timeout entirely with some bullshit OperationTimeout error and leave you wondering what the hell happened.

The query optimizer is different, and sometimes it picks absolutely terrible execution plans for no apparent reason. Had one client completely rewrite their analytics queries

• turned a nice clean 15-line aggregation with $lookup and $group into like 200 lines of ugly application code that does the same thing but worse. Still working on optimizing it months later because DocumentDB's aggregation performance is just... shit.

Cost-Sensitive Workloads: That small development cluster?

Minimum cost is like $200-250/month, maybe more with all the hidden fees. You can run a Mongo

DB instance on a $20 VPS, but DocumentDB doesn't have a cheap option. Great for enterprises with deep pockets, painful for indie developers and small teams.

Advanced MongoDB Features: Grid

FS for file storage?

Nope. Full-text search? Use OpenSearch instead. Change streams? They work, but differently enough to break your existing code.

Migration Horror Stories

The Aggregation Pipeline Nightmare: Migrated this reporting system that worked perfectly in Mongo

DB.

Same data, same queries, suddenly like 10x slower in DocumentDB. Spent weeks trying to figure out what was wrong. Turns out the aggregation optimizer makes completely different choices and we never figured out how to fix it. Solution? Rewrote the entire pipeline and questioned my life choices. Still not as fast as the original.

The Transaction Trap: E-commerce site was using multi-document transactions for order processing.

Oops, "compatible" doesn't include that feature. Had to redesign the entire order workflow around single-document updates. Took like 2 months, maybe longer, and the CTO was... let's just say not happy about the timeline or the budget.

The Hidden Cost Explosion: Estimated $500/month based on that lying piece of shit calculator, ended up paying like $1,400 the first month.

I/O charges at $0.20 per million requests, data transfer between AZs at $0.01/GB, backup storage growing from 50GB to 800GB somehow

• all the stuff that's supposedly "included" but actually costs extra. Finance team loved that surprise phone call. Still trying to optimize costs months later and questioning why we didn't just use a fucking VPS.

The Honest Assessment

DocumentDB is great if:

• You're doing mostly reads
• You don't need advanced MongoDB features
• You're already married to AWS
• You value operational simplicity over cost

It's terrible if:

• You need multi-document transactions
• You have complex aggregation pipelines
• You're cost-sensitive
• You want to avoid vendor lock-in

The "MongoDB compatible" marketing is technically correct but practically misleading. It's more like "MongoDB-flavored"

• tastes familiar but leaves a weird aftertaste.