feat: add MongoDB driver support (#482)

* feat: add MongoDB driver support

Add MongoDB as the 11th supported database driver, enabling document
database operations via the existing `Connector` interface.

- New driver at `packages/drivers/src/mongodb.ts` supporting:
  - Full MQL command set: find, aggregate, CRUD, indexes, collection mgmt
  - Cross-database queries via per-query `database` field
  - BSON type serialization (ObjectId, Decimal128, Long, UUID, Binary, Date)
  - Schema introspection via document sampling with field type inference
  - Connection string URI and host/port/user/password auth
  - `authorizedDatabases` fallback for restricted-privilege users
- Registration in driver index, config normalizer (with `mongo`/`mongodb` aliases), and connection registry
- CI: MongoDB 7.0 service in driver-e2e workflow with health checks
- 90 E2E tests including:
  - CRUD operations, aggregation pipelines, schema introspection
  - Cross-database operations, index management, collection lifecycle
  - Adversarial tests: deeply nested docs, special characters, heterogeneous
    collections, concurrent operations, large documents, numeric edge cases

Closes #480

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address multi-model code review findings for MongoDB driver

Fixes from 6-model consensus review (Claude, GPT 5.2 Codex, Gemini 3.1
Pro, Kimi K2.5, MiniMax M2.5, GLM-5):

- Cap user-specified `limit` against `effectiveLimit` to prevent OOM
  from unbounded queries (flagged by Gemini)
- Add `ping` command for connection testing instead of querying
  `system.version` which may not be accessible (flagged by Gemini, GLM-5)
- Add `e.code === 26` fallback for `dropCollection` error handling
  across MongoDB versions (flagged by GLM-5)
- Fix misleading docstring on `extractFields` that claimed dot-notation
  expansion (flagged by Gemini)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address CodeRabbit findings and update docs for MongoDB driver

CodeRabbit review fixes:
- Use `...COMMON_ALIASES` spread in `MONGODB_ALIASES` for consistency
  with other drivers (normalize.ts)
- Scan entire aggregate pipeline for `$limit` instead of only last
  stage; also skip auto-limit for `$out`/`$merge` write pipelines
- Keep `mongodb` at `^6.0.0` (NOT upgrading to v7): v7 drops Node 16/18
  support and has many breaking changes; v6.21.0 is actively maintained
  and supports MongoDB server 3.6-8.0

Additional review fixes:
- Include database name in URI when building from individual config
  fields for correct auth-source resolution (GLM-5)
- Add security comment about credential exposure in URI (Kimi K2.5)

Documentation updates:
- `docs/docs/drivers.md`: add MongoDB to support matrix (11 databases),
  install section, auth methods, auto-discovery
- `docs/docs/configure/warehouses.md`: add MongoDB configuration section
  with connection string and field-based examples, server compatibility
- `docs/docs/data-engineering/tools/warehouse-tools.md`: add MongoDB to
  Docker discovery and env var detection

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: format MongoDB driver files with Prettier

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: cap aggregate `$limit` and serialize `distinct` values (CodeRabbit)

- Cap user-specified `$limit` in aggregate pipelines against
  `effectiveLimit` to prevent OOM, matching the `find` command behavior
- Serialize `distinct` return values through `serializeValue()` for
  consistent BSON type handling across find/aggregate/distinct

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

.github/workflows/ci.yml

@@ -45,6 +45,7 @@ jobs:
               - 'packages/opencode/src/altimate/native/connections/**'
               - 'packages/opencode/test/altimate/drivers-e2e.test.ts'
               - 'packages/opencode/test/altimate/drivers-docker-e2e.test.ts'
+              - 'packages/opencode/test/altimate/drivers-mongodb-e2e.test.ts'
               - 'packages/opencode/test/altimate/connections.test.ts'
             dbt-tools:
               - 'packages/dbt-tools/**'
@@ -155,6 +156,16 @@ jobs:
           --health-timeout 5s
           --health-retries 10
 
+      mongodb:
+        image: mongo:7.0
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --eval 'db.runCommand({ping:1})' --quiet"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
@@ -195,6 +206,13 @@ jobs:
           TEST_REDSHIFT_PORT: "15439"
           TEST_REDSHIFT_PASSWORD: testpass123
 
+      - name: Run MongoDB driver E2E
+        run: bun test test/altimate/drivers-mongodb-e2e.test.ts
+        working-directory: packages/opencode
+        env:
+          TEST_MONGODB_HOST: 127.0.0.1
+          TEST_MONGODB_PORT: "27017"
+
       # Cloud tests NOT included — they require real credentials
       # Run locally with:
       #   ALTIMATE_CODE_CONN_SNOWFLAKE_TEST='...' bun test test/altimate/drivers-snowflake-e2e.test.ts

bun.lock

@@ -1,6 +1,6 @@
 # Warehouses
 
-Altimate Code connects to 8 warehouse types. Configure them in `.altimate-code/connections.json` (project-local) or `~/.altimate-code/connections.json` (global).
+Altimate Code connects to 9 warehouse types. Configure them in `.altimate-code/connections.json` (project-local) or `~/.altimate-code/connections.json` (global).
 
 ## Configuration
 
@@ -237,6 +237,51 @@ If you're already authenticated via `gcloud`, omit `credentials_path`:
 | `ssl_cert` | No | Path to client certificate file |
 | `ssl_key` | No | Path to client key file |
 
+## MongoDB
+
+```json
+{
+  "my-mongodb": {
+    "type": "mongodb",
+    "host": "localhost",
+    "port": 27017,
+    "database": "analytics",
+    "user": "analyst",
+    "password": "{env:MONGO_PASSWORD}"
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `connection_string` | No | Full connection string (alternative to individual fields) |
+| `host` | No | Hostname (default: `127.0.0.1`) |
+| `port` | No | Port (default: `27017`) |
+| `database` | No | Database name |
+| `user` | No | Username |
+| `password` | No | Password |
+| `auth_source` | No | Authentication database (default: `admin`) |
+| `replica_set` | No | Replica set name |
+| `tls` | No | Enable TLS (default: `false`) |
+| `direct_connection` | No | Connect directly to a single host |
+
+### Using a connection string
+
+```json
+{
+  "my-mongodb": {
+    "type": "mongodb",
+    "connection_string": "mongodb://analyst:secret@localhost:27017/analytics"
+  }
+}
+```
+
+!!! note
+    MongoDB uses MQL (MongoDB Query Language) instead of SQL. Queries are submitted as JSON objects via the `execute` method. Supported commands: `find`, `aggregate`, `countDocuments`, `distinct`, `insertOne`, `insertMany`, `updateOne`, `updateMany`, `deleteOne`, `deleteMany`, `createIndex`, `listIndexes`, `createCollection`, `dropCollection`, `ping`.
+
+!!! info "Server compatibility"
+    The MongoDB driver (v6.x) supports MongoDB server versions 3.6 through 8.0, covering all releases from the last 3+ years.
+
 ## SQL Server
 
 ```json

docs/docs/configure/warehouses.md

@@ -70,6 +70,7 @@ env_bigquery  | bigquery | GOOGLE_APPLICATION_CREDENTIALS
 | Databricks | `DATABRICKS_HOST`, `DATABRICKS_SERVER_HOSTNAME` |
 | PostgreSQL | `PGHOST`, `PGDATABASE`, `DATABASE_URL` |
 | MySQL | `MYSQL_HOST`, `MYSQL_DATABASE` |
+| MongoDB | `MONGODB_URI`, `MONGO_URL` |
 | Redshift | `REDSHIFT_HOST` |
 
 ### Parameters
@@ -164,7 +165,7 @@ Remove an existing warehouse connection.
 
 ## warehouse_discover
 
-Discover database containers running in Docker. Detects PostgreSQL, MySQL/MariaDB, and SQL Server containers with their connection details.
+Discover database containers running in Docker. Detects PostgreSQL, MySQL/MariaDB, SQL Server, and MongoDB containers with their connection details.
 
 ```
 > warehouse_discover

docs/docs/data-engineering/tools/warehouse-tools.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Altimate Code connects to 10 databases natively via TypeScript drivers. No Python dependency required. Drivers are loaded lazily, so only the driver you need is imported at runtime.
+Altimate Code connects to 11 databases natively via TypeScript drivers. No Python dependency required. Drivers are loaded lazily, so only the driver you need is imported at runtime.
 
 ## Support Matrix
 
@@ -17,6 +17,7 @@ Altimate Code connects to 10 databases natively via TypeScript drivers. No Pytho
 | Snowflake | `snowflake-sdk` | Password, Key-Pair (unencrypted + encrypted), OAuth | ✅ Live account | 37 E2E tests, key-pair with passphrase support |
 | BigQuery | `@google-cloud/bigquery` | Service Account, ADC | ✅ Live account | 25 E2E tests, UNNEST/STRUCT/DATE types |
 | Databricks | `@databricks/sql` | PAT, OAuth | ✅ Live account | 24 E2E tests, Unity Catalog support |
+| MongoDB | `mongodb` | Password, Connection String | ✅ Docker | 90 E2E tests, MQL queries, aggregation pipelines |
 | Oracle | `oracledb` (thin) | Password | ❌ Needs Oracle 12.1+ | Thin mode only, no Instant Client |
 
 ## Installation
@@ -33,6 +34,9 @@ bun add pg                        # PostgreSQL + Redshift
 bun add mysql2                    # MySQL
 bun add mssql                     # SQL Server
 
+# Document databases
+bun add mongodb                   # MongoDB
+
 # Cloud warehouses
 bun add snowflake-sdk             # Snowflake
 bun add @google-cloud/bigquery    # BigQuery
@@ -129,6 +133,14 @@ altimate-dbt init --project-root /path/to/dbt/project --python-path $(which pyth
 |--------|--------------|
 | Password | `host`, `port`, `service_name`, `user`, `password` |
 
+### MongoDB
+| Method | Config Fields |
+|--------|--------------|
+| Password | `host`, `port`, `database`, `user`, `password` |
+| Connection String | `connection_string: "mongodb://user:pass@host:port/db"` |
+
+MongoDB supports server versions 3.6 through 8.0. Queries use MQL (MongoDB Query Language) via JSON, not SQL. The driver supports `find`, `aggregate`, CRUD operations, index management, and schema introspection via document sampling.
+
 ### DuckDB
 | Method | Config Fields |
 |--------|--------------|
@@ -167,7 +179,7 @@ SSH auth types: `"key"` (default) or `"password"` (set `ssh_password`).
 
 The CLI auto-discovers connections from:
 
-1. **Docker containers**: detects running PostgreSQL, MySQL, MariaDB, SQL Server, Oracle containers
+1. **Docker containers**: detects running PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, MongoDB containers
 2. **dbt profiles**: parses `~/.dbt/profiles.yml` for all supported adapters
 3. **Environment variables**: detects `SNOWFLAKE_ACCOUNT`, `PGHOST`, `MYSQL_HOST`, `MSSQL_HOST`, `ORACLE_HOST`, `DUCKDB_PATH`, `SQLITE_PATH`, etc.
 

docs/docs/drivers.md

@@ -16,6 +16,7 @@
     "mysql2": "^3.0.0",
     "mssql": "^11.0.0",
     "oracledb": "^6.0.0",
-    "duckdb": "^1.0.0"
+    "duckdb": "^1.0.0",
+    "mongodb": "^6.0.0"
   }
 }

packages/drivers/package.json

@@ -1,7 +1,6 @@
 // Re-export types
 export type { Connector, ConnectorResult, SchemaColumn, ConnectionConfig } from "./types"
 
-
 // Re-export config normalization
 export { normalizeConfig } from "./normalize"
 
@@ -16,3 +15,4 @@ export { connect as connectSqlserver } from "./sqlserver"
 export { connect as connectOracle } from "./oracle"
 export { connect as connectDuckdb } from "./duckdb"
 export { connect as connectSqlite } from "./sqlite"
+export { connect as connectMongodb } from "./mongodb"