LibreChat/packages/data-schemas/misc/documentdb/documentdb-compat.md

Amazon DocumentDB Compatibility Assessment (issue #14488)

Adjudicated against official AWS documentation on 2026-07-28. Engine columns throughout: DocumentDB 3.6 / 4.0 / 5.0 / 8.0 instance-based and elastic clusters. AWS's supported-APIs page states that unsupported operators are omitted from its tables, so several verdicts below are implicit-by-omission and flagged as such.

Executive summary

• The login blocker was real: three aggregation-pipeline updates (one using $$NOW) existed in the codebase. DocumentDB documents no support for pipeline-form updates on any engine version. All three are now rewritten with plain update operators that work on every engine, including elastic.
• Partial-index creation fails on DocumentDB < 5.0 and elastic — and the failure was provably silent (no log, no crash, uniqueness quietly unenforced). Model creation now attaches an index listener so failed builds log loudly.
• Transactions already degrade gracefully via a runtime probe. GridFS is unreachable dead code. retryWrites=false is a deployment-docs item.
• Recommendation: DocumentDB 5.0+ instance-based is a supportable target; 4.0 runs but with degraded uniqueness enforcement (now logged); elastic clusters should be documented as unsupported (no unique indexes at all).

Proven incompatibilities — fixed in this PR

1. acceptTerms pipeline update + $$NOW (P0 — blocked login)

packages/data-schemas/src/methods/user.ts:303 used a pipeline-form findByIdAndUpdate with $ifNull/$$NOW (introduced by PR #10810, matching the reporter's regression window). When Terms gating is on, every login hits this and DocumentDB rejects it.

AWS evidence: the supported APIs page lists only classic update operators (no pipeline form anywhere); the $set/ $unset stage operators are marked unsupported for 3.6/4.0/5.0; $$NOW is absent from the System variables table entirely ($$CURRENT and $$REMOVE are explicitly "No"). Implicit-by-omission, but consistent with the reported Failed to parse update: field must be of BSON type object class of error (AWS documents no exact error string).

Fix: null-guarded first-acceptance claim (termsAcceptedAt: null matches both the schema's explicit null default and missing legacy fields — a $exists: false guard would never fire because of that default), with a plain-$set fallback for repeat acceptance. First-acceptance timestamp preservation, concurrency convergence, and the IUser | null contract are covered by tests, including a raw-inserted legacy document without the field.

2. decrementTagCounts pipeline update (P1 — silent tag-count drift)

packages/data-schemas/src/methods/conversationTag.ts:47 used a $max/$subtract/$ifNull pipeline inside bulkWrite, wrapped in a try/catch that only logs — on DocumentDB, conversation deletion succeeded while tag counts silently drifted.

Fix: two mutually exclusive plain ops per tag in one ordered bulkWrite — clamp-to-zero (count below the decrement amount, or null/missing) first, then a guarded $inc. Clamp-at-zero, missing-count tolerance, and variable-amount semantics all preserved; now covered by a new test block (previously untested).

3. extendFilesTTL pipeline update (P1 — /files/usage TTL holds fail)

packages/data-schemas/src/methods/file.ts:607 — not in the reporter's list; found by sweeping the codebase (rg for pipeline-shaped update args and $$NOW; these three sites were the only hits).

Fix: read the candidate files (one projected query), compute each file's min(now + renewMs, createdAt + maxLifetimeMs) ceiling client-side, then issue per-document guarded $sets (expiresAt: { $exists: true, $lt: next }) through tenantSafeBulkWrite. Only-widens, per-file ceiling, and cleared-TTL-stays-permanent semantics are preserved under concurrency by the write guard. Cost: one extra read round trip on this path — unavoidable without a schema change, because the ceiling is per-document.

Proven, made loud — partial indexes (P1 on < 5.0 / elastic)

Four unique partial indexes exist:

• packages/data-schemas/src/schema/user.ts:192 and :199 — OAuth ids (googleId, openidId, …) with partialFilterExpression: { $exists: true }
• packages/data-schemas/src/schema/file.ts:173 — execute_code files ($eq-shaped filter)
• packages/data-schemas/src/schema/group.ts:56 — group source ids ($exists: true)

AWS: partial-index.html — "The partial index feature is supported in Amazon DocumentDB 5.0 instance-based clusters"; the index-properties table marks Partial as No/No/Yes/Yes/No across 3.6/4.0/5.0/8.0/elastic. The $exists and $eq filter shapes used here are inside DocumentDB 5.0's supported operator list ($eq, $exists, $and, $gt/$gte/$lt/$lte), so on 5.0+ these indexes build.

On 3.6/4.0/elastic the builds fail — and empirically (probe: unique index over pre-seeded duplicates, mongoose 8, autoIndex) the failure is completely silent: no unhandled rejection, no log, the index simply doesn't exist and duplicate inserts succeed. Mongoose only surfaces build errors through a Model.on('index') listener, which nothing attached. createModels now attaches one that logs every failed build (packages/data-schemas/src/models/index.ts). Operational consequence on < 5.0 remains: OAuth-account uniqueness is not DB-enforced — documented, loud, but not fixable in application code.

Proven compatible — no action needed

• Transactions: supported on 4.0+ instance-based ("Amazon DocumentDB … supports transactions in Amazon DocumentDB 4.0 and later" — transactions.html); unsupported on 3.6 and elastic. LibreChat already probes at runtime (packages/data-schemas/src/utils/transactions.ts, cached in api/server/services/PermissionService.js) and falls back to non-transactional writes — the same mode as standalone MongoDB without a replica set. DocumentDB's restrictions (1-minute execution limit, no cursors in transactions, no retryable commit/abort) don't intersect LibreChat's usage.
• GridFS: packages/api/src/cache/keyvMongo.ts only constructs a GridFSBucket when useGridFS is set — no caller ever sets it and the class isn't exported (the singleton uses a plain logs collection). Dead code. Moot regardless: AWS lists GridFS as supported on instance-based clusters (elastic: no).
• TTL indexes: supported everywhere including elastic. AWS warns deletion is best-effort ("Documents are not guaranteed to be deleted within any specific period") — acceptable, since LibreChat treats TTL as cleanup, not as a security boundary.
• $ifNull: supported on all versions (only its pipeline-update context was the problem).

Deployment requirements (documentation, not code)

• retryWrites=false is mandatory in MONGO_URI. AWS: "Amazon DocumentDB does not currently support retryable writes"; the failure mode is {"ok":0,"errmsg":"Unrecognized field: 'txnNumber'","code":9} (functional-differences.html). api/db/connect.js passes MONGO_URI through verbatim, so this belongs in the deployment docs (and the live harness flags a URI missing it).
• TLS with the AWS CA bundle; clusters are VPC-only (tunnel/bastion for external access).

Document as unsupported — elastic clusters

Elastic cluster limitations: no unique indexes (any), no partial indexes, no ACID transactions, no GridFS, no change streams, $expr unsupported, and the cursor-methods table even lists sort()/skip()/limit() as "No". The email + tenantId unique index alone disqualifies elastic clusters. Recommend stating this explicitly in the docs.

Undetermined — honest gaps

• The reporter's engine version and cluster type — still unknown; it decides whether the partial-index caveat applies to them (5.0+: it doesn't). Worth asking directly on the issue.
• DocumentDB 8.0 pipeline-update acceptance — 8.0 added $set/$unset aggregation stages, but AWS never documents pipeline-form updates; the harness probe answers this live.
• collMod is only "Partial" on every version — avoid Model.syncIndexes() against DocumentDB (it may issue collMod beyond the documented expireAfterSeconds).
• Read-side aggregations (3 files: methods/prompt.ts, methods/aclEntry.ts, methods/agentCategory.ts) were not audited stage-by-stage; no exotic stages ($facet, $setWindowFields, $unionWith, $graphLookup) are used anywhere.
• No faithful local emulator exists. The documentdb-local Docker image is the PostgreSQL-based Linux Foundation project — AWS's own OSS blog confirms "a different engine than the one used in Amazon DocumentDB." Live regression testing must run against a real cluster.

Regression strategy

1. In-repo (CI today): the behavioral tests added in user.methods.spec.ts, conversationTag.methods.spec.ts, and file.spec.ts lock the pipeline-free implementations' semantics (first-acceptance preservation, clamp-at-zero, per-file ceiling).
2. Live harness (this directory): compat.documentdb.spec.ts exercises the exact operations behind #14488 against a real cluster and prints a capability matrix (pipeline updates, $$NOW, transactions, partial unique indexes, TTL, retryWrites). Gated on DOCUMENTDB_URI; verified green against real MongoDB as a baseline. Suggested cadence: before releases and whenever update-operator code in data-schemas changes; optionally a scheduled GitHub Action on a runner with VPC access to a dev cluster.

Support matrix and recommendation

Capability (LibreChat dependency)	3.6	4.0	5.0	8.0	Elastic
Pipeline updates (no longer used)	✗	✗	✗	?	✗
Plain update operators (all writes now)	✓	✓	✓	✓	✓
Unique indexes	✓	✓	✓	✓	✗
Partial unique indexes (OAuth ids)	✗	✗	✓	✓	✗
Transactions (runtime-probed)	✗	✓	✓	✓	✗
TTL indexes	✓	✓	✓	✓	✓

Recommendation: support DocumentDB 5.0+ instance-based with retryWrites=false documented as required. 4.0 functions with partial-unique-index loss (now logged loudly at startup) — "works, with a documented caveat". Elastic clusters: unsupported, full stop.