[RFC] MongoDB Storage Backend

AGENTS.md

@@ -10,7 +10,7 @@ by AWS engineers. It is not a fork of DynamoDB and contains no DynamoDB source c
 protocol: any AWS SDK, CLI, or tool that works with DynamoDB works with ExtendDB, unchanged.
 
 - **Language:** Rust (edition 2024, MSRV 1.88+)
-- **Storage backend:** PostgreSQL 14+
+- **Storage backends:** PostgreSQL 14+ (default), MongoDB 7.0+ (feature flag `mongodb`)
 - **Architecture:** Async (tokio), trait-based storage abstraction
 - **Authentication:** Mandatory SigV4 with built-in IAM (users, groups, roles, policies)
 - **TLS:** Mandatory (self-signed cert generated by default)
@@ -51,7 +51,8 @@ extenddb/
 
 The `TableEngine` trait in `crates/storage/src/lib.rs` defines the storage interface. All storage backends implement this trait:
 
-- **Current:** `storage-postgres` (PostgreSQL)
+- `storage-postgres` (PostgreSQL) — default backend
+- `storage-mongodb` (MongoDB) — feature flag `mongodb`
 
 The trait uses RPITIT (return-position impl Trait in traits) for async methods — no `#[async_trait]` macro.
 
@@ -66,12 +67,14 @@ extenddb (bin)
        │    ├─> extenddb-core (pure sync, no async)
        │    └─> extenddb-storage (trait definitions)
        ├─> extenddb-auth
-       └─> extenddb-storage-postgres
+       ├─> extenddb-storage-postgres (feature: postgres)
+       └─> extenddb-storage-mongodb  (feature: mongodb)
 ```
 
 - **extenddb-core:** Pure synchronous Rust. No async, no I/O. Types, validation, expression parsing.
 - **extenddb-storage:** Trait definitions only. No implementation.
 - **extenddb-storage-postgres:** Concrete PostgreSQL implementation.
+- **extenddb-storage-mongodb:** Concrete MongoDB implementation.
 - **extenddb-engine:** Operation handlers that call storage traits.
 - **extenddb-server:** HTTP server, management API, web console.
 - **extenddb-auth:** SigV4 signature verification, IAM policy evaluation.
@@ -82,13 +85,22 @@ extenddb (bin)
 ### Prerequisites
 
 - Rust 1.88+ (`rustup update`)
-- PostgreSQL 14+ running locally (see `docs/local-postgres-setup.md`)
+- Storage backend (one of):
+  - PostgreSQL 14+ running locally (see `docs/local-postgres-setup.md`)
+  - MongoDB 7.0+ with replica set (see `docs/local-mongodb-setup.md`)
 - Python 3.10+ for tests (`python3 -m venv ~/venvs/extenddb-venv && source ~/venvs/extenddb-venv/bin/activate && pip install -r requirements.txt`)
 
 ### Build
 
 ```bash
+# PostgreSQL backend (default)
 cargo build --release
+
+# MongoDB backend
+cargo build --release --features mongodb
+
+# Both backends
+cargo build --release --features postgres,mongodb
 ```
 
 Binary: `target/release/extenddb`
@@ -109,11 +121,15 @@ cargo clippy --all-targets -- -D warnings
 ### Initialize (first time only)
 
 ```bash
+# PostgreSQL (default)
 ./target/release/extenddb init --config extenddb.toml
+
+# MongoDB
+./target/release/extenddb init --backend mongodb --config extenddb.toml
 ```
 
 This creates:
-- PostgreSQL databases (`extenddb_catalog`, `extenddb_account_<id>`)
+- Databases (`extenddb_catalog`, `extenddb_data`)
 - Admin user credentials (printed to stdout — save the password!)
 - Self-signed TLS certificate at `~/.extenddb/tls/cert.pem`
 - Config file `extenddb.toml`
@@ -357,6 +373,9 @@ Expression parsing lives in `crates/core/src/expression/`. This is pure sync Rus
 | Differences from DynamoDB | `docs/differences-from-dynamodb.md`               | Behavioral differences                 |
 | Troubleshooting | `docs/troubleshooting.md`                         | Common errors and solutions            |
 | Storage Component Design | `docs/design/04-component-storage.md`             | Storage trait design                   |
+| MongoDB Design | `docs/design/13-storage-mongodb.md`               | MongoDB backend architecture           |
+| Local PostgreSQL Setup | `docs/local-postgres-setup.md`                    | PostgreSQL installation and config     |
+| Local MongoDB Setup | `docs/local-mongodb-setup.md`                     | MongoDB installation and config        |
 | Testing Design | `docs/design/09-testing.md`                       | Test strategy and infrastructure       |
 | Extending Storage | `12-backend-plugin-architecture.md` | Guide to implementing storage backends |
 
@@ -448,9 +467,10 @@ Activate when the user asks about installing, configuring, running, or debugging
 1. **TLS is mandatory** — server refuses to start without it. Use `AWS_CA_BUNDLE` for self-signed certs.
 2. **Auth is mandatory** — all requests must be SigV4-signed. Use `extenddb manage` or web console to create credentials.
 3. **Account isolation** — all operations are scoped to `account_id`. Different accounts can have tables with the same name.
-4. **PostgreSQL must be running** — `extenddb init` and `extenddb serve` require a running PostgreSQL instance.
-5. **Python venv** — activate the venv before running tests: `source ~/venvs/extenddb-venv/bin/activate`
-6. **Test credentials** — run `devtools/provision-test-credentials` before pytest to create test users and keys.
+4. **Storage backend must be running** — `extenddb init` and `extenddb serve` require a running PostgreSQL or MongoDB instance.
+5. **MongoDB requires a replica set** — even single-node MongoDB must be configured with `--replSet` for transactions and streams.
+6. **Python venv** — activate the venv before running tests: `source ~/venvs/extenddb-venv/bin/activate`
+7. **Test credentials** — run `devtools/provision-test-credentials` before pytest to create test users and keys.
 
 ## Getting Help