Busca en todas las páginas de la documentación
DocumentDB has two halves, and this page walks through both. The AWS SDK creates the cluster, attaches an instance, and hands you an endpoint. A MongoDB driver then connects to that endpoint over TLS and runs your documents. The SDK never runs a query.
Each example is small and shows either the AWS SDK call or, where relevant, how its result feeds a normal MongoDB driver. Read them in order - create the cluster, add an instance, read the endpoints, connect, then manage credentials.
pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-docdb (Node.js 18+).pip install pymongo (Python) or npm install mongodb (Node.js). These are MongoDB drivers, not AWS SDKs.curl -o global-bundle.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem.aws configure, environment variables, or an IAM role - the SDK resolves them automatically.AWS_REGION or passed per client. These examples assume us-east-1 and a cluster named app-docdb.# --- Python (boto3) ---
import boto3
docdb = boto3.client("docdb", region_name="us-east-1")// --- TypeScript (AWS SDK v3) ---
import { DocDBClient } from "@aws-sdk/client-docdb";
const docdb = new DocDBClient({ region: "us-east-1" });A DocumentDB cluster owns the storage but has no compute until you attach an instance. Create the cluster with CreateDBCluster, then add an instance with CreateDBInstance, then wait for the instance to become available.
# --- Python (boto3) ---
docdb.create_db_cluster(
DBClusterIdentifier="app-docdb", Engine="docdb",
MasterUsername="appuser", ManageMasterUserPassword=True,
StorageEncrypted=True,
)
docdb.create_db_instance(
DBInstanceIdentifier="app-docdb-1", DBClusterIdentifier="app-docdb",
Engine="docdb", DBInstanceClass="db.t3.medium",
)
docdb.get_waiter("db_instance_available").wait(DBInstanceIdentifier="app-docdb-1")
print("cluster ready - it now has an instance to connect to")// --- TypeScript (AWS SDK v3) ---
import {
CreateDBClusterCommand, CreateDBInstanceCommand, waitUntilDBInstanceAvailable,
} from "@aws-sdk/client-docdb";
await docdb.send(new CreateDBClusterCommand({
DBClusterIdentifier: "app-docdb", Engine: "docdb",
MasterUsername: "appuser", ManageMasterUserPassword: true,
StorageEncrypted: true,
}));
await docdb.send(new CreateDBInstanceCommand({
DBInstanceIdentifier: "app-docdb-1", DBClusterIdentifier: "app-docdb",
Engine: "docdb", DBInstanceClass: "db.t3.medium",
}));
await waitUntilDBInstanceAvailable({ client: docdb, maxWaitTime: 1200 }, { DBInstanceIdentifier: "app-docdb-1" });
console.log("cluster ready - it now has an instance to connect to");Engine is "docdb" on both the cluster and the instance - not "mongodb".ManageMasterUserPassword puts the credential in Secrets Manager instead of your code.db_instance_available - the endpoint is unusable while the instance is creating.Related: Cluster & Instance Provisioning via SDK.
DescribeDBClusters returns the writer endpoint and the reader endpoint. Both listen on port 27017, and both are what your MongoDB driver connects to.
# --- Python (boto3) ---
cl = docdb.describe_db_clusters(DBClusterIdentifier="app-docdb")["DBClusters"][0]
print("writer endpoint:", cl["Endpoint"]) # points at the current writer
print("reader endpoint:", cl["ReaderEndpoint"]) # load-balances across readers
print("port:", cl["Port"]) # 27017
print("status:", cl["Status"])// --- TypeScript (AWS SDK v3) ---
import { DescribeDBClustersCommand } from "@aws-sdk/client-docdb";
const out = await docdb.send(new DescribeDBClustersCommand({ DBClusterIdentifier: "app-docdb" }));
const cl = out.DBClusters![0];
console.log("writer endpoint:", cl.Endpoint); // points at the current writer
console.log("reader endpoint:", cl.ReaderEndpoint); // load-balances across readers
console.log("port:", cl.Port); // 27017
console.log("status:", cl.Status);Endpoint is the cluster (writer) endpoint - send writes and read-after-write here.ReaderEndpoint load-balances read-only connections across reader instances.Port is 27017 by default, the MongoDB wire-protocol port.Related: DocumentDB's MongoDB-Compatible Model.
The endpoint from the previous step feeds a MongoDB driver. This is a driver connection, not an AWS SDK call - the SDK is done once you have the host. DocumentDB requires TLS and does not support retryable writes.
# --- Python (pymongo driver - NOT the AWS SDK) ---
from pymongo import MongoClient
client = MongoClient(
host="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, # required: DocumentDB has no retryable writes
)
client["shop"]["orders"].insert_one({"sku": "A-1", "qty": 2})
print(client["shop"]["orders"].find_one({"sku": "A-1"}))pymongo, a MongoDB driver - the AWS SDK has no query API for DocumentDB.tls=True with the downloaded CA bundle is mandatory; connections without TLS are refused.retryWrites=False is required - DocumentDB does not implement retryable writes.mongodb; the same host, TLS, and options apply.Related: TLS & IAM Database Authentication.
ManageMasterUserPassword stores the master credential in Secrets Manager instead of your code. Read its ARN from the cluster, then fetch the password your driver needs.
# --- Python (boto3) ---
import json
cl = docdb.describe_db_clusters(DBClusterIdentifier="app-docdb")["DBClusters"][0]
secret_arn = cl["MasterUserSecret"]["SecretArn"]
sm = boto3.client("secretsmanager", region_name="us-east-1")
creds = json.loads(sm.get_secret_value(SecretId=secret_arn)["SecretString"])
print("username:", creds["username"]) # password is creds["password"]// --- TypeScript (AWS SDK v3) ---
import { DescribeDBClustersCommand } from "@aws-sdk/client-docdb";
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
const out = await docdb.send(new DescribeDBClustersCommand({ DBClusterIdentifier: "app-docdb" }));
const secretArn = out.DBClusters![0].MasterUserSecret!.SecretArn!;
const sm = new SecretsManagerClient({ region: "us-east-1" });
const secret = await sm.send(new GetSecretValueCommand({ SecretId: secretArn }));
const creds = JSON.parse(secret.SecretString!);
console.log("username:", creds.username); // password is creds.passwordMasterUserSecret.SecretArn after the cluster is available.creds["username"] and creds["password"] into the driver from example 3.Related: TLS & IAM Database Authentication.
A second instance in the same cluster becomes a reader. Because storage is shared, it attaches in seconds without copying data, and the reader endpoint starts load-balancing across it.
# --- Python (boto3) ---
docdb.create_db_instance(
DBInstanceIdentifier="app-docdb-2", DBClusterIdentifier="app-docdb",
Engine="docdb", DBInstanceClass="db.t3.medium",
)
docdb.get_waiter("db_instance_available").wait(DBInstanceIdentifier="app-docdb-2")
cl = docdb.describe_db_clusters(DBClusterIdentifier="app-docdb")["DBClusters"][0]
print("reads ->", cl["ReaderEndpoint"], " writes ->", cl["Endpoint"])// --- TypeScript (AWS SDK v3) ---
import { CreateDBInstanceCommand, DescribeDBClustersCommand, waitUntilDBInstanceAvailable } from "@aws-sdk/client-docdb";
await docdb.send(new CreateDBInstanceCommand({
DBInstanceIdentifier: "app-docdb-2", DBClusterIdentifier: "app-docdb",
Engine: "docdb", DBInstanceClass: "db.t3.medium",
}));
await waitUntilDBInstanceAvailable({ client: docdb, maxWaitTime: 1200 }, { DBInstanceIdentifier: "app-docdb-2" });
const out = await docdb.send(new DescribeDBClustersCommand({ DBClusterIdentifier: "app-docdb" }));
console.log("reads ->", out.DBClusters![0].ReaderEndpoint, " writes ->", out.DBClusters![0].Endpoint);ReaderEndpoint and writes to Endpoint.readPreference=secondaryPreferred to send reads to replicas.Related: Cluster & Instance Provisioning via SDK.
Standard RDS provisions a database in a single CreateDBInstance. DocumentDB always separates storage from compute like Aurora: CreateDBCluster creates the shared storage volume, and CreateDBInstance with a DBClusterIdentifier attaches compute. A cluster with zero instances exists but has nothing to connect to - the writer endpoint has no instance behind it. Always create at least one instance and wait on db_instance_available before pointing a driver at the endpoint.
A create call returns in milliseconds with the resource in creating, and the endpoint is unusable until an instance is available. Use the db_instance_available waiter (or poll Status on the cluster and DBInstanceStatus on the instance) before the next step depends on the new state. Give the waiter a generous maxWaitTime because instance provisioning takes several minutes.
CreateDBInstance and wait for it before connecting.tls=True with the downloaded CA bundle.retryWrites on. The MongoDB default enables retryable writes, which DocumentDB rejects. Fix: set retryWrites=False in the driver.creating. Fix: wait on db_instance_available, then describe.docdb API to find or insert. Fix: connect with pymongo / the node mongodb driver.A cluster owns storage but has no compute until you attach an instance. Call CreateDBInstance with the cluster id, wait on db_instance_available, and then connect. The endpoint has no instance behind it until then.
Use the cluster Endpoint (the writer) for writes and read-after-write, and the ReaderEndpoint for read-only queries. Both come from DescribeDBClusters and both listen on port 27017.
DocumentDB requires TLS by default and rejects plaintext connections. Download the DocumentDB CA bundle and pass tls=True with tlsCAFile pointing at it. Also set retryWrites=False, which DocumentDB requires.
If you set ManageMasterUserPassword, DocumentDB stores and rotates it in AWS Secrets Manager and reports the secret ARN under MasterUserSecret. Your app reads the current value at connect time instead of holding a password in code.
No. The docdb client only provisions and manages the cluster. Documents go through a MongoDB driver such as pymongo or the node mongodb package over the endpoint. DocumentDB has no Data API.
Add reader instances to the cluster with CreateDBInstance. Because storage is shared, they attach in seconds without copying data. Route read-only queries to the reader endpoint, optionally with readPreference=secondaryPreferred in the driver.
db.t3.medium is a reasonable small default for development. For production, size to real CPU and memory use with a db.r6g or db.r5 class, and match reader size to writer size for balanced load.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última actualización: 24 jul 2026