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.
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
jsonbon Aurora and with DynamoDB for the same use case, and write the decision down.
Prerequisites
- Amazon DynamoDB fundamentals — access-pattern thinking
- Amazon ElastiCache (Valkey/Redis OSS) — private data-store networking
- Docker Desktop and the .NET 10 SDK
- Optional: an AWS account for a short, paid deploy-and-destroy (see Cost and cleanup)
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
| Strength | Detail |
|---|---|
| Flexible, nested data | Products and applications with varying shapes, without nullable-column sprawl |
| Read a whole aggregate at once | One document = one product with its tariffs, documents and eligibility rules |
| Managed operations | Patching, backups to S3 with point-in-time restore, automatic storage growth, up to 15 read replicas in an instance-based cluster |
| Storage decoupled from compute | Six copies across three AZs (Aurora-style); failover to a replica typically in well under a minute ⚠ VERIFY current failover guidance |
| MongoDB API and drivers | Existing MongoDB skills and the official .NET driver work |
| Options | Instance-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:
| Caveat | What it means |
|---|---|
| Compatibility, not identity | Implements 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 writes | Supported only from engine 8.0.2; on earlier versions you must set retryWrites=false |
| Result ordering | No implicit order; always sort() |
| Index builds | One index build per collection at a time |
admin / local databases | Not supported; mongodump/mongorestore do not carry users and roles |
| Tooling | MongoDB Database Tools up to and including 100.11.0 |
$vectorSearch | Not supported as a stage; vector search is available inside $search |
| VPC only | Clusters live in your VPC; no public endpoint; you need a bastion, VPN or SSM port forwarding to reach it from a laptop |
| Pricing | Instance-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 equivalent | What'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 vCore | DocumentDB instance-based cluster | Closest match: you pick instance sizes |
SQL Server JSON columns / OPENJSON | PostgreSQL jsonb on Aurora | Often enough: keep relational integrity for the core, JSON for the variable part |
| MongoDB Atlas on Azure | MongoDB Atlas on AWS (Marketplace) | Use Atlas if you need full MongoDB feature parity |
| Azure Cosmos DB for NoSQL | DynamoDB | Key-value/document with access-pattern design; different API |
| Entity Framework Core | MongoDB 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_logscluster parameter and export audit and profiler logs to CloudWatch Logs with retention.
When a document model fits — the decision
| Workload | Best fit | Why |
|---|---|---|
| Product catalogue: varying attributes, read-mostly, nested tariffs | DocumentDB or PostgreSQL jsonb | Natural documents; few writers; rich queries on attributes |
| Onboarding applications with versioned, country-specific sections | DocumentDB or jsonb with JSON Schema validation | Shape varies; whole application read and written as a unit |
| Account ledger, balances, postings | Relational (RDS/Aurora) | Constraints, joins, mature ACID semantics, reconciliation SQL |
| Idempotency keys, high-volume key lookups | DynamoDB | Single-digit ms at any scale, conditional writes, TTL |
| Full-text search over documents | OpenSearch | Relevance ranking and analyzers |
| Existing MongoDB app needing full feature parity | MongoDB Atlas | Avoid 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.0Treat 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.0Add 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 runThe 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
- Console → Amazon DocumentDB → Clusters → Create.
- Cluster type: Instance-based cluster (or Serverless if available for your engine version in us-east-1).
- Engine version: 8.0 for new work (retryable writes from 8.0.2, correlated
$lookupsubqueries); 5.0 if your driver/tooling requires it. - Instance class: the smallest burstable class for a lab; number of instances: 1 for a lab (production: at least 3 across AZs).
- Authentication: username
hladmin, Manage master credentials in AWS Secrets Manager so the password is generated and rotatable. - Network: your lab VPC, a subnet group of private subnets, security group allowing 27017 from the app security group only.
- Encryption at rest: On, with a KMS key (cannot be changed later).
- 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.
- Add tags
Project=cea-lab,Lab=m06-docdb,Environment=learn. Create cluster. - 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.pemCheck --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
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
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 updatedRunning 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
MongoClientSettings.FromConnectionString(uri)— the URI comes from configuration; in AWS, build it from the Secrets Manager secret at start-up. Never commit it.settings.ServerApi = null— the MongoDB Stable API handshake is not part of DocumentDB's implementation; leave it unset.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.ReadPreference.SecondaryPreferred— reads go to replicas when available, offloading the primary. UsePrimaryfor read-after-write paths (same lesson as replicas in lesson 9).ImportFromPemFile(caBundlePath)— loads the AWS RDS/DocumentDB CA bundle, which contains Regional root and intermediate certificates.X509ChainTrustMode.CustomRootTrustwithCustomTrustStore— validates the server certificate against only the AWS bundle, without installing it into the machine's trust store. This is what thetlsCAFileoption does in other drivers.RemoteCertificateNameMismatchcheck — a valid chain for the wrong host name is still rejected.[BsonId] public required string ProductCodeandReplaceOneAsync(..., IsUpsert = true)— the product code is the_id, so the replace targets the same document every run (a generatedObjectIdwould differ per object and break the upsert). Inserts if absent, replaces if present: a repeatable seed.BsonDecimal128(4.10m)— rates and money are stored as Decimal128, never as doubles..Sort(...Descending("attributes.aerPercent"))— explicit order on a nested field, by path; DocumentDB returns results in no guaranteed order.Filter.Eq("attributes.earlyWithdrawal.allowed", true)— dot notation queries nested fields. Add an index on it if the query is frequent.- Update with
p.Version == bond.Versionand.Inc(p => p.Version, 1)— optimistic concurrency: a concurrent editor's change makesModifiedCount0. $jsonSchemavalidator withValidationAction.Error— the database rejects documents missing required fields or with unknown currencies. Flexible ≠ unvalidated.- 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_logsand 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):
| Option | Verdict | Reason |
|---|---|---|
| Keep the 140-column SQL Server table | Rejected | Every new product needs a schema change and a release |
jsonb column in the existing Aurora PostgreSQL catalogue database | Chosen for the catalogue | 40 products, read-mostly, already on Aurora; GIN index on attributes; no new service to run |
| DocumentDB | Chosen for onboarding applications | 1.2 M applications/year, deeply nested, versioned schemas per country, independent team and lifecycle, heavy querying on nested fields by the operations UI |
| DynamoDB | Rejected for both | Ad 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
jsonband 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=trueon 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
currencywithin a month →$jsonSchemavalidators 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
| Symptom | Likely cause | Fix |
|---|---|---|
Timeout connecting to …docdb.amazonaws.com:27017 | Not in the VPC, or security group closed | Run inside the VPC or via SSM port forwarding; allow 27017 from the app SG |
The remote certificate is invalid according to the validation procedure | AWS CA not trusted | Load global-bundle.pem into a custom trust store as shown |
Retryable writes are not supported (code 301) | Engine before 8.0.2 | retryWrites=false in settings or URI |
Unsupported … $operator / feature not supported | Operator not implemented in DocumentDB | Check the supported-API list; rewrite the query |
Cannot create index … index build already in progress | Concurrent index builds on one collection | Build indexes sequentially |
| Document fails validation | $jsonSchema rule violated | Fix the data, or version the schema deliberately |
| Writes slow during heavy reads | All traffic on the primary | Use secondaryPreferred for reads that tolerate lag; add replicas |
mongodump / mongorestore errors | Tools newer than 100.11.0 | Use 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-mongoaws 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-1If 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
productstable: relational columns forproduct_code,product_type,currency,status,version, and ajsonbcolumnattributeswith 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
The insert fails with a "Document failed validation" error, because the currency enum allows only GBP and EUR. That is the point: the validator is a business rule in the database, like a CHECK constraint. Adding USD is a product decision (Harbourline does not offer USD products) and a schema-change record, not a quick fix.
CREATE TABLE products (
product_code text PRIMARY KEY,
product_type text NOT NULL,
currency char(3) NOT NULL CHECK (currency IN ('GBP','EUR')),
status text NOT NULL CHECK (status IN ('draft','live','withdrawn')),
version int NOT NULL,
markets text[] NOT NULL,
attributes jsonb NOT NULL
);
CREATE INDEX products_attributes_gin ON products USING gin (attributes jsonb_path_ops);
-- Query 1
SELECT product_code, (attributes->>'aerPercent')::numeric AS aer
FROM products
WHERE product_type = 'savings' AND status = 'live' AND 'GB' = ANY(markets)
ORDER BY aer DESC;
-- Query 2
SELECT product_code FROM products WHERE attributes @> '{"earlyWithdrawal":{"allowed":true}}';
-- Query 3
UPDATE products SET attributes = jsonb_set(attributes, '{aerPercent}', '4.60'), version = version + 1
WHERE product_code = 'BOND-2Y-GBP' AND version = 1;Why: for a 40-product catalogue already next to Aurora, jsonb gives the same flexibility plus relational constraints and no extra service. That is why Harbourline chose it for the catalogue.
- Collect evidence: the exact error codes and messages, driver version and settings (Stable API,
retryWrites), and the operations the library issues (enable the profiler on the test cluster). - Check known differences: retryable writes on engines before 8.0.2 (code 301), Stable API, unsupported operators or stages, implicit ordering assumptions, transactions over the limits, and
admindatabase commands. - Test each failing operation in isolation against DocumentDB 8.0.2+ and against MongoDB.
- Decide: if fixes are configuration (disable retryable writes, upgrade engine), stay on DocumentDB. If the library relies on unsupported features and the vendor will not adapt, choose MongoDB Atlas on AWS (private connectivity, encryption, contractual and data-residency review) and record why.
- Either way, add a compatibility test suite to CI that runs against the real target.
Knowledge check
Answer: No. It is an AWS-built engine that implements the MongoDB API (3.6, 4.0, 5.0, 8.0) on Aurora-style distributed storage. Most applications work with the standard drivers, but some features and behaviours differ.
Answer: Retryable writes are supported only from engine 8.0.2. Most drivers enable them by default, so writes fail with an error until you disable them.
Answer: Not in place. Take a snapshot and restore it into a new cluster with encryption enabled.
Answer: Good: product catalogues with varying attributes; onboarding applications with versioned nested sections. Bad: the ledger and balances, which need relational constraints and mature transactional semantics.
Answer: $jsonSchema validation in the database, typed models in code, a schemaVersion field with migrations, and indexes on the fields you query.
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
A company is migrating an on-premises MongoDB application to AWS. It wants a managed service, minimal code changes, and automatic storage scaling across three Availability Zones. The application uses common CRUD operations and aggregation stages. What should a solutions architect recommend?
A. Amazon DynamoDB with a single-table design. B. Amazon DocumentDB, after validating the operators the application uses. C. Amazon RDS for PostgreSQL with JSON columns. D. MongoDB on Amazon EC2 with EBS volumes.
Answer: B. DocumentDB is MongoDB-compatible and managed, with storage replicated across three AZs. DynamoDB requires a rewrite (A). PostgreSQL needs code and query changes (C). EC2 is self-managed (D).
A team created an Amazon DocumentDB cluster without encryption at rest for testing and now must use it for production data that must be encrypted with a customer managed KMS key. What should they do?
A. Modify the cluster to enable storage encryption. B. Enable TLS in the cluster parameter group. C. Take a snapshot and restore it to a new cluster with encryption enabled using the customer managed key. D. Enable default EBS encryption in the account.
Answer: C. Encryption at rest is set at creation; restoring a snapshot into an encrypted cluster is the supported path. It cannot be modified in place (A). TLS protects data in transit (B). DocumentDB storage is not EBS (D).
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
jsonbon 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
$jsonSchemaand 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.
Amazon ElastiCache (Valkey/Redis OSS)
Use ElastiCache for Valkey safely in a bank: cache-aside with .NET HybridCache, distributed session state, atomic rate-limit counters with a Lua script, choosing serverless or node-based caches, securing them with TLS, RBAC or IAM authentication — and knowing what must never be cached.
Amazon Redshift and S3 as data stores
Separate operational and analytical data: move transaction history out of the OLTP database into a partitioned S3 data lake with a reconciled archive job, query it with Athena, and know when a Redshift Serverless warehouse (or zero-ETL) earns its cost.