feat: add MongoDB driver support

[anandgupta42]

What does this PR do?

Adds MongoDB as the 11th supported database driver, enabling document database operations via the existing Connector interface. This is needed for the DataAgentBench (DAB) benchmark where 2 of 12 datasets require MongoDB.

Changes:

• New driver at packages/drivers/src/mongodb.ts with full MQL command set (find, aggregate, CRUD, indexes, collection management)
• Cross-database queries via per-query database field override
• BSON type serialization (ObjectId, Decimal128, Long, UUID, Binary, Date)
• Schema introspection via document sampling with accurate nullable detection
• Connection string URI and host/port auth support
• authorizedDatabases fallback for restricted-privilege users
• Registration in driver index, config normalizer (mongo/mongodb aliases), and connection registry
• CI: MongoDB 7.0 service in driver-e2e workflow with health checks
• 90 E2E tests: CRUD, aggregation, schema introspection, cross-DB ops, indexes, adversarial edge cases

Type of change

• New feature (non-breaking change which adds functionality)

Issue for this PR

Closes#480
Closes#481

How did you verify your code works?

• All 90 MongoDB E2E tests pass against Dockerized MongoDB 7.0
• Existing driver tests (DuckDB, SQLite, PostgreSQL, normalize, connections) all pass — zero regressions
• TypeScript typecheck passes
• Marker check passes (no upstream files modified)
• Multi-model code review (Claude + GPT 5.2 Codex + 4 others): review findings addressed before commit

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• New and existing unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a MongoDB database driver with host/port or connection-string connection, schema discovery, and broad operation support (CRUD, aggregation, indexes).

• Tests

  • Added comprehensive end-to-end tests covering connection, CRUD, aggregation, schema introspection, indexes, and error cases.

• CI

  • Integrated MongoDB service into CI and added an E2E test step to run the MongoDB test suite.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

📝 Walkthrough

Walkthrough

Adds a MongoDB driver and CI/test integration: new driver implementation (connect, schema introspection, JSON MQL execution), registry and normalization updates, optional dependency entry, and a comprehensive Docker-capable end-to-end test plus CI changes to run it.

Changes

Cohort / File(s)	Summary
CI Workflow .github/workflows/ci.yml	Expanded change-detection to include the new MongoDB E2E test; added a mongodb service (mongo:7.0) with a mongosh health check; added a CI step to run the MongoDB E2E test with TEST_MONGODB_HOST/PORT.
Package manifest packages/drivers/package.json	Added mongodb: ^6.0.0 to optionalDependencies.
Driver implementation packages/drivers/src/mongodb.ts, packages/drivers/src/index.ts	New MongoDB connector exporting connect(config), managing MongoClient lifecycle, schema introspection (listSchemas, listTables, describeTable via sampling), BSON-aware serialization, and execute(query) supporting MQL commands (find, aggregate, CRUD, index ops); re-exported as connectMongodb.
Normalization & aliases packages/drivers/src/normalize.ts	Added MONGODB_ALIASES and registered aliases for mongodb/mongo (e.g., username→user, uri/url→connection_string, dbname→database, connection-timeout keys).
Connector registry & runtime packages/opencode/src/altimate/native/connections/registry.ts	Registered mongodb/mongo in DRIVER_MAP; added static import/case for the mongodb driver; detectAuthMethod returns password if config.password else connection_string for MongoDB; test runner uses a MongoDB ping JSON command for health checks when driver is MongoDB.
End-to-end tests packages/opencode/test/altimate/drivers-mongodb-e2e.test.ts	Added comprehensive E2E test file with Docker auto-detection and optional container startup; covers connection variants, lifecycle/close behavior, broad CRUD and aggregation scenarios, schema introspection, collection/index management, adversarial/error-case tests, BSON serialization checks, and cleanup logic.

Sequence Diagram(s)

sequenceDiagram
participant App as Application
participant Driver as MongoDB Driver
participant MClient as MongoClient
participant Server as MongoDB Server
App->>Driver: connect(config)
activate Driver
Driver->>MClient: new MongoClient(uri, options)
activate MClient
MClient->>Server: TCP connect & auth
Server-->>MClient: Connected
MClient-->>Driver: client instance
Driver-->>App: Connector
deactivate Driver
rect rgba(200, 150, 255, 0.5)
Note over App,Driver: Execute JSON MQL
App->>Driver: execute(JSON query)
activate Driver
Driver->>Driver: parse & validate
Driver->>MClient: call op (find/aggregate/insert/...)
activate MClient
MClient->>Server: run operation
Server-->>MClient: cursor/data
MClient-->>Driver: result
Driver->>Driver: serialize BSON -> rows
Driver-->>App: ConnectorResult
deactivate Driver
end
rect rgba(150, 200, 255, 0.5)
Note over App,Driver: Introspection flow
App->>Driver: listSchemas() / listTables() / describeTable()
Driver->>MClient: admin/listDatabases / listCollections / find(limit=100)
MClient->>Server: fetch metadata / sample docs
Server-->>MClient: metadata / documents
MClient-->>Driver: data
Driver-->>App: schemas/tables/columns
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 In a burrow of BSON and curious code,
I sniffed out collections down a new road.
Find, aggregate, index—the carrots all gleam,
Altimate hops forward, a developer's dream! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add MongoDB driver support' is clear, concise, and accurately reflects the main change—adding MongoDB as a new database driver to the system.
Description check	✅ Passed	The PR description includes a clear summary of changes, verification of testing including the 90 E2E tests, and a checklist. However, it does not follow the provided template structure with 'Summary', 'Test Plan', and 'Checklist' sections.
Linked Issues check	✅ Passed	The PR comprehensively implements all coding objectives from #480: MongoDB driver with full MQL support, schema introspection, BSON serialization, connection options, registration, CI integration, and 90 E2E tests. Issue #481 is coordination-only.
Out of Scope Changes check	✅ Passed	All changes are directly in scope: MongoDB driver implementation, supporting infrastructure (normalization, registry, CI), and comprehensive E2E tests. No modifications to unrelated systems or files detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mongodb-driver

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

packages/drivers/src/normalize.ts (1)

76-85: Consider using COMMON_ALIASES spread for consistency.

Other drivers (Postgres, Redshift, MySQL, SQL Server, Oracle) spread COMMON_ALIASES to inherit the common user and database mappings. The MongoDB aliases define these inline, which duplicates the same mappings. This works correctly but is inconsistent with the established pattern.

♻️ Suggested refactor for consistency

 const MONGODB_ALIASES: AliasMap = {
- user: ["username"],- database: ["dbname", "db"],+ ...COMMON_ALIASES,
connection_string: ["connectionString", "uri", "url"],
auth_source: ["authSource"],
replica_set: ["replicaSet"],
direct_connection: ["directConnection"],
connect_timeout: ["connectTimeoutMS"],
server_selection_timeout: ["serverSelectionTimeoutMS"],
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@packages/drivers/src/normalize.ts` around lines 76 - 85, MONGODB_ALIASES
currently redeclares the common mappings for user and database; update it to
spread COMMON_ALIASES into MONGODB_ALIASES (e.g., const MONGODB_ALIASES:
AliasMap = { ...COMMON_ALIASES, /* mongo-specific keys */ }) and then include
only MongoDB-specific aliases (connection_string, auth_source, replica_set,
direct_connection, connect_timeout, server_selection_timeout), removing the
duplicate user and database entries to match the other drivers' pattern.

packages/drivers/src/mongodb.ts (1)

328-362: Aggregate $limit detection could miss nested stages.

The check lastStage && "$limit" in lastStage only examines the last pipeline stage. If users have a $limit buried in the middle of the pipeline (intentionally wanting full results), the auto-appended $limit will still truncate. This is documented behavior (you append if "pipeline doesn't already end with one"), so it's acceptable, but consider documenting that users should place their own $limit last if they want to control truncation precisely.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@packages/drivers/src/mongodb.ts` around lines 328 - 362, The current
aggregate branch only checks the last pipeline stage (`lastStage` / `hasLimit`)
for a $limit and can wrongly append a new $limit when one exists earlier; update
the detection to scan the entire parsed.pipeline (e.g., replace the `hasLimit`
logic with a check like `pipeline.some(stage => "$limit" in stage)`) so you only
push `{ $limit: effectiveLimit + 1 }` when no stage in `parsed.pipeline`
contains `$limit`; ensure you still preserve existing behavior of cloning
`parsed.pipeline` into `pipeline` and use `coll.aggregate(pipeline).toArray()`
and keep the rest of the logic unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/drivers/package.json`:
- Around line 19-20: Update the mongodb dependency version in
packages/drivers/package.json from "mongodb": "^6.0.0" to "mongodb": "^7.0.0" so
the project can pull the latest stable 7.x releases; after changing the
dependency string, run your package manager to update the lockfile
(npm/yarn/pnpm install) and run the test suite/build to ensure no breaking API
changes affect code using the MongoClient or other mongodb-related symbols.
---
Nitpick comments:
In `@packages/drivers/src/mongodb.ts`:
- Around line 328-362: The current aggregate branch only checks the last
pipeline stage (`lastStage` / `hasLimit`) for a $limit and can wrongly append a
new $limit when one exists earlier; update the detection to scan the entire
parsed.pipeline (e.g., replace the `hasLimit` logic with a check like
`pipeline.some(stage => "$limit" in stage)`) so you only push `{ $limit:
effectiveLimit + 1 }` when no stage in `parsed.pipeline` contains `$limit`;
ensure you still preserve existing behavior of cloning `parsed.pipeline` into
`pipeline` and use `coll.aggregate(pipeline).toArray()` and keep the rest of the
logic unchanged.
In `@packages/drivers/src/normalize.ts`:
- Around line 76-85: MONGODB_ALIASES currently redeclares the common mappings
for user and database; update it to spread COMMON_ALIASES into MONGODB_ALIASES
(e.g., const MONGODB_ALIASES: AliasMap = { ...COMMON_ALIASES, /* mongo-specific
keys */ }) and then include only MongoDB-specific aliases (connection_string,
auth_source, replica_set, direct_connection, connect_timeout,
server_selection_timeout), removing the duplicate user and database entries to
match the other drivers' pattern.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e11fc510-0761-4a43-919e-0c5ae0a1c567

📥 Commits

Reviewing files that changed from the base of the PR and between 91fe351 and e431850.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• .github/workflows/ci.yml
• packages/drivers/package.json
• packages/drivers/src/index.ts
• packages/drivers/src/mongodb.ts
• packages/drivers/src/normalize.ts
• packages/opencode/src/altimate/native/connections/registry.ts
• packages/opencode/test/altimate/drivers-mongodb-e2e.test.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

What is the latest stable version of the mongodb npm package?

💡 Result:

The latest stable version of the mongodb npm package is 7.1.1.

Citations:

• 1: https://www.npmjs.com/package/mongodb
• 2: https://www.npmjs.com/package/mongodb?activeTab=dependencies
• 3: https://www.npmjs.com/package/mongodb?activeTab=versions

---

Update mongodb package to latest stable version.

The mongodb ^6.0.0 constraint excludes the latest stable release (7.1.1). Update to ^7.0.0 to include security patches and bug fixes from the latest major version.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@packages/drivers/package.json` around lines 19 - 20, Update the mongodb
dependency version in packages/drivers/package.json from "mongodb": "^6.0.0" to
"mongodb": "^7.0.0" so the project can pull the latest stable 7.x releases;
after changing the dependency string, run your package manager to update the
lockfile (npm/yarn/pnpm install) and run the test suite/build to ensure no
breaking API changes affect code using the MongoClient or other mongodb-related
symbols.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

packages/drivers/src/mongodb.ts (1)

191-194: Redundant logic in serializeValue — both branches produce identical output.

Lines 191-194 always call JSON.stringify(val) regardless of which branch is taken. The conditional serves no purpose.

♻️ Simplify to a single JSON.stringify call

 // Arrays and plain objects — JSON-serialize for tabular display
- if (Array.isArray(val) || typeof (val as any).toJSON !== "function") {- return JSON.stringify(val)- }
return JSON.stringify(val)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@packages/drivers/src/mongodb.ts` around lines 191 - 194, The conditional in
serializeValue is redundant because both branches call JSON.stringify(val);
simplify by removing the if/else and returning JSON.stringify(val) directly from
the serializeValue function (locate the serializeValue function and replace the
conditional block starting with "if (Array.isArray(val) || typeof (val as
any).toJSON !== \"function\")" with a single return JSON.stringify(val)).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/drivers/src/mongodb.ts`:
- Around line 382-395: The distinct branch returns raw BSON values from
coll.distinct without serialization; update the code in the "distinct" case to
pass each value through the existing serializeValue function before constructing
rows (e.g., when building limited.map((v) => [serializeValue(v)]) ), keeping the
truncated/limited logic and columns: [parsed.field] and row_count based on
limited.length unchanged so the response matches how find/aggregate return
serialized tabular values.
- Around line 336-370: The aggregate branch doesn't cap a user-specified $limit,
so a pipeline ending in { $limit: N } can return more than effectiveLimit and
risk OOM; update the pipeline before calling coll.aggregate by inspecting
parsed.pipeline's lastStage: if lastStage has "$limit", replace its value with
Math.min(userLimit, effectiveLimit + 1) (so truncated detection remains
correct), otherwise append { $limit: effectiveLimit + 1 } as currently done;
operate on the local pipeline array (the one created from parsed.pipeline) so
coll.aggregate(pipeline).toArray() uses the capped limit.
---
Nitpick comments:
In `@packages/drivers/src/mongodb.ts`:
- Around line 191-194: The conditional in serializeValue is redundant because
both branches call JSON.stringify(val); simplify by removing the if/else and
returning JSON.stringify(val) directly from the serializeValue function (locate
the serializeValue function and replace the conditional block starting with "if
(Array.isArray(val) || typeof (val as any).toJSON !== \"function\")" with a
single return JSON.stringify(val)).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b676f8db-554c-452d-935d-599b0d84a98e

📥 Commits

Reviewing files that changed from the base of the PR and between e431850 and b5e060c.

📒 Files selected for processing (2)

• packages/drivers/src/mongodb.ts
• packages/opencode/src/altimate/native/connections/registry.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/opencode/src/altimate/native/connections/registry.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Distinct values are not serialized, unlike find and aggregate results.

Values returned by distinct may include BSON types (ObjectId, Decimal128, etc.), but they are returned as-is without passing through serializeValue. This is inconsistent with find and aggregate which serialize all values for tabular display.

🔧 Proposed fix to serialize distinct values

 const values = await coll.distinct(parsed.field, parsed.filter ?? {})
const truncated = values.length > effectiveLimit
const limited = truncated ? values.slice(0, effectiveLimit) : values
return {
columns: [parsed.field],
- rows: limited.map((v: unknown) => [v]),+ rows: limited.map((v: unknown) => [serializeValue(v)]),
row_count: limited.length,
truncated,
}

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	case"distinct": {
	if(!parsed.field){
	thrownewError("distinct requires a 'field' string")
	}
	constvalues=awaitcoll.distinct(parsed.field,parsed.filter??{})
	consttruncated=values.length>effectiveLimit
	constlimited=truncated ? values.slice(0,effectiveLimit) : values
	return{
	columns: [parsed.field],
	rows: limited.map((v: unknown)=>[v]),
	row_count: limited.length,
	truncated,
	}
	}
	case"distinct": {
	if(!parsed.field){
	thrownewError("distinct requires a 'field' string")
	}
	constvalues=awaitcoll.distinct(parsed.field,parsed.filter??{})
	consttruncated=values.length>effectiveLimit
	constlimited=truncated ? values.slice(0,effectiveLimit) : values
	return{
	columns: [parsed.field],
	rows: limited.map((v: unknown)=>[serializeValue(v)]),
	row_count: limited.length,
	truncated,
	}
	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@packages/drivers/src/mongodb.ts` around lines 382 - 395, The distinct branch
returns raw BSON values from coll.distinct without serialization; update the
code in the "distinct" case to pass each value through the existing
serializeValue function before constructing rows (e.g., when building
limited.map((v) => [serializeValue(v)]) ), keeping the truncated/limited logic
and columns: [parsed.field] and row_count based on limited.length unchanged so
the response matches how find/aggregate return serialized tabular values.

[anandgupta42]

Addressed all CodeRabbit findings in 56acab4:

Version upgrade (^6.0.0 → ^7.0.0) — intentionally NOT upgrading: mongodb v7 drops Node 16/18 support and has many breaking changes. v6.21.0 (latest v6) is actively maintained and supports MongoDB server 3.6 through 8.0, covering all releases from the last 3+ years.

Nitpicks addressed:

• ✅ COMMON_ALIASES spread in MONGODB_ALIASES for consistency
• ✅ Aggregate $limit detection now scans entire pipeline (not just last stage), and skips $out/$merge write pipelines

Additional fixes in this commit:

• Include database in URI for correct auth-source resolution
• Security comment about credential exposure
• Full documentation updates (drivers.md, warehouses.md, warehouse-tools.md)