Skip to Content
Cloud Engineering Academy
6. Databases & Data Architecture

Amazon DocumentDB

Decide when a document model fits a banking workload — product catalogues, onboarding applications — and when PostgreSQL JSONB or DynamoDB is the better answer; then connect to Amazon DocumentDB from .NET 10 with TLS, schema validation and the MongoDB-compatibility caveats in mind.

intermediate⏱ 1 h 40 min🟢 FreeSAA-C03DEA-C01

Assumes: .NET 10 LTS · MongoDB.Driver 3.14.0 · Amazon DocumentDB 5.0 / 8.0 · mongo:8.0 (local stand-in) · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain what a document database is, and recognise workloads where a document model is a genuine fit — and where it is not.
  • Describe Amazon DocumentDB's architecture (instance-based clusters, serverless, elastic clusters, global clusters) and how it differs from running MongoDB.
  • List the MongoDB-compatibility caveats that break real applications (retryable writes, result ordering, unsupported operators, tooling versions) and how to test for them.
  • Connect from .NET 10 with the MongoDB C# driver over TLS using the AWS certificate bundle, with credentials from Secrets Manager.
  • Compare DocumentDB with PostgreSQL jsonb on Aurora and with DynamoDB for the same use case, and write the decision down.

Prerequisites

Why this matters in banking

Harbourline sells 40 retail and SME products in the UK and the EU. Every product has a different shape: a fixed-rate bond has a term and an early-withdrawal penalty; a business current account has a tariff with tiered transaction fees; an EU savings product needs extra disclosure documents in three languages. Today they live in SQL Server as a Products table with 140 nullable columns and a ProductAttributes key-value table nobody can query efficiently.

The onboarding team has the same problem with applications: a UK sole trader's application has different sections from an EU limited company's, and the forms change every quarter as regulation changes.

A document database stores each product or application as one self-describing JSON document. That is a real fit. But a document store is also the place where well-meaning teams put the ledger "because it's flexible" — and then discover that flexible schemas and multi-document transactions are not what auditors want for money. This lesson helps you choose with clear eyes.

The idea in plain language

A document database stores data as documents — JSON-like objects (stored as BSON, a binary JSON) with nested fields and arrays — grouped into collections. Documents in a collection do not need identical fields. You query by any field, add indexes on the fields you filter by, and read a whole entity in one operation without joins.

Amazon DocumentDB (with MongoDB compatibility) is an AWS-built database engine that implements the MongoDB wire protocol and API. Your app uses the standard MongoDB driver. Underneath, it is not MongoDB: it uses an Aurora-style distributed storage layer, which is why some behaviours differ.

Analogy: A relational schema is a printed form — every customer fills the same boxes, and adding a box means reprinting every form. A document store is a folder per customer: each folder holds exactly the pages that apply to them. Easy to file, easy to read in one go — but if the bank never agrees which pages must be in the folder, the auditors will find empty folders.

What problem DocumentDB solves

StrengthDetail
Flexible, nested dataProducts and applications with varying shapes, without nullable-column sprawl
Read a whole aggregate at onceOne document = one product with its tariffs, documents and eligibility rules
Managed operationsPatching, backups to S3 with point-in-time restore, automatic storage growth, up to 15 read replicas in an instance-based cluster
Storage decoupled from computeSix copies across three AZs (Aurora-style); failover to a replica typically in well under a minute ⚠ VERIFY current failover guidance
MongoDB API and driversExisting MongoDB skills and the official .NET driver work
OptionsInstance-based clusters, serverless (GA July 2025; available on DocumentDB 8.0 since May 2026), elastic clusters for sharding to very large scale, global clusters for cross-Region DR

Limitations — be explicit about them:

CaveatWhat it means
Compatibility, not identityImplements MongoDB 3.6, 4.0, 5.0 and 8.0 APIs; operators and stages are supported selectively — check the supported-API list for each one you use
Retryable writesSupported only from engine 8.0.2; on earlier versions you must set retryWrites=false
Result orderingNo implicit order; always sort()
Index buildsOne index build per collection at a time
admin / local databasesNot supported; mongodump/mongorestore do not carry users and roles
ToolingMongoDB Database Tools up to and including 100.11.0
$vectorSearchNot supported as a stage; vector search is available inside $search
VPC onlyClusters live in your VPC; no public endpoint; you need a bastion, VPN or SSM port forwarding to reach it from a laptop
PricingInstance-hours (or serverless capacity) plus storage and, on the Standard configuration, I/O. There is no always-free tier for steady use

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Cosmos DB for MongoDB (RU-based)Amazon DocumentDB (instance-based or serverless)DocumentDB bills compute and storage, not request units; compatibility levels differ — test both
Azure Cosmos DB for MongoDB vCoreDocumentDB instance-based clusterClosest match: you pick instance sizes
SQL Server JSON columns / OPENJSONPostgreSQL jsonb on AuroraOften enough: keep relational integrity for the core, JSON for the variable part
MongoDB Atlas on AzureMongoDB Atlas on AWS (Marketplace)Use Atlas if you need full MongoDB feature parity
Azure Cosmos DB for NoSQLDynamoDBKey-value/document with access-pattern design; different API
Entity Framework CoreMongoDB C# driver (or the MongoDB EF Core provider ⚠ VERIFY DocumentDB support)Use the driver directly for DocumentDB unless you have tested the EF provider against it

Architecture

Endpoints: a cluster endpoint (always the primary, for writes), a reader endpoint (load-balances replicas), and instance endpoints. Connecting with replicaSet=rs0 lets the driver discover all members and route reads by readPreference.

Security-boundary view

  • Network: private subnets only; security group allows TCP 27017 from the API security groups.
  • In transit: TLS is on by default (cluster parameter tls = enabled). Keep it.
  • At rest: encryption must be chosen at cluster creation (KMS key); you cannot encrypt an existing unencrypted cluster in place — you restore a snapshot into a new encrypted cluster.
  • Identity: database users with SCRAM passwords managed by Secrets Manager rotation, built-in roles scoped per database; IAM authentication is available for DocumentDB 5.0 and later ⚠ VERIFY current engine support and driver mechanism (MONGODB-AWS).
  • Audit: enable the audit_logs cluster parameter and export audit and profiler logs to CloudWatch Logs with retention.

When a document model fits — the decision

WorkloadBest fitWhy
Product catalogue: varying attributes, read-mostly, nested tariffsDocumentDB or PostgreSQL jsonbNatural documents; few writers; rich queries on attributes
Onboarding applications with versioned, country-specific sectionsDocumentDB or jsonb with JSON Schema validationShape varies; whole application read and written as a unit
Account ledger, balances, postingsRelational (RDS/Aurora)Constraints, joins, mature ACID semantics, reconciliation SQL
Idempotency keys, high-volume key lookupsDynamoDBSingle-digit ms at any scale, conditional writes, TTL
Full-text search over documentsOpenSearchRelevance ranking and analyzers
Existing MongoDB app needing full feature parityMongoDB AtlasAvoid compatibility gaps

A rule of thumb for Harbourline's architecture review: if the team already runs Aurora PostgreSQL and the documents are modest in volume, start with a jsonb column. Choose DocumentDB when the document workload is large, independent, needs MongoDB-style querying and indexing on nested fields, or when the team is migrating an existing MongoDB application.

Step-by-step implementation

You will build the catalogue against a local MongoDB 8.0 container — a stand-in, because DocumentDB cannot run locally — and keep the code inside the DocumentDB-supported subset. Then you will see exactly what changes for DocumentDB.

Run a local stand-in

docker run --name hl-m06-mongo -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=hladmin -e MONGO_INITDB_ROOT_PASSWORD=LocalOnly_ChangeMe1 -d mongo:8.0

Treat it as a development convenience only. Anything that works here must still be tested against DocumentDB before release.

Create the project

dotnet new console -n Harbourline.Catalogue.Documents -f net10.0
cd Harbourline.Catalogue.Documents
dotnet add package MongoDB.Driver --version 3.14.0

Add validation and indexes

The program in Complete code creates the products collection with a $jsonSchema validator (so every product has a code, a type, a currency and a status) and indexes on the fields the API filters by.

Run and query

$env:DOCDB_URI = "mongodb://hladmin:LocalOnly_ChangeMe1@localhost:27017/?authSource=admin"
dotnet run

The app inserts three products of different shapes and runs the catalogue queries.

Optional: point it at DocumentDB

Create a small cluster (see AWS CLI), reach it through SSM port forwarding from a bastion or run the app in the VPC, set DOCDB_URI to the DocumentDB connection string and DOCDB_CA_BUNDLE to the downloaded global-bundle.pem, run once, then delete the cluster.

AWS Console instructions

  1. Console → Amazon DocumentDB → Clusters → Create.
  2. Cluster type: Instance-based cluster (or Serverless if available for your engine version in us-east-1).
  3. Engine version: 8.0 for new work (retryable writes from 8.0.2, correlated $lookup subqueries); 5.0 if your driver/tooling requires it.
  4. Instance class: the smallest burstable class for a lab; number of instances: 1 for a lab (production: at least 3 across AZs).
  5. Authentication: username hladmin, Manage master credentials in AWS Secrets Manager so the password is generated and rotatable.
  6. Network: your lab VPC, a subnet group of private subnets, security group allowing 27017 from the app security group only.
  7. Encryption at rest: On, with a KMS key (cannot be changed later).
  8. Backup retention: 1 day for the lab (production: per records policy, up to 35 days); Log exports: audit and profiler logs to CloudWatch Logs; Deletion protection on in production.
  9. Add tags Project=cea-lab, Lab=m06-docdb, Environment=learn. Create cluster.
  10. Connectivity & security tab → copy the connection string for applications and download the CA bundle link shown there.

AWS CLI

# Subnet group for the cluster.
aws docdb create-db-subnet-group --db-subnet-group-name hl-m06-docdb-subnets \
  --db-subnet-group-description "Private data subnets" \
  --subnet-ids subnet-0aaa1111bbbb2222c subnet-0ddd3333eeee4444f subnet-0ggg5555hhhh6666i \
  --profile learn-sandbox --region us-east-1

# Cluster with Secrets Manager-managed master password, KMS encryption and audit/profiler log export.
aws docdb create-db-cluster --db-cluster-identifier hl-m06-docdb --engine docdb --engine-version 8.0.0 \
  --master-username hladmin --manage-master-user-password \
  --db-subnet-group-name hl-m06-docdb-subnets --vpc-security-group-ids sg-0docdb00000000001 \
  --storage-encrypted --kms-key-id alias/hl-m06-docdb \
  --backup-retention-period 1 --enable-cloudwatch-logs-exports audit profiler \
  --tags Key=Project,Value=cea-lab Key=Lab,Value=m06-docdb Key=Environment,Value=learn \
  --profile learn-sandbox --region us-east-1

# One small instance for the lab (choose the smallest class available to you).
aws docdb create-db-instance --db-instance-identifier hl-m06-docdb-1 \
  --db-cluster-identifier hl-m06-docdb --engine docdb --db-instance-class db.t4g.medium \
  --profile learn-sandbox --region us-east-1

# Download the CA bundle used to verify DocumentDB's TLS certificate.
curl -sSo global-bundle.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

Check --engine-version values with aws docdb describe-db-engine-versions --engine docdb and instance classes with describe-orderable-db-instance-options, because availability varies by Region ⚠ VERIFY before running. Turning on audit_logs also requires a custom cluster parameter group with that parameter set.

Infrastructure as Code

DocumentDbStack.cs
using Amazon.CDK;
using Amazon.CDK.AWS.DocDB;
using Amazon.CDK.AWS.EC2;
using Amazon.CDK.AWS.KMS;
using Amazon.CDK.AWS.Logs;
using Constructs;

namespace Harbourline.Infra;

public sealed class DocumentDbStack : Stack
{
    public DocumentDbStack(Construct scope, string id, IVpc vpc, ISecurityGroup appSg, IStackProps? props = null) : base(scope, id, props)
    {
        var key = new Key(this, "DocDbKey", new KeyProps { EnableKeyRotation = true, Alias = "alias/hl-m06-docdb" });

        var parameters = new ClusterParameterGroup(this, "Params", new ClusterParameterGroupProps
        {
            DbClusterParameterGroupName = "hl-m06-docdb8",
            Family = "docdb8.0", // ⚠ VERIFY family name for your engine version
            Description = "TLS on, audit logs on",
            Parameters = new Dictionary<string, string> { ["tls"] = "enabled", ["audit_logs"] = "enabled" }
        });

        var cluster = new DatabaseCluster(this, "Cluster", new DatabaseClusterProps
        {
            DbClusterName = "hl-m06-docdb",
            EngineVersion = "8.0.0",
            MasterUser = new Login { Username = "hladmin" }, // password generated into Secrets Manager
            InstanceType = InstanceType.Of(InstanceClass.BURSTABLE4_GRAVITON, InstanceSize.MEDIUM),
            Instances = 1, // lab only; 3 in production
            Vpc = vpc,
            VpcSubnets = new SubnetSelection { SubnetType = SubnetType.PRIVATE_ISOLATED },
            StorageEncrypted = true,
            KmsKey = key,
            ParameterGroup = parameters,
            Backup = new BackupProps { Retention = Duration.Days(1) },
            ExportAuditLogsToCloudWatch = true,
            ExportProfilerLogsToCloudWatch = true,
            CloudWatchLogsRetention = RetentionDays.ONE_MONTH,
            DeletionProtection = false, // lab only
            RemovalPolicy = RemovalPolicy.DESTROY
        });

        cluster.Connections.AllowDefaultPortFrom(appSg, "Catalogue API to DocumentDB");
        cluster.AddRotationSingleUser(); // rotate the master password with a managed Lambda

        Tags.SetTag("Project", "cea-lab");
        Tags.SetTag("Lab", "m06-docdb");
        Tags.SetTag("Environment", "learn");
    }
}

Complete code

Program.cs
using System.Security.Cryptography.X509Certificates;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;

var uri = Environment.GetEnvironmentVariable("DOCDB_URI")
          ?? throw new InvalidOperationException("Set DOCDB_URI (local: mongodb://...; AWS: from Secrets Manager)");
var caBundlePath = Environment.GetEnvironmentVariable("DOCDB_CA_BUNDLE"); // set only for DocumentDB

var settings = MongoClientSettings.FromConnectionString(uri);
settings.ServerApi = null;          // DocumentDB does not implement the Stable API handshake
settings.RetryWrites = false;       // required before DocumentDB 8.0.2; harmless locally
settings.ReadPreference = ReadPreference.SecondaryPreferred;
settings.ApplicationName = "hl-catalogue";

if (caBundlePath is not null)
{
    // Trust ONLY the AWS RDS/DocumentDB certificate authorities for this connection.
    var bundle = new X509Certificate2Collection();
    bundle.ImportFromPemFile(caBundlePath);
    settings.UseTls = true;
    settings.SslSettings = new SslSettings
    {
        EnabledSslProtocols = System.Security.Authentication.SslProtocols.Tls12 | System.Security.Authentication.SslProtocols.Tls13,
        ServerCertificateValidationCallback = (_, cert, chain, errors) =>
        {
            if (cert is null) return false;
            using var customChain = new X509Chain();
            customChain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
            customChain.ChainPolicy.CustomTrustStore.AddRange(bundle);
            customChain.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck; // ⚠ see Security considerations
            var ok = customChain.Build(new X509Certificate2(cert));
            // Hostname mismatch is still an error we must not ignore.
            return ok && (errors & System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch) == 0;
        }
    };
}

var client = new MongoClient(settings);
var db = client.GetDatabase("catalogue");
await EnsureCollectionAsync(db);
var products = db.GetCollection<ProductDocument>("products");

// Three products with different shapes. All data is fictional.
await products.ReplaceOneAsync(p => p.ProductCode == "SAV-EASY-GBP",
    new ProductDocument
    {
        ProductCode = "SAV-EASY-GBP", ProductType = "savings", Currency = "GBP", Status = "live", Version = 3,
        Name = "Easy Access Saver",
        Attributes = new BsonDocument { { "aerPercent", new BsonDecimal128(4.10m) }, { "withdrawalsPerYear", "unlimited" } },
        Markets = ["GB"]
    }, new ReplaceOptions { IsUpsert = true });

await products.ReplaceOneAsync(p => p.ProductCode == "BOND-2Y-GBP",
    new ProductDocument
    {
        ProductCode = "BOND-2Y-GBP", ProductType = "savings", Currency = "GBP", Status = "live", Version = 1,
        Name = "Two-Year Fixed Rate Bond",
        Attributes = new BsonDocument
        {
            { "aerPercent", new BsonDecimal128(4.55m) }, { "termMonths", 24 },
            { "earlyWithdrawal", new BsonDocument { { "allowed", true }, { "penaltyDaysInterest", 90 } } }
        },
        Markets = ["GB"]
    }, new ReplaceOptions { IsUpsert = true });

await products.ReplaceOneAsync(p => p.ProductCode == "BIZ-CUR-EUR",
    new ProductDocument
    {
        ProductCode = "BIZ-CUR-EUR", ProductType = "business_current", Currency = "EUR", Status = "live", Version = 2,
        Name = "Business Current Account (EUR)",
        Attributes = new BsonDocument
        {
            { "monthlyFee", new BsonDecimal128(9.50m) },
            { "tariff", new BsonArray
                {
                    new BsonDocument { { "upTo", 50 }, { "feePerTxn", new BsonDecimal128(0.00m) } },
                    new BsonDocument { { "upTo", 500 }, { "feePerTxn", new BsonDecimal128(0.25m) } }
                }
            },
            { "disclosures", new BsonArray { "de", "fr", "nl" } }
        },
        Markets = ["IE", "NL", "DE"]
    }, new ReplaceOptions { IsUpsert = true });

// Query 1: live savings products in GB, best rate first. Explicit sort — DocumentDB guarantees no implicit order.
var savings = await products
    .Find(p => p.ProductType == "savings" && p.Status == "live" && p.Markets.Contains("GB"))
    .Sort(Builders<ProductDocument>.Sort.Descending("attributes.aerPercent"))
    .ToListAsync();
foreach (var p in savings) Console.WriteLine($"{p.ProductCode,-14} {p.Name,-28} AER {p.Attributes["aerPercent"]}%");

// Query 2: products with early withdrawal allowed (nested field), using a filter builder.
var flexible = await products
    .Find(Builders<ProductDocument>.Filter.Eq("attributes.earlyWithdrawal.allowed", true))
    .Project(p => p.ProductCode)
    .ToListAsync();
Console.WriteLine($"Early withdrawal allowed: {string.Join(", ", flexible)}");

// Query 3: optimistic concurrency — update only if the version we read is still current.
var bond = await products.Find(p => p.ProductCode == "BOND-2Y-GBP").SingleAsync();
var result = await products.UpdateOneAsync(
    p => p.ProductCode == bond.ProductCode && p.Version == bond.Version,
    Builders<ProductDocument>.Update
        .Set("attributes.aerPercent", new BsonDecimal128(4.60m))
        .Inc(p => p.Version, 1));
Console.WriteLine(result.ModifiedCount == 1 ? "Rate updated" : "Conflict: someone else changed the product");

static async Task EnsureCollectionAsync(IMongoDatabase db)
{
    var existing = await (await db.ListCollectionNamesAsync()).ToListAsync();
    if (!existing.Contains("products"))
    {
        // $jsonSchema validation keeps flexible documents from becoming shapeless documents.
        var validator = new BsonDocument("$jsonSchema", new BsonDocument
        {
            { "bsonType", "object" },
            { "required", new BsonArray { "_id", "productType", "currency", "status", "version" } },
            { "properties", new BsonDocument
                {
                    { "_id", new BsonDocument { { "bsonType", "string" } } },
                    { "currency", new BsonDocument { { "enum", new BsonArray { "GBP", "EUR" } } } },
                    { "status", new BsonDocument { { "enum", new BsonArray { "draft", "live", "withdrawn" } } } },
                    { "version", new BsonDocument { { "bsonType", "int" } } }
                }
            }
        });
        await db.CreateCollectionAsync("products", new CreateCollectionOptions<BsonDocument>
        {
            Validator = validator,
            ValidationAction = DocumentValidationAction.Error
        });
    }

    var coll = db.GetCollection<ProductDocument>("products");
    // _id is already uniquely indexed. Create other indexes one at a time:
    // DocumentDB allows only one index build per collection at once.
    await coll.Indexes.CreateOneAsync(new CreateIndexModel<ProductDocument>(
        Builders<ProductDocument>.IndexKeys.Ascending(p => p.ProductType).Ascending(p => p.Status).Ascending(p => p.Markets)));
}

public sealed class ProductDocument
{
    // The business key is the document _id: unique, immutable and stable across replaces.
    [BsonId] public required string ProductCode { get; set; }
    [BsonElement("productType")] public required string ProductType { get; set; }
    [BsonElement("name")] public required string Name { get; set; }
    [BsonElement("currency")] public required string Currency { get; set; }
    [BsonElement("status")] public required string Status { get; set; }
    [BsonElement("version")] public int Version { get; set; }
    [BsonElement("markets")] public List<string> Markets { get; set; } = [];
    // The variable part of the product, kept as a document.
    [BsonElement("attributes")] public BsonDocument Attributes { get; set; } = [];
}

Expected output (local stand-in or DocumentDB):

BOND-2Y-GBP    Two-Year Fixed Rate Bond     AER 4.55%
SAV-EASY-GBP   Easy Access Saver            AER 4.10%
Early withdrawal allowed: BOND-2Y-GBP
Rate updated

Running it again gives the same output: ReplaceOneAsync with upsert resets each product to its seed state (keyed by _id), and the update then applies once more.

Code explained line by line

  1. MongoClientSettings.FromConnectionString(uri) — the URI comes from configuration; in AWS, build it from the Secrets Manager secret at start-up. Never commit it.
  2. settings.ServerApi = null — the MongoDB Stable API handshake is not part of DocumentDB's implementation; leave it unset.
  3. settings.RetryWrites = false — required on DocumentDB before engine 8.0.2; otherwise writes fail with "Retryable writes are not supported". On 8.0.2+ you can turn it back on after testing.
  4. ReadPreference.SecondaryPreferred — reads go to replicas when available, offloading the primary. Use Primary for read-after-write paths (same lesson as replicas in lesson 9).
  5. ImportFromPemFile(caBundlePath) — loads the AWS RDS/DocumentDB CA bundle, which contains Regional root and intermediate certificates.
  6. X509ChainTrustMode.CustomRootTrust with CustomTrustStore — validates the server certificate against only the AWS bundle, without installing it into the machine's trust store. This is what the tlsCAFile option does in other drivers.
  7. RemoteCertificateNameMismatch check — a valid chain for the wrong host name is still rejected.
  8. [BsonId] public required string ProductCode and ReplaceOneAsync(..., IsUpsert = true) — the product code is the _id, so the replace targets the same document every run (a generated ObjectId would differ per object and break the upsert). Inserts if absent, replaces if present: a repeatable seed.
  9. BsonDecimal128(4.10m) — rates and money are stored as Decimal128, never as doubles.
  10. .Sort(...Descending("attributes.aerPercent")) — explicit order on a nested field, by path; DocumentDB returns results in no guaranteed order.
  11. Filter.Eq("attributes.earlyWithdrawal.allowed", true) — dot notation queries nested fields. Add an index on it if the query is frequent.
  12. Update with p.Version == bond.Version and .Inc(p => p.Version, 1) — optimistic concurrency: a concurrent editor's change makes ModifiedCount 0.
  13. $jsonSchema validator with ValidationAction.Error — the database rejects documents missing required fields or with unknown currencies. Flexible ≠ unvalidated.
  14. Indexes created one after another — DocumentDB fails a second concurrent index build on the same collection. Creating an index that already exists with the same definition is a no-op, so the method is safe to rerun.

Security considerations

⚠ Learning shortcut — not for production

The local container uses a root user with a password in an environment variable and no TLS. On DocumentDB, use a Secrets Manager-managed password with rotation (or IAM authentication where supported), least-privilege database roles per application (read for the catalogue reader, readWrite on one database for the editor), TLS with the AWS CA bundle, and certificate revocation checking appropriate to your organisation's PKI policy rather than NoCheck.

  • Encrypt at creation. Storage encryption cannot be added later without a snapshot restore into a new cluster. Default it on in IaC.
  • Audit. Turn on audit_logs and export to CloudWatch Logs with a defined retention. Audit logs record authentication and DDL/DML events per your filter settings.
  • Data minimisation. Onboarding documents contain identity data (passport numbers, addresses). Store document images in S3 with tight access, and only references and extracted fields in DocumentDB. Plan the erasure process: deleting a document does not delete it from backups until they expire.
  • Query injection. MongoDB-style queries can be injected if you build filters from raw JSON strings. Always use typed builders or parameterised filters; never deserialize a client-supplied filter document.
  • Network. No public access exists; do not create a public bastion. Use SSM Session Manager port forwarding with approval for administrative access.

Banking use case

Harbourline's decision record (abridged):

OptionVerdictReason
Keep the 140-column SQL Server tableRejectedEvery new product needs a schema change and a release
jsonb column in the existing Aurora PostgreSQL catalogue databaseChosen for the catalogue40 products, read-mostly, already on Aurora; GIN index on attributes; no new service to run
DocumentDBChosen for onboarding applications1.2 M applications/year, deeply nested, versioned schemas per country, independent team and lifecycle, heavy querying on nested fields by the operations UI
DynamoDBRejected for bothAd hoc operational queries on nested fields would need many GSIs

The onboarding service stores each application as one document (applicationId, customerId, schemaVersion, sections, status, decisions[]), with $jsonSchema validation per schemaVersion. Approved applications emit an event; the core banking system creates the account in the relational ledger. Money never lives in DocumentDB.

Common mistakes

  • Choosing DocumentDB because "JSON is flexible" → no analysis of alternatives → compare with jsonb and DynamoDB, write the ADR.
  • Assuming full MongoDB parity → a library uses an unsupported operator or the Stable API → run the integration test suite against DocumentDB early; check the supported-API list.
  • Leaving retryWrites=true on engines before 8.0.2 → every write fails → disable it, or upgrade to 8.0.2+ and test.
  • Relying on natural order → results "look sorted" in MongoDB tests → always sort.
  • No schema validation → three spellings of currency within a month → $jsonSchema validators and typed models.
  • Unencrypted cluster created "for now" → cannot enable encryption later → encryption on in IaC from day one.
  • Disabling TLS to "make the driver work" → certificate not trusted → load the AWS CA bundle instead.

Troubleshooting

SymptomLikely causeFix
Timeout connecting to …docdb.amazonaws.com:27017Not in the VPC, or security group closedRun inside the VPC or via SSM port forwarding; allow 27017 from the app SG
The remote certificate is invalid according to the validation procedureAWS CA not trustedLoad global-bundle.pem into a custom trust store as shown
Retryable writes are not supported (code 301)Engine before 8.0.2retryWrites=false in settings or URI
Unsupported … $operator / feature not supportedOperator not implemented in DocumentDBCheck the supported-API list; rewrite the query
Cannot create index … index build already in progressConcurrent index builds on one collectionBuild indexes sequentially
Document fails validation$jsonSchema rule violatedFix the data, or version the schema deliberately
Writes slow during heavy readsAll traffic on the primaryUse secondaryPreferred for reads that tolerate lag; add replicas
mongodump / mongorestore errorsTools newer than 100.11.0Use Database Tools 100.11.0 or earlier

Cost and cleanup

The local stand-in is free. DocumentDB is paid: an instance-based cluster bills per instance-hour (the smallest burstable class is a few US cents per hour ⚠ VERIFY on the pricing page), plus storage per GB-month and, on the Standard storage configuration, I/O requests; backups beyond the cluster's storage size are billed too. A one-hour lab with one small instance and a few MB of data costs well under USD 1, if you delete the cluster the same day. Serverless clusters bill by capacity units consumed; check the minimum capacity.

Free alternative: do the design exercise and run the code against the local mongo:8.0 container, with the DocumentDB-specific settings in place.

docker rm -f hl-m06-mongo
aws docdb delete-db-instance --db-instance-identifier hl-m06-docdb-1 --profile learn-sandbox --region us-east-1
aws docdb wait db-instance-deleted --db-instance-identifier hl-m06-docdb-1 --profile learn-sandbox --region us-east-1
aws docdb delete-db-cluster --db-cluster-identifier hl-m06-docdb --skip-final-snapshot --profile learn-sandbox --region us-east-1
aws docdb delete-db-subnet-group --db-subnet-group-name hl-m06-docdb-subnets --profile learn-sandbox --region us-east-1
# Manual snapshots are NOT deleted with the cluster — list and delete them.
aws docdb describe-db-cluster-snapshots --snapshot-type manual --profile learn-sandbox --region us-east-1
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
  --query "ResourceTagMappingList[].ResourceARN" --profile learn-sandbox --region us-east-1

If Secrets Manager created a master-user secret, it is removed with the cluster; a KMS key you created must be scheduled for deletion separately.

Exercises

  • 🟢 Guided: Run the program locally. Then try to insert a product with currency = "USD" and observe the validation error. Add "USD" only if you can justify it to the product owner.
  • 🟡 Challenge: Implement the same catalogue in PostgreSQL (Docker) with a products table: relational columns for product_code, product_type, currency, status, version, and a jsonb column attributes with a GIN index. Write the three queries in SQL and compare readability and performance.
  • 🔴 Live problem: A vendor's onboarding SaaS integration library was built for MongoDB Atlas. In the DocumentDB test environment, saving an application intermittently fails and the vendor says "DocumentDB is broken". You have the error logs. Plan how to find out what's wrong and decide between DocumentDB and Atlas.

Assignment

Write an ADR "Document storage for onboarding applications" comparing DocumentDB, Aurora PostgreSQL jsonb, DynamoDB and MongoDB Atlas on: fit to access patterns, compatibility risk, security controls (encryption, audit, identity), operational effort, cost at 1.2 M applications/year, and exit strategy. Include the $jsonSchema for one application version.

Solutions

Knowledge check

Interview questions

  • "When would you choose DocumentDB over DynamoDB?" — When the workload needs rich, ad hoc queries and secondary indexes on nested fields with a MongoDB-style API, at moderate scale, rather than predefined key-based access patterns at massive scale.
  • "When would you choose PostgreSQL jsonb instead?" — When documents are part of a mostly relational domain, volumes are modest, and you value constraints, joins and one fewer service.
  • "What are DocumentDB's compatibility risks?" — Unsupported operators/stages, retryable writes before 8.0.2, no implicit ordering, no admin database, tool version limits. Mitigate with integration tests against DocumentDB.
  • "How do you secure DocumentDB?" — VPC-only, SGs, TLS with the AWS CA, encryption at creation with KMS, Secrets Manager rotation or IAM auth, least-privilege roles, audit logs to CloudWatch with retention.

Certification practice

Completion checklist

  • I can explain when a document model fits and when it does not
  • I ran the catalogue code against the local stand-in with validation and indexes
  • I can list five DocumentDB compatibility caveats
  • I can connect to DocumentDB over TLS with the AWS CA bundle from .NET
  • I deleted the container and any DocumentDB cluster, instance, snapshots and subnet group

Key takeaways

  • DocumentDB is MongoDB-compatible, not MongoDB: validate every operator and setting your code and libraries use.
  • Good banking fits are catalogues and applications with varying shapes; money stays in the relational ledger.
  • PostgreSQL jsonb on an existing Aurora cluster is often the simpler answer — write the ADR.
  • Secure it like any data store: VPC-only, TLS with the AWS CA, encryption at creation, rotated credentials, audit logs.
  • Validate documents with $jsonSchema and version your schemas.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page