[RFC] MongoDB Storage Backend

.github/workflows/integration-mongodb.yml

@@ -0,0 +1,67 @@
+# Copyright 2026 ExtendDB contributors
+# SPDX-License-Identifier: Apache-2.0
+name: MongoDB Integration Tests
+
+on:
+  pull_request:
+  merge_group:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# The MongoDB backend needs a replica set (single-node --replSet + rs.initiate()
+# + wait-for-PRIMARY) for transactions and streams, which GitHub `services:`
+# cannot express. `devtools/run-mongodb-tests` performs that bootstrap, then
+# init/serve/provision extenddb and delegates the workload to
+# `run-tests --backend mongodb`, tearing everything down on exit. Both jobs
+# reuse it so CI runs the exact path developers run locally (no drift), while
+# splitting pytest and rust into parallel jobs the way integration.yml does.
+jobs:
+  mongodb-pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+      - name: Build release (mongodb backend)
+        run: cargo build --release --no-default-features --features mongodb
+      - name: Run MongoDB pytest suite
+        run: devtools/run-mongodb-tests -- --pytest --comprehensive --parallel
+
+  mongodb-rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+      - name: Build release (mongodb backend)
+        run: cargo build --release --no-default-features --features mongodb
+      - name: Run MongoDB rust integration suite
+        run: devtools/run-mongodb-tests -- --rust --rust-integration
+
+  mongodb-integration:
+    runs-on: ubuntu-latest
+    needs: [mongodb-pytest, mongodb-rust]
+    if: always()
+    steps:
+      - run: |
+          if [ "${{ needs.mongodb-pytest.result }}" != "success" ] || \
+             [ "${{ needs.mongodb-rust.result }}" != "success" ]; then
+            exit 1
+          fi

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,15 +85,25 @@ 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 (backends are mutually exclusive — disable default postgres)
+cargo build --release --no-default-features --features mongodb
 ```
 
+Backends are selected by mutually exclusive Cargo features (`postgres`,
+`mongodb`, `sqlite`); a build enabling more than one is rejected at compile
+time. Each binary serves exactly one backend.
+
 Binary: `target/release/extenddb`
 
 ### Unit Test
@@ -109,11 +122,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 +374,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 +468,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