documentdb.md

DocumentDB controls and a real document compatibility backend

DocumentDB owns scoped cluster, single-writer instance, snapshot, tag and retained lifecycle intent. A pinned MongoDB 7.0.43 process owns BSON documents, indexes, queries, SCRAM authentication and native replica-set change streams. There is no in-memory document store, canned query result, automatic AWS forwarding or engine fallback. MongoDB is not the AWS DocumentDB engine. The implemented boundary is a local compatibility backend, not distributed DocumentDB storage or complete MongoDB/DocumentDB behavioral equivalence.

Native setup

Install the immutable Docker Official Image explicitly:

docker pull mongo@sha256:84c4a18b60a0e73d1577112b0a600b46cab477c64cfe0ff36d0647bbca055bd0
go build -o /tmp/stackd-docdb ./cmd/stackd
/tmp/stackd-docdb -listen 127.0.0.1:4566 \
  -database /tmp/owned-docdb.sqlite -docker-host unix:///var/run/docker.sock \
  -docdb-runtime -compute-endpoint http://host.docker.internal:4566

The pin comes from the upstream mongo:7.0.43-jammy source. -docdb-image accepts an explicitly installed immutable compatible override; the runtime never pulls. Config.DocumentDBRuntime supplies the same caller-owned engine contract to embedders. A stable namespace derived from the SQLite path owns containers and volumes. Persistent shutdown detaches; ephemeral shutdown removes its exact-owned native resources. Never run two controllers against the same metadata/namespace.

Create a docdb cluster and then a CreateDBInstance writer. The empty control-plane cluster reports available, as required by the AWS CLI creation contract. It has no document endpoint and ResolveCluster.Ready stays false until the real writer completes authenticated native readiness. The control contract selects engine family 5.0; this does not relabel the binary, whose native buildInfo remains MongoDB 7.0.43. Instance classes are identifiers, not AWS hardware capacity.

The returned endpoint binds Docker-host loopback only. TLS is mandatory; clients explicitly trust the owner-generated CA and authenticate against admin with their database credentials. Native replica discovery advertises localhost:<the same published port>, replica-set name stackd. Use retryWrites=false. The API does not invent a CA field in AWS response shapes: embedders/source adapters obtain public trust material through the authoritative connection lookup; a local operator can read /data/db/security/ca.pem from its exact-owned container. The host/Docker daemon remain trusted. Remote Docker needs an explicit localhost tunnel preserving the port; this is not AWS VPC networking. Requests attaching subnet groups/security groups or claiming managed encryption, serverless scaling, scheduled maintenance and managed secrets fail rather than becoming inert metadata. Backup retention/window settings own real daily cold snapshot work and expiry; they do not claim continuous online AWS backups.

One shared RDS Query namespace

The authoritative SDK models give RDS and DocumentDB the same signing name, endpoint prefix, API version, XML namespace and arn:...:rds:... resource namespace. Ordinary aws rds, aws docdb, boto3 and Go v2 SDK clients therefore use the same local endpoint. There is no user-agent classifier or invented service hostname.

RDS composes the public Query boundary: Engine=docdb selects the document owner; identifier/ARN commands resolve the current retained owner; clusters, instances and cluster snapshots are unioned before existing filtering/pagination. A marker from one official SDK works in the other. The owner repositories share the transaction domain and prevent duplicate public identifiers; there is no second resource registry. Model-generated typed projections reject RDS-only fields for a DocumentDB command instead of silently dropping requested effects. The generator runs with make generate-aws and its drift check.

This follows the documented RDS cross-engine list and DocumentDB shared management/filter contract. Resource authority is rds:<operation> with current IAM/resource/request tags. The existing protected RDS service-linked role and KMS credential cipher protect retained master credentials. DocumentDB resources also prevent that role's premature deletion. This internal credential encryption is not database-volume storage encryption.

Retention, transitions and snapshots

Typed memory/SQLC repositories persist cluster/instance/snapshot intent, incarnations, generation-fenced work, encrypted credentials and public CA bytes. Native effects happen after repository transactions close. Create, start, stop, reboot, password change, deletion, snapshot and restore join the shared job driver. Readiness is actual authenticated native readiness, not a timer or successful container allocation. Controller replacement reattaches retained data and trust material before publishing availability. Stop closes the real listening process; start retains documents. Old master credentials fail after native password change. A failed native writer can be deleted even while its failed operation retains a retry deadline. Deletion supersedes that intent with generation-fenced retirement; an in-progress healthy creation cannot be canceled through this failed-state path. Unlike AWS's managed seven-day automatic restart, a stopped local cluster currently stays stopped until StartDBCluster; that retained deadline remains an explicit lifecycle gap.

Snapshots are cold physical copies of the complete native database directory. They briefly stop client connections and restart the source. A restored cluster requires its own writer, native volume, endpoint/trust identity and control-plane incarnation. Snapshot credentials and bytes survive source password changes and source deletion; subsequent source writes are not part of an earlier snapshot. This is not an online AWS snapshot or point-in-time recovery. Deletion requires explicit SkipFinalSnapshot; callers create a supported manual snapshot first instead of receiving a fake final backup.

BackupRetentionPeriod admits 1–35 days and defaults to 1. PreferredBackupWindow uses a UTC window of at least 30 minutes; the local default is 09:00-09:30, not AWS's randomly selected regional window. The shared service-time scheduler commits one generation-fenced daily snapshot intent before its native cold copy. Retries keep the same immutable snapshot incarnation. Missed windows produce one current real snapshot, not invented historical data. Automated copies appear as SnapshotType=automated in both official SDKs. Retention changes recompute exact-owned expiry from each copy's creation time. Expiry waits for in-progress restores, commits retirement, and then deletes the native snapshot outside the transaction. Cluster deletion retires its automated copies but leaves manual snapshots. The typed deadlines and policy survive SQLite reopen through schema415.

This is a daily local backup adapter over MongoDB's physical copy capability. AWS continuously backs up data and supports any point within the retention period; that online storage and oplog/time-index recovery owner remains absent. Do not treat the local cold snapshot's connection pause as AWS behavior.

Service.ResolveCluster(ctx, arn) is the authoritative Lambda source boundary: current rds:DescribeDBClusters authority, an available writer, immutable RuntimeID, native address/port/replica-set and public CA. It returns no password. Lambda owns current Secrets Manager/KMS retrieval, polling, batching, retries and opaque resume tokens. It must bind tokens to the immutable incarnation rather than copying cluster state or treating a replaced name as the same source. Source lookup passes its reader's transaction context into current IAM policy evaluation, joining the shared SQLite read rather than opening a second connection. The durable source regression exercises a real assumed-role allow followed by policy revocation; retained source identity never caches the earlier grant.

Evidence

testdata/aws/docdb_controls.json captures six fresh native observations in the authorized account/region on 2026-09-28, each with its native request ID. The probe verified STS identity and made zero mutations: three absent-resource errors, a missing parameter group, invalid list page size and native engine-version metadata. No AWS database, subnet, role or other billable resource was provisioned; there was nothing to clean up. Native version metadata and the unsupported parameter-group observation are evidence, not local parity claims.

scripts/aws/docdb_executable_smoke.py launches the actual CLI and uses signed boto3 requests, official Go v2 decoded controls/modeled errors, and a real PyMongo client at the returned endpoint. It exercises trusted TLS, wrong-password, untrusted/plaintext transport rejection, BSON insert/query/change stream, password rotation, stop/start, SQLite/controller restart, resume-token continuity, independent physical snapshot/restore and survival after source deletion. Current IAM denial, cross-region absence, source-filtered snapshots, RDS SDK engine filtering, shared-name collision, and rejected-control CloudTrail history are exercised. Exact-owned Docker containers and volumes are checked absent and both controller exits are zero. Observed reports are retained in testdata/integration/docdb_runtime.json, including a final native PostgreSQL/MySQL application regression and a separate ephemeral CLI shutdown that removed its active database and physical snapshot.

Run the reproducible local workflow with installed boto3 and pymongo:

go build -o /tmp/docdb-sdk-smoke ./scripts/docdb_sdk_smoke
python3 -B scripts/aws/docdb_executable_smoke.py \
  --binary /tmp/stackd-docdb --sdk-binary /tmp/docdb-sdk-smoke \
  --state-directory /tmp/new-owned-docdb-proof

--with-rds additionally requires the pinned SQL images documented in RDS and exercises shared public-name rejection. Engine-native race tests also exercise container replacement, change-stream resume, password retry, foreign-resource refusal and actual physical snapshot independence. The durable repository regression proves source identity/credential/audit rollback, restart and account isolation. A signed Go SDK regression proves mixed-owner pagination, engine filtering, cross-SDK markers, owner mutation and RDS-only-field rejection. These are bounded workflows, not exhaustive service conformance.

The permanent Terraform workflow is examples/terraform-storage. Install the pinned Mongo image, boto3, pymongo, Terraform1.15.9 and the AWS6.68.0 filesystem mirror, then run:

python3 examples/terraform-storage/run.py --services docdb \
  --provider-mirror /absolute/path/to/provider/mirror

This workflow uses an owned paused service timeline to exercise daily backup and expiry without waiting 24 wall-clock hours. It declares cluster/writer resources, imports them, changes the native password, tags, backup retention and window, consumes binary BSON through verified TLS and SCRAM, checks transaction rollback and independent restored bytes, reopens SQLite, and destroys its exact-owned resources. The new workflow and transition regressions are unverified until run; the fixture emits a report only for completed stages. docdb-limits.json records prerequisites, source references and exact resource/settings gaps. The generated provider inventory remains the authoritative list of every current-provider resource and data source, not a lifecycle pass claim.

Explicit differences and remaining operations

The AWS functional differences and change-stream guide remain the reference, not generic MongoDB documentation:

• Native MongoDB change streams are available from its replica-set oplog. AWS's modifyChangeStreams enable/disable command, default-disabled collection state, managed retention and DocumentDB-specific token/error behavior are not implemented. The backend returns a real unsupported-command error for that AWS-specific command; it does not fake enabling a feed. Native oplog tokens and resume behavior are not asserted identical to AWS tokens.
• MongoDB supports capabilities AWS DocumentDB rejects, including retryable writes and certain commands/operators/admin databases. Those remain native MongoDB semantics outside the supported compatibility boundary, not a claimed AWS validation layer. Implicit multi-document atomicity, query plans, index rules, cursor timing and transaction limits are not calibrated as AWS-equivalent.
• Managed distributed storage, readers/failover/Multi-AZ, global clusters, elastic/serverless capacity, cloud VPC/SG/NACL enforcement, AWS CA rotation, IAM database authentication and customer-managed storage encryption are absent.
• Parameter/subnet groups, continuous online backups/PITR, snapshot sharing/copy/export, scheduled maintenance, engine upgrades, managed secret rotation, event subscriptions and the remaining generated control operations return explicit unsupported errors. No successful billable native DocumentDB lifecycle capture is claimed. Audit projection is generated/documentation-derived, not a new successful-management native audit calibration.

Intentional TODO: Comeback owners are internal/services/docdb/service.go for the remaining managed/native-contract capabilities and internal/services/docdb/lifecycle.go for seven-day automatic restart. RDS's separate remaining boundaries stay in RDS.