DocumentDB via SDK Best Practices

Q: How should I handle the database password?

Never store it in code. Use ManageMasterUserPassword so DocumentDB keeps and rotates the credential in Secrets Manager, or use IAM database authentication for a passwordless model. Your app reads the secret at connect time.

Q: How do I scale reads?

Add reader instances with CreateDBInstance; they attach to shared storage in seconds. Route read-only queries to the reader endpoint and set readPreference=secondaryPreferred in the driver so reads reach the replicas.

Q: How do I avoid exhausting connections?

Create one MongoClient at module scope and let the driver pool connections, rather than opening a client per request. Reuse it across warm Lambda invocations, and bound maxPoolSize so a burst of callers cannot overwhelm the instance.

This is the checklist to run before and after building on Amazon DocumentDB from the SDK. Each item is a rule stated positively with a one-line rationale.

Work top to bottom - the groups run roughly in dependency order, from provisioning outward to connections and cost. Remember the model throughout: the SDK provisions and operates the cluster, but a MongoDB driver runs your documents over TLS. Most rules hold whether you provision from the SDK or from IaC.

How to Use This List

Treat each box as an audit question against your own clusters and access code.
The groups run from foundation outward: provision, secure, back up, make available, connect, and control cost.
Rules are SDK-agnostic - they hold for boto3 and AWS SDK v3 alike.
Revisit the list whenever you add an instance, a region, an elastic cluster, or a new caller.

A - Provisioning

Create the cluster, then attach instances. CreateDBCluster makes the storage; CreateDBInstance adds the compute - a cluster with no instance is not connectable.
Encrypt at rest from the start. Set StorageEncrypted=True at create time - you cannot enable it in place later without a snapshot-copy-restore.
Wait on db_instance_available before using an endpoint. The endpoint is unusable while the instance is creating; size maxWaitTime generously.
Use Engine="docdb" and a deliberate EngineVersion. Pick the MongoDB compatibility version your app needs and keep it consistent across the cluster.
Prefer IaC for durable infrastructure. Use the SDK for tooling and learning; define production clusters in CloudFormation, CDK, or Terraform for repeatability.

Create an encrypted cluster with a managed credential, then attach a writer.

# --- Python (boto3) ---
docdb.create_db_cluster(
    DBClusterIdentifier="app-docdb", Engine="docdb", EngineVersion="5.0.0",
    MasterUsername="appuser", ManageMasterUserPassword=True,
    StorageEncrypted=True,
    DBSubnetGroupName="app-docdb-subnets",
    VpcSecurityGroupIds=["sg-0123456789abcdef0"],
)
docdb.create_db_instance(
    DBInstanceIdentifier="app-docdb-writer", DBClusterIdentifier="app-docdb",
    Engine="docdb", DBInstanceClass="db.r6g.large",
)

// --- TypeScript (AWS SDK v3) ---
import { CreateDBClusterCommand, CreateDBInstanceCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new CreateDBClusterCommand({
  DBClusterIdentifier: "app-docdb", Engine: "docdb", EngineVersion: "5.0.0",
  MasterUsername: "appuser", ManageMasterUserPassword: true,
  StorageEncrypted: true,
  DBSubnetGroupName: "app-docdb-subnets",
  VpcSecurityGroupIds: ["sg-0123456789abcdef0"],
}));
await docdb.send(new CreateDBInstanceCommand({
  DBInstanceIdentifier: "app-docdb-writer", DBClusterIdentifier: "app-docdb",
  Engine: "docdb", DBInstanceClass: "db.r6g.large",
}));

B - Security, TLS & Credentials

Never put the master password in code. Use ManageMasterUserPassword so DocumentDB stores and rotates it in Secrets Manager, or use IAM database authentication.
Keep the cluster private. Place it in private subnets via a DBSubnetGroupName and keep it off the public internet.
Restrict port 27017 with security groups. Allow the DocumentDB port only from the application tier's security group, not from anywhere.
Always connect over TLS with the CA bundle. Download global-bundle.pem and pass it to the driver; never disable TLS to work around a certificate error.
Consider IAM database authentication. The MONGODB-AWS mechanism removes stored passwords entirely for supported engine versions and clients.

C - Backups & Disaster Recovery

Enable automated backups with real retention. A BackupRetentionPeriod above 0 turns on continuous backups plus point-in-time recovery.
Set a low-traffic backup window. Use PreferredBackupWindow so backups do not compete with peak load.
Take a manual cluster snapshot before risky changes. Automated backups vanish with the cluster; a manual CreateDBClusterSnapshot persists until you delete it.
Copy snapshots cross-region for DR. CopyDBClusterSnapshot with a destination-region KMS key survives a regional event.
Restore to a new cluster and attach an instance. Restores never overwrite the source and start with no compute; validate before cutting over.

Enable retention and checkpoint before a release.

# --- Python (boto3) ---
docdb.modify_db_cluster(
    DBClusterIdentifier="app-docdb",
    BackupRetentionPeriod=7, PreferredBackupWindow="03:00-04:00",
    ApplyImmediately=True,
)
docdb.create_db_cluster_snapshot(
    DBClusterIdentifier="app-docdb",
    DBClusterSnapshotIdentifier="app-docdb-pre-release",
)

// --- TypeScript (AWS SDK v3) ---
import { ModifyDBClusterCommand, CreateDBClusterSnapshotCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new ModifyDBClusterCommand({
  DBClusterIdentifier: "app-docdb",
  BackupRetentionPeriod: 7, PreferredBackupWindow: "03:00-04:00",
  ApplyImmediately: true,
}));
await docdb.send(new CreateDBClusterSnapshotCommand({
  DBClusterIdentifier: "app-docdb",
  DBClusterSnapshotIdentifier: "app-docdb-pre-release",
}));

D - High Availability & Read Scaling

Run more than one instance in production. A single-instance cluster has no failover target; add at least one reader for availability.
Add readers for read load. Extra instances attach to shared storage in seconds and join the reader endpoint's load balancing.
Route reads to the reader endpoint, writes to the writer. Use the cluster Endpoint for writes and read-after-write, and ReaderEndpoint for read-only queries.
Connect to cluster endpoints, not instance DNS. Cluster endpoints repoint on failover; instance endpoints do not.
Use a global cluster for multi-region DR. CreateGlobalCluster gives cross-region replication with read-only secondaries and fast failover.

Add a reader and route reads to the reader endpoint.

# --- Python (boto3) ---
docdb.create_db_instance(
    DBInstanceIdentifier="app-docdb-reader-2", DBClusterIdentifier="app-docdb",
    Engine="docdb", DBInstanceClass="db.r6g.large",
)
cl = docdb.describe_db_clusters(DBClusterIdentifier="app-docdb")["DBClusters"][0]
print("reads ->", cl["ReaderEndpoint"], " writes ->", cl["Endpoint"])

// --- TypeScript (AWS SDK v3) ---
import { CreateDBInstanceCommand, DescribeDBClustersCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new CreateDBInstanceCommand({
  DBInstanceIdentifier: "app-docdb-reader-2", DBClusterIdentifier: "app-docdb",
  Engine: "docdb", DBInstanceClass: "db.r6g.large",
}));
const dc = await docdb.send(new DescribeDBClustersCommand({ DBClusterIdentifier: "app-docdb" }));
console.log("reads ->", dc.DBClusters![0].ReaderEndpoint, " writes ->", dc.DBClusters![0].Endpoint);

E - Connections, Drivers & Indexes

Remember the SDK does not run your queries. DocumentDB has no Data API; documents go through a MongoDB driver (pymongo / node mongodb).
Always set retryWrites=false. DocumentDB rejects retryable writes, which are on by default in modern drivers.
Pool and reuse connections. Create the MongoClient once at module scope; opening a client per request exhausts the instance's connection budget.
Set a read preference for replica reads. Use secondaryPreferred in the driver so read traffic reaches reader instances.
Index the fields you query and sort on. Create indexes with the driver to match your query and sort patterns; unindexed queries scan the collection.
Reuse SDK clients across invocations. Initialize the docdb client at module scope so warm Lambda invocations skip re-creating it.

Reuse one pooled client for the whole process.

# --- Python (pymongo driver - NOT the AWS SDK) ---
from pymongo import MongoClient
 
# Module scope: created once, connection-pooled, reused across requests.
client = MongoClient(
    "app-docdb.cluster-abc123.us-east-1.docdb.amazonaws.com",
    port=27017, tls=True, tlsCAFile="global-bundle.pem",
    username="appuser", password="from-secrets-manager",
    retryWrites=False, readPreference="secondaryPreferred",
    maxPoolSize=50,
)

F - Cost & Operations

Right-size the instance class. Match DBInstanceClass to real CPU and memory use; oversized instances waste money idle.
Consider an elastic cluster for variable or write-heavy load. Sharded docdb-elastic clusters scale horizontally and can be resized as demand moves.
Prune manual snapshots. They never expire and keep incurring storage cost - tag and clean them on a schedule.
Defer disruptive changes to the maintenance window. Leave ApplyImmediately false for changes that can wait, to avoid surprise downtime.
Alarm on connections, CPU, and replica lag. CloudWatch surfaces connection exhaustion, saturation, and lag before users feel them.
Tag clusters for cost attribution. Consistent tags make spend, cleanup, and ownership discoverable.

FAQs

What is the single most important DocumentDB habit from the SDK?

Separating the planes: the SDK provisions and manages the cluster, and a MongoDB driver runs your documents over TLS. DocumentDB has no Data API, so once you know a task is a query, the answer is always the driver, not the SDK.

Why must I set retryWrites to false?

DocumentDB does not implement retryable writes, and modern MongoDB drivers enable them by default. A connection with retryWrites on will fail. Set retryWrites=False in every driver connection.

How should I handle the database password?

Never store it in code. Use ManageMasterUserPassword so DocumentDB keeps and rotates the credential in Secrets Manager, or use IAM database authentication for a passwordless model. Your app reads the secret at connect time.

Do automated backups survive deleting the cluster?

No. Automated backups are removed with the cluster, aside from an optional final snapshot. For anything you must keep, take a manual cluster snapshot, which persists until you delete it, and copy it cross-region for DR.

How do I scale reads?

Add reader instances with CreateDBInstance; they attach to shared storage in seconds. Route read-only queries to the reader endpoint and set readPreference=secondaryPreferred in the driver so reads reach the replicas.

When should I use an elastic cluster instead of a standard one?

When writes or data outgrow a single writer, or when capacity swings and you want to scale horizontally. Elastic clusters (the docdb-elastic client) shard data and are sized by shard capacity and count. Standard clusters are simpler for steady, single-writer load.

Why does my new cluster's endpoint come back empty?

The cluster has storage but no instance yet, or the instance is still creating. Attach an instance with CreateDBInstance and wait on db_instance_available before reading or connecting to the endpoint.

How do I avoid exhausting connections?

Create one MongoClient at module scope and let the driver pool connections, rather than opening a client per request. Reuse it across warm Lambda invocations, and bound maxPoolSize so a burst of callers cannot overwhelm the instance.

Do these rules apply with IaC too?

Mostly yes. Encryption, private networking, managed credentials, backups and retention, multi-instance availability, and tagging are architectural habits that hold whether you provision from the SDK or from CloudFormation, CDK, or Terraform.

Cluster & Instance Provisioning via SDK - the provisioning rules in group A.
TLS & IAM Database Authentication - the security and TLS rules in group B.
Backup, Restore & Global Clusters - the backup, DR, and availability rules in groups C and D.
DocumentDB Serverless for Variable Workloads - the elastic-cluster cost lever in group F.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

How to Use This List

Treat each box as an audit question against your own clusters and access code.
The groups run from foundation outward: provision, secure, back up, make available, connect, and control cost.
Rules are SDK-agnostic - they hold for boto3 and AWS SDK v3 alike.
Revisit the list whenever you add an instance, a region, an elastic cluster, or a new caller.

A - Provisioning

Create the cluster, then attach instances. CreateDBCluster makes the storage; CreateDBInstance adds the compute - a cluster with no instance is not connectable.
Encrypt at rest from the start. Set StorageEncrypted=True at create time - you cannot enable it in place later without a snapshot-copy-restore.
Wait on db_instance_available before using an endpoint. The endpoint is unusable while the instance is creating; size maxWaitTime generously.
Use Engine="docdb" and a deliberate EngineVersion. Pick the MongoDB compatibility version your app needs and keep it consistent across the cluster.
Prefer IaC for durable infrastructure. Use the SDK for tooling and learning; define production clusters in CloudFormation, CDK, or Terraform for repeatability.

Create an encrypted cluster with a managed credential, then attach a writer.

# --- Python (boto3) ---
docdb.create_db_cluster(
    DBClusterIdentifier="app-docdb", Engine="docdb", EngineVersion="5.0.0",
    MasterUsername="appuser", ManageMasterUserPassword=True,
    StorageEncrypted=True,
    DBSubnetGroupName="app-docdb-subnets",
    VpcSecurityGroupIds=["sg-0123456789abcdef0"],
)
docdb.create_db_instance(
    DBInstanceIdentifier="app-docdb-writer", DBClusterIdentifier="app-docdb",
    Engine="docdb", DBInstanceClass="db.r6g.large",
)

// --- TypeScript (AWS SDK v3) ---
import { CreateDBClusterCommand, CreateDBInstanceCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new CreateDBClusterCommand({
  DBClusterIdentifier: "app-docdb", Engine: "docdb", EngineVersion: "5.0.0",
  MasterUsername: "appuser", ManageMasterUserPassword: true,
  StorageEncrypted: true,
  DBSubnetGroupName: "app-docdb-subnets",
  VpcSecurityGroupIds: ["sg-0123456789abcdef0"],
}));
await docdb.send(new CreateDBInstanceCommand({
  DBInstanceIdentifier: "app-docdb-writer", DBClusterIdentifier: "app-docdb",
  Engine: "docdb", DBInstanceClass: "db.r6g.large",
}));

B - Security, TLS & Credentials

Never put the master password in code. Use ManageMasterUserPassword so DocumentDB stores and rotates it in Secrets Manager, or use IAM database authentication.
Keep the cluster private. Place it in private subnets via a DBSubnetGroupName and keep it off the public internet.
Restrict port 27017 with security groups. Allow the DocumentDB port only from the application tier's security group, not from anywhere.
Always connect over TLS with the CA bundle. Download global-bundle.pem and pass it to the driver; never disable TLS to work around a certificate error.
Consider IAM database authentication. The MONGODB-AWS mechanism removes stored passwords entirely for supported engine versions and clients.

C - Backups & Disaster Recovery

Enable automated backups with real retention. A BackupRetentionPeriod above 0 turns on continuous backups plus point-in-time recovery.
Set a low-traffic backup window. Use PreferredBackupWindow so backups do not compete with peak load.
Take a manual cluster snapshot before risky changes. Automated backups vanish with the cluster; a manual CreateDBClusterSnapshot persists until you delete it.
Copy snapshots cross-region for DR. CopyDBClusterSnapshot with a destination-region KMS key survives a regional event.
Restore to a new cluster and attach an instance. Restores never overwrite the source and start with no compute; validate before cutting over.

Enable retention and checkpoint before a release.

# --- Python (boto3) ---
docdb.modify_db_cluster(
    DBClusterIdentifier="app-docdb",
    BackupRetentionPeriod=7, PreferredBackupWindow="03:00-04:00",
    ApplyImmediately=True,
)
docdb.create_db_cluster_snapshot(
    DBClusterIdentifier="app-docdb",
    DBClusterSnapshotIdentifier="app-docdb-pre-release",
)

// --- TypeScript (AWS SDK v3) ---
import { ModifyDBClusterCommand, CreateDBClusterSnapshotCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new ModifyDBClusterCommand({
  DBClusterIdentifier: "app-docdb",
  BackupRetentionPeriod: 7, PreferredBackupWindow: "03:00-04:00",
  ApplyImmediately: true,
}));
await docdb.send(new CreateDBClusterSnapshotCommand({
  DBClusterIdentifier: "app-docdb",
  DBClusterSnapshotIdentifier: "app-docdb-pre-release",
}));

D - High Availability & Read Scaling

Run more than one instance in production. A single-instance cluster has no failover target; add at least one reader for availability.
Add readers for read load. Extra instances attach to shared storage in seconds and join the reader endpoint's load balancing.
Route reads to the reader endpoint, writes to the writer. Use the cluster Endpoint for writes and read-after-write, and ReaderEndpoint for read-only queries.
Connect to cluster endpoints, not instance DNS. Cluster endpoints repoint on failover; instance endpoints do not.
Use a global cluster for multi-region DR. CreateGlobalCluster gives cross-region replication with read-only secondaries and fast failover.

Add a reader and route reads to the reader endpoint.

# --- Python (boto3) ---
docdb.create_db_instance(
    DBInstanceIdentifier="app-docdb-reader-2", DBClusterIdentifier="app-docdb",
    Engine="docdb", DBInstanceClass="db.r6g.large",
)
cl = docdb.describe_db_clusters(DBClusterIdentifier="app-docdb")["DBClusters"][0]
print("reads ->", cl["ReaderEndpoint"], " writes ->", cl["Endpoint"])

// --- TypeScript (AWS SDK v3) ---
import { CreateDBInstanceCommand, DescribeDBClustersCommand } from "@aws-sdk/client-docdb";
 
await docdb.send(new CreateDBInstanceCommand({
  DBInstanceIdentifier: "app-docdb-reader-2", DBClusterIdentifier: "app-docdb",
  Engine: "docdb", DBInstanceClass: "db.r6g.large",
}));
const dc = await docdb.send(new DescribeDBClustersCommand({ DBClusterIdentifier: "app-docdb" }));
console.log("reads ->", dc.DBClusters![0].ReaderEndpoint, " writes ->", dc.DBClusters![0].Endpoint);

E - Connections, Drivers & Indexes

Remember the SDK does not run your queries. DocumentDB has no Data API; documents go through a MongoDB driver (pymongo / node mongodb).
Always set retryWrites=false. DocumentDB rejects retryable writes, which are on by default in modern drivers.
Pool and reuse connections. Create the MongoClient once at module scope; opening a client per request exhausts the instance's connection budget.
Set a read preference for replica reads. Use secondaryPreferred in the driver so read traffic reaches reader instances.
Index the fields you query and sort on. Create indexes with the driver to match your query and sort patterns; unindexed queries scan the collection.
Reuse SDK clients across invocations. Initialize the docdb client at module scope so warm Lambda invocations skip re-creating it.

Reuse one pooled client for the whole process.

# --- Python (pymongo driver - NOT the AWS SDK) ---
from pymongo import MongoClient
 
# Module scope: created once, connection-pooled, reused across requests.
client = MongoClient(
    "app-docdb.cluster-abc123.us-east-1.docdb.amazonaws.com",
    port=27017, tls=True, tlsCAFile="global-bundle.pem",
    username="appuser", password="from-secrets-manager",
    retryWrites=False, readPreference="secondaryPreferred",
    maxPoolSize=50,
)

F - Cost & Operations

Right-size the instance class. Match DBInstanceClass to real CPU and memory use; oversized instances waste money idle.
Consider an elastic cluster for variable or write-heavy load. Sharded docdb-elastic clusters scale horizontally and can be resized as demand moves.
Prune manual snapshots. They never expire and keep incurring storage cost - tag and clean them on a schedule.
Defer disruptive changes to the maintenance window. Leave ApplyImmediately false for changes that can wait, to avoid surprise downtime.
Alarm on connections, CPU, and replica lag. CloudWatch surfaces connection exhaustion, saturation, and lag before users feel them.
Tag clusters for cost attribution. Consistent tags make spend, cleanup, and ownership discoverable.

FAQs

What is the single most important DocumentDB habit from the SDK?

Why must I set retryWrites to false?

DocumentDB does not implement retryable writes, and modern MongoDB drivers enable them by default. A connection with retryWrites on will fail. Set retryWrites=False in every driver connection.

How should I handle the database password?

Do automated backups survive deleting the cluster?

How do I scale reads?

When should I use an elastic cluster instead of a standard one?

Why does my new cluster's endpoint come back empty?

How do I avoid exhausting connections?

Do these rules apply with IaC too?

Cluster & Instance Provisioning via SDK - the provisioning rules in group A.
TLS & IAM Database Authentication - the security and TLS rules in group B.
Backup, Restore & Global Clusters - the backup, DR, and availability rules in groups C and D.
DocumentDB Serverless for Variable Workloads - the elastic-cluster cost lever in group F.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

DocumentDB via SDK Best Practices

Search Documentation

DocumentDB via SDK Best Practices