MongoDB Setup

This guide connects a MongoDB database to Klairr. The connection uses a dedicated read-only role over TLS — Klairr never has write access to your data. Queries run as aggregation pipelines, and every stage is allow-listed before it reaches Mongo.

Prerequisites

• MongoDB 4.0 or higher. Earlier versions may work but are not supported.
• A reachable cluster — Atlas, self-hosted on a public endpoint, or a private network with a route from Klairr (see Network Access).
• TLS enabled on the cluster. TLS 1.2+ is required.
• An admin who can create database users.
• The cluster runs as a replica set (single-node replica set is fine). Standalone deployments work for read queries today, but replica sets are recommended — they’re required for change-stream features we’ll add next.

Choose a connection method

See Network Access for the full posture.

Step 1: Create a read-only user

In mongosh (or Atlas → Security → Database Access → Add New Database User → Custom Role):

use admin
db.createUser({
  user: "klairr_reader",
  pwd: "<password>",
  roles: [
    { role: "readAnyDatabase", db: "admin" },
    { role: "clusterMonitor",  db: "admin" }
  ]
})

Why these roles:

• readAnyDatabase — grants find, listCollections, listIndexes, dbStats, collStats across every database. Narrower than readAnyDatabase? Use read on a specific database ({ role: "read", db: "analytics" }) — Klairr only queries the database you select in setup, so the narrower grant works equally well.
• clusterMonitor — required for Klairr to validate replica-set state and (later) change-stream support. No data access.

Klairr does not request readWrite, dbAdmin, dbOwner, userAdmin, clusterAdmin, or root.

If you can’t provision a strict read-only role (common in dev environments), see “Allow writable role” below.

Step 2: Allowlist Klairr’s egress

Atlas: Security → Network Access → Add IP Address. Self-hosted: open the relevant port to Klairr’s egress range.

The egress range is region-specific and shared with you in your contract — see Network Access.

Step 3: Add the connector in Klairr

Open Settings → Connectors → Add connector, pick MongoDB, and enter:

Allow writable role

If your role grants writes (rare in production but common in dev environments), Klairr’s connect-time probe will block the setup.

You can set “Allow writable role” to “Yes” to acknowledge this and proceed. Klairr’s executor only emits an allow-listed set of aggregation stages ($match, $project, $group, $sort, $limit, $skip, $count, $lookup, $unwind, $addFields, $set, $replaceRoot, $facet, and a small number of others); write stages ($out, $merge) and server-side eval ($function, $accumulator, $where) are rejected at the application layer regardless of what the role permits. The acknowledgement is recorded on the connector for audit.

Setup tests

When you click Connect, Klairr runs the following checks. Each failure maps to the troubleshooting entry below.

1. URI shape — the connection string parses and is mongodb:// or mongodb+srv://.
2. DNS / SRV resolution — every replica-set member resolves; the egress guard accepts each one.
3. TLS handshake — the cluster speaks TLS 1.2+; the cert validates.
4. Authentication — the user exists and the password is correct.
5. Database access — the user has find on the configured database.
6. Write probe — Klairr attempts a synthetic insertOne against a non-existent collection. A read-only user rejects with “not authorized”; a writable user triggers the “Allow writable role” path.
7. Schema introspection — Klairr enumerates collections and runs $sample to infer field types.

What Klairr queries

• Schema introspection runs $sample against each collection (default 100 docs) to infer field types. Mixed-type fields are flagged in the column description. No row data leaves your database during introspection.
• Question answering translates the natural-language question into a JSON aggregation pipeline. Every pipeline is validated against an allow-list before execution: forbidden stages ($out, $merge, $function, $accumulator, $where, $collStats, $indexStats, etc.) are rejected at the application layer.
• A server-side $limit is appended to every pipeline.
• $lookup and $unionWith targets are validated to reject system.* collections (no exfil from system.users, system.sessions, etc.).

Atlas notes

• PrivateLink is gated to specific Atlas plans. Contact Atlas support to provision the endpoint, then contact Klairr support so we can pair the endpoint on our side.
• Read preference — Klairr defaults to the cluster’s primary. To prefer secondaries (lower analytics load on primary), append ?readPreference=secondaryPreferred to your connection string.
• Sample size is bounded — schema introspection samples 100 docs per collection. Refresh schema after large structural changes (new collections, new field shapes).

Troubleshooting

• Connection refused / DNS resolution failed — the cluster is unreachable from Klairr. For Atlas: check Network Access allowlist. For self-hosted: confirm the host is publicly reachable; if it’s on a private network, set “Host is on a private network” to Yes. See Network Access.
• TLS handshake failed — the cluster speaks an unsupported TLS version, or the cert isn’t valid. Atlas clusters always speak TLS; for self-hosted, ensure TLS is enabled and the cert is signed by a public CA or your private CA is in the system trust store.
• Authentication failed — the user doesn’t exist, the password is wrong, or the auth source is wrong. Atlas users default to admin as the auth source even when defaultauthdb is something else; the connection string above reflects this.
• Permission denied / “not authorized for collection” — the user is missing read on the configured database. Re-run db.createUser with readAnyDatabase or read scoped to the database.
• “Credentials grant write access” — Klairr’s probe found the role can write. Either narrow the role to read / readAnyDatabase, or set “Allow writable role” to Yes (Klairr’s executor allow-list will still block writes).
• Resolves to a private address — the SRV record returned an RFC1918 address (Atlas does this for PrivateLink-configured clusters). Set “Host is on a private network” to Yes if you have a route, or use the cluster’s public endpoint.
• Cluster is standalone, not replica-set — most analytics works today, but Klairr’s roadmap features (change streams, oplog-driven incremental refresh) require a replica set. Convert with Atlas (one-click) or rs.initiate() on self-hosted.

Related

• Network Access — egress IPs, private-network options, TLS requirements.
• Roles & Permissions — who in your Klairr workspace can see and query which connectors.
• Supported Data Sources — every database and SaaS Klairr connects to.
• Security & Data Handling — encryption, logging, what we do and don’t store.