MongoDB

Connect GradientHarbor to MongoDB databases. GradientHarbor queries your MongoDB collections using SQL via DuckDB's community MongoDB extension.

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ GradientHarbor  │────▶│   DuckDB Engine   │────▶│    MongoDB     │
│                 │ SQL │  (mongo extension)│     │   (your data)  │
│  AI Agent       │◀────│  SQL → document   │◀────│   collections  │
│  Dashboards     │     │  queries          │     │                │
└─────────────────┘     └──────────────────┘     └─────────────────┘

GradientHarbor connects to MongoDB through DuckDB's MongoDB extension, which translates SQL queries into MongoDB operations. This means:

• Collections are accessed as SQL tables
• Documents are flattened into rows and columns
• Standard SQL queries work against your MongoDB data
• No additional infrastructure is required beyond your existing MongoDB instance

Prerequisites

• MongoDB instance (self-hosted or Atlas, any tier)
• A connection string with credentials embedded (e.g., mongodb+srv://user:pass@host/db)
• A database user with read access

Configuration

Field	Example	Required
Connection String	mongodb+srv://reader:password@cluster0.abc123.mongodb.net/myapp	Yes

WARNING

The connection string must include credentials (username and password) in the URL. GradientHarbor does not support separate credential fields for MongoDB.

Setup Steps

1. Create a read-only user in your MongoDB instance or Atlas:

   • In Atlas: go to Database Access > Add Database User
   • Grant read-only privileges on the target database

2. Get the connection string:

   • In Atlas: go to your cluster > Connect > Drivers > copy the connection string
   • Replace <password> with your user's password
   • Ensure the database name is included in the path

3. Add the connector in GradientHarbor:

   • Go to Administration > DB Connectors
   • Select MongoDB
   • Paste the full connection string
   • Test the connection

4. Select schemas after introspection completes

5. Full catalog sync maps your collections to SQL-queryable tables

Atlas MongoSQL

For MongoDB Atlas clusters (M10+), GradientHarbor also supports Atlas MongoSQL — a native SQL interface provided by Atlas. This connects via ODBC and offers a direct SQL endpoint without the DuckDB translation layer.

To use Atlas MongoSQL instead of the DuckDB-based connector, select Atlas MongoSQL when adding a connector and provide either:

• An ODBC connection string (e.g., DSN=... or Driver={...};Server=...;)
• A Mongo-style URI pointing at the Atlas SQL endpoint (e.g., mongodb://atlas-sql-.../db)

INFO

Atlas MongoSQL requires the MongoDB Atlas SQL ODBC driver to be installed on the host. The DuckDB-based MongoDB connector has no additional driver requirements.

Troubleshooting

Issue	Solution
Connection refused	Verify the connection string is correct and includes credentials. Check network access / IP allowlist in Atlas.
Authentication failed	Ensure the user has access to the specific database. Check that the password is URL-encoded if it contains special characters.
Missing collections	Collections must have at least one document to be discovered during introspection.