AWS.DocDB reference

ApplyPendingMaintenanceAction

Source: src/AWS/DocDB/ApplyPendingMaintenanceAction.ts

Runtime binding for the ApplyPendingMaintenanceAction operation (IAM action rds:ApplyPendingMaintenanceAction — DocumentDB shares the RDS control plane).

Opts a DocumentDB cluster or instance into a pending maintenance action (system-update, db-upgrade, ca-certificate-rotation) immediately or at the next maintenance window — the apply half of maintenance automation. The target is an ARN carried in the request, so the grant spans the account. Provide the implementation with Effect.provide(AWS.DocDB.ApplyPendingMaintenanceActionHttp).

ApplyPendingMaintenanceAction: Maintenance

const applyPending = yield* DocDB.ApplyPendingMaintenanceAction();

yield* applyPending({
  ResourceIdentifier: clusterArn,
  ApplyAction: "system-update",
  OptInType: "next-maintenance",
});

Connect

Source: src/AWS/DocDB/Connect.ts

Runtime binding that resolves MongoDB connection settings for a DocumentDB DBCluster from a Secrets Manager secret (the cluster’s managed master user secret by default).

Binding it yields an Effect (not a callable) that resolves a MongoConnectionInfo — host, port, credentials, and a ready-to-use mongodb:// URL — fresh on every execution. No socket is opened; feed the result into mongo (the bundled Effect client over the mongodb driver) or any MongoDB driver. The deploy half grants secretsmanager:GetSecretValue on the secret and publishes the endpoint as environment variables. Provide the implementation with Effect.provide(AWS.DocDB.ConnectHttp).

Connect: Connecting to a Cluster

Query DocumentDB from a Function

export default MyFunction.make(
  { main: import.meta.url, functionUrl: true },
  Effect.gen(function* () {
    // init — bind the cluster's managed master secret; grants
    // secretsmanager:GetSecretValue and attaches the function to the
    // cluster's VPC subnets/security groups
    const connect = yield* AWS.DocDB.Connect(cluster, {
      database: "app",
      subnetIds: [subnetA.subnetId, subnetB.subnetId],
      securityGroupIds: [appSecurityGroup.groupId],
    });
    // init — build the Effect mongo client (one connection per execution)
    const db = yield* AWS.DocDB.mongo(connect);

    return {
      fetch: Effect.gen(function* () {
        const { use } = yield* db;
        const orders = yield* use((db) =>
          db.collection("orders").find({ open: true }).toArray(),
        );
        return yield* HttpServerResponse.json({ count: orders.length });
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(AWS.DocDB.ConnectHttp)),
);

Resolve Raw Connection Info

// init
const connect = yield* AWS.DocDB.Connect(cluster, { database: "app" });

// runtime — host/port/credentials plus a ready-to-use mongodb:// URL
const info = yield* connect;

CopyDBClusterSnapshot

Source: src/AWS/DocDB/CopyDBClusterSnapshot.ts

Runtime binding for the CopyDBClusterSnapshot operation (IAM action rds:CopyDBClusterSnapshot — DocumentDB shares the RDS control plane).

Copies a DocumentDB cluster snapshot — to a new name, another KMS key, or (with a pre-signed URL) another region — the core of snapshot fan-out and DR automation. Source and target identifiers are runtime data, so the grant spans the account’s cluster-snapshot ARNs. Provide the implementation with Effect.provide(AWS.DocDB.CopyDBClusterSnapshotHttp).

CopyDBClusterSnapshot: Managing Snapshots

const copySnapshot = yield* DocDB.CopyDBClusterSnapshot();

yield* copySnapshot({
  SourceDBClusterSnapshotIdentifier: "nightly-2026-07-15",
  TargetDBClusterSnapshotIdentifier: "archive-2026-07-15",
});

CreateDBClusterSnapshot

Source: src/AWS/DocDB/CreateDBClusterSnapshot.ts

Runtime binding for the CreateDBClusterSnapshot operation (IAM action rds:CreateDBClusterSnapshot).

Takes an on-demand snapshot of the bound DBCluster — e.g. a backup function that snapshots before a risky migration. The cluster identifier is injected from the binding; the grant covers both the cluster ARN and the account’s cluster-snapshot ARN space (both resources must be allowed for snapshot creation). Provide the implementation with Effect.provide(AWS.DocDB.CreateDBClusterSnapshotHttp).

CreateDBClusterSnapshot: Operating a Cluster

// init — bind the operation to the cluster
const createDBClusterSnapshot =
  yield* AWS.DocDB.CreateDBClusterSnapshot(cluster);

// runtime
const { DBClusterSnapshot } = yield* createDBClusterSnapshot({
  DBClusterSnapshotIdentifier: `pre-migration-${runId}`,
});

DBCluster

Source: src/AWS/DocDB/DBCluster.ts

An Amazon DocumentDB (MongoDB-compatible) cluster.

DBCluster owns the writer and reader endpoints and cluster-wide networking; instances are added via DBInstance. It can bootstrap master credentials directly or let DocumentDB manage them in Secrets Manager. Provisioning a cluster (and its first instance) takes several minutes.

Mutable fields are reconciled in place against the observed cloud state; immutable fields (engine, dbSubnetGroupName, storageEncrypted, kmsKeyId, globalClusterIdentifier, availabilityZones, masterUsername) force a replacement.

DBCluster: Creating a Cluster

const cluster = yield* DBCluster("Docs", {
  dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
  vpcSecurityGroupIds: [sg.groupId],
  masterUsername: "alchemy",
  manageMasterUserPassword: true,
  backupRetentionPeriod: "7 days",
  deletionProtection: false,
});

DBCluster: Logs & Encryption

const cluster = yield* DBCluster("Docs", {
  dbSubnetGroupName: subnetGroup.dbSubnetGroupName,
  masterUsername: "alchemy",
  masterUserPassword: Redacted.make("supersecret"),
  storageEncrypted: true,
  enableCloudwatchLogsExports: ["audit", "profiler"],
});

DBInstance

Source: src/AWS/DocDB/DBInstance.ts

An Amazon DocumentDB instance — a compute member of a DocumentDB DBCluster. Storage, backup, and endpoints are managed at the cluster level; the instance contributes CPU/RAM and can serve as a writer or reader. Provisioning takes several minutes.

Mutable fields (dbInstanceClass, promotionTier, maintenance window, monitoring) are reconciled in place; immutable fields (engine, dbClusterIdentifier, availabilityZone) force a replacement.

DBInstance: Adding an Instance

const writer = yield* DBInstance("Writer", {
  dbClusterIdentifier: cluster.dbClusterIdentifier,
  dbInstanceClass: "db.t3.medium",
});

DBSubnetGroup

Source: src/AWS/DocDB/DBSubnetGroup.ts

An Amazon DocumentDB subnet group — the set of VPC subnets a DocumentDB cluster and its instances are placed into. DocumentDB is VPC-only, so a subnet group spanning at least two Availability Zones is required before a cluster can be created.

DBSubnetGroup: Creating a Subnet Group

const subnetGroup = yield* DBSubnetGroup("DocDbSubnets", {
  subnetIds: [subnetA.subnetId, subnetB.subnetId],
});

DeleteDBClusterSnapshot

Source: src/AWS/DocDB/DeleteDBClusterSnapshot.ts

Runtime binding for the DeleteDBClusterSnapshot operation (IAM action rds:DeleteDBClusterSnapshot — DocumentDB shares the RDS control plane).

Deletes a DocumentDB cluster snapshot by identifier — the retention half of snapshot-rotation automation (create nightly, prune the oldest). Snapshot identifiers are runtime data, so the grant spans the account’s cluster-snapshot ARNs. Provide the implementation with Effect.provide(AWS.DocDB.DeleteDBClusterSnapshotHttp).

DeleteDBClusterSnapshot: Managing Snapshots

const deleteSnapshot = yield* DocDB.DeleteDBClusterSnapshot();

yield* deleteSnapshot({
  DBClusterSnapshotIdentifier: "nightly-2026-06-01",
}).pipe(
  // already gone — rotation is idempotent
  Effect.catchTag("DBClusterSnapshotNotFoundFault", () => Effect.void),
);

DescribeDBClusters

Source: src/AWS/DocDB/DescribeDBClusters.ts

Runtime binding for the DescribeDBClusters operation (IAM action rds:DescribeDBClusters).

Lists the account’s DocumentDB clusters (or one cluster by identifier) — status, endpoints, members, engine versions — for health checks and cluster discovery. Provide the implementation with Effect.provide(AWS.DocDB.DescribeDBClustersHttp).

DescribeDBClusters: Monitoring Clusters

const describeDBClusters = yield* AWS.DocDB.DescribeDBClusters();

const page = yield* describeDBClusters({
  DBClusterIdentifier: clusterId,
});
const status = page.DBClusters?.[0]?.Status;

DescribeDBClusterSnapshots

Source: src/AWS/DocDB/DescribeDBClusterSnapshots.ts

Runtime binding for the DescribeDBClusterSnapshots operation (IAM action rds:DescribeDBClusterSnapshots — DocumentDB shares the RDS control plane).

Lists the account’s DocumentDB cluster snapshots (optionally filtered by cluster or snapshot identifier) with status and creation time embedded — pairs with CreateDBClusterSnapshot/DeleteDBClusterSnapshot for backup automation. Provide the implementation with Effect.provide(AWS.DocDB.DescribeDBClusterSnapshotsHttp).

DescribeDBClusterSnapshots: Managing Snapshots

const describeSnapshots = yield* DocDB.DescribeDBClusterSnapshots();

const page = yield* describeSnapshots({
  DBClusterSnapshotIdentifier: "nightly-2026-07-15",
});
const status = page.DBClusterSnapshots?.[0]?.Status;

DescribeDBInstances

Source: src/AWS/DocDB/DescribeDBInstances.ts

Runtime binding for the DescribeDBInstances operation (IAM action rds:DescribeDBInstances — DocumentDB shares the RDS control plane).

Lists the account’s DocumentDB instances (optionally filtered by identifier or cluster) with status, endpoint, and class embedded — the building block of instance-health monitoring and reboot automation. Provide the implementation with Effect.provide(AWS.DocDB.DescribeDBInstancesHttp).

DescribeDBInstances: Monitoring Instances

const describeDBInstances = yield* DocDB.DescribeDBInstances();

const page = yield* describeDBInstances({
  Filters: [{ Name: "db-cluster-id", Values: [clusterId] }],
});
const available = page.DBInstances?.filter(
  (instance) => instance.DBInstanceStatus === "available",
);

DescribeEvents

Source: src/AWS/DocDB/DescribeEvents.ts

Runtime binding for the DescribeEvents operation (IAM action rds:DescribeEvents).

Returns events related to DocumentDB clusters, instances, snapshots, and parameter groups from the last 24 hours (up to 14 days with an explicit time window) — failovers, maintenance, configuration changes. Provide the implementation with Effect.provide(AWS.DocDB.DescribeEventsHttp).

DescribeEvents: Monitoring Clusters

const describeEvents = yield* AWS.DocDB.DescribeEvents();

const page = yield* describeEvents({
  SourceIdentifier: clusterId,
  SourceType: "db-cluster",
});
for (const event of page.Events ?? []) {
  yield* Effect.logInfo(`${event.Date}: ${event.Message}`);
}

DescribePendingMaintenanceActions

Source: src/AWS/DocDB/DescribePendingMaintenanceActions.ts

Runtime binding for the DescribePendingMaintenanceActions operation (IAM action rds:DescribePendingMaintenanceActions — DocumentDB shares the RDS control plane).

Lists pending maintenance actions (engine patches, certificate rotations) across the account’s DocumentDB clusters and instances — pairs with ApplyPendingMaintenanceAction for maintenance automation. Provide the implementation with Effect.provide(AWS.DocDB.DescribePendingMaintenanceActionsHttp).

DescribePendingMaintenanceActions: Maintenance

const describePending = yield* DocDB.DescribePendingMaintenanceActions();

const page = yield* describePending();
for (const resource of page.PendingMaintenanceActions ?? []) {
  yield* Effect.log(
    `${resource.ResourceIdentifier}: ${resource.PendingMaintenanceActionDetails?.length} pending`,
  );
}

FailoverDBCluster

Source: src/AWS/DocDB/FailoverDBCluster.ts

Runtime binding for the FailoverDBCluster operation (IAM action rds:FailoverDBCluster).

Forces a failover of the bound DBCluster — one of the replicas is promoted to primary — for resilience testing or to move the writer to a specific instance. The cluster identifier is injected from the binding. Provide the implementation with Effect.provide(AWS.DocDB.FailoverDBClusterHttp).

FailoverDBCluster: Operating a Cluster

// init — bind the operation to the cluster
const failoverDBCluster = yield* AWS.DocDB.FailoverDBCluster(cluster);

// runtime — promote a specific replica
yield* failoverDBCluster({
  TargetDBInstanceIdentifier: replicaId,
});

mongo

Source: src/AWS/DocDB/Mongo.ts

Open an Effect-typed MongoDB client from a DocumentDB connection (the runtime Effect produced by binding AWS.DocDB.Connect).

The connect work is deferred until first use and memoized on the current execution’s Scope (via makeExecutionMemo), so the driver connection is built at most once per execution — a Lambda invocation or Worker event — and its close finalizer fires when the execution settles, never held across events. This is the one legal pooling shape on workerd (sockets are IoContext-pinned) and the correct one on Lambda.

DocumentDB authenticates over the MongoDB wire protocol: database users and their built-in roles (read, readWrite, dbAdmin, clusterAdmin, …) are managed inside the database with db.createUser(...) — IAM only governs the management plane.

mongo: Connecting to a Cluster

Query a Collection inside a Function

// init — bind the cluster, then build the client
const connect = yield* AWS.DocDB.Connect(cluster, { database: "app" });
const db = yield* AWS.DocDB.mongo(connect);

// runtime — one driver connection per execution, closed on settle
const { use } = yield* db;
const open = yield* use((db) =>
  db.collection("orders").find({ open: true }).toArray(),
);

Create a Database User (DB-plane auth)

const { use } = yield* db;
yield* use((db) =>
  db.admin().command({
    createUser: "reporting",
    pwd: reportingPassword,
    roles: [{ role: "read", db: "app" }],
  }),
);

RebootDBInstance

Source: src/AWS/DocDB/RebootDBInstance.ts

Runtime binding for the RebootDBInstance operation (IAM action rds:RebootDBInstance).

Reboots the bound DBInstance — e.g. an ops function applying a parameter-group change that requires a restart. The instance identifier is injected from the binding. Provide the implementation with Effect.provide(AWS.DocDB.RebootDBInstanceHttp).

RebootDBInstance: Operating an Instance

// init — bind the operation to the instance
const rebootDBInstance = yield* AWS.DocDB.RebootDBInstance(instance);

// runtime — optionally force a failover during the reboot
yield* rebootDBInstance({ ForceFailover: false });

StartDBCluster

Source: src/AWS/DocDB/StartDBCluster.ts

Runtime binding for the StartDBCluster operation (IAM action rds:StartDBCluster).

Starts the bound DBCluster after it was stopped — e.g. an ops function that wakes a development cluster on a schedule. The cluster identifier is injected from the binding. Provide the implementation with Effect.provide(AWS.DocDB.StartDBClusterHttp).

StartDBCluster: Operating a Cluster

// init — bind the operation to the cluster
const startDBCluster = yield* AWS.DocDB.StartDBCluster(cluster);

// runtime
yield* startDBCluster();

StopDBCluster

Source: src/AWS/DocDB/StopDBCluster.ts

Runtime binding for the StopDBCluster operation (IAM action rds:StopDBCluster).

Stops the bound DBCluster — compute billing pauses while storage is retained (up to 7 days, after which DocumentDB starts it back up) — e.g. an ops function that parks a development cluster overnight. The cluster identifier is injected from the binding. Provide the implementation with Effect.provide(AWS.DocDB.StopDBClusterHttp).

StopDBCluster: Operating a Cluster

// init — bind the operation to the cluster
const stopDBCluster = yield* AWS.DocDB.StopDBCluster(cluster);

// runtime
yield* stopDBCluster();