How to Integrate Retool with MongoDB

Before configuring Retool, ensure your MongoDB instance has a dedicated user for Retool with appropriate permissions, and that the instance is reachable from Retool's servers. Create a MongoDB user for Retool. Connect to your MongoDB instance using the mongo shell or MongoDB Compass, switch to the admin database, and create a user with readWrite access on the specific database Retool needs to access. Use a strong password and store it in a password manager. For network access: - If MongoDB is on a server with a public IP: open port 27017 (or your custom MongoDB port) in the server's firewall to Retool Cloud's IP ranges: 35.90.103.132/30 and 44.208.168.68/30 (us-west-2). If using eu-central-1 Retool Cloud: 3.77.79.248/30. - If MongoDB is in a private VPC: do NOT expose port 27017 publicly. Instead, configure SSH tunneling through a bastion host (covered in Step 2). - If using self-hosted Retool in the same network as MongoDB: no firewall changes needed — Retool connects directly from your network. Also verify your MongoDB configuration file (mongod.conf). The bindIp setting controls which network interfaces MongoDB listens on. For remote connections, ensure it includes either 0.0.0.0 (listen on all interfaces) or the specific IP that Retool's traffic arrives from. Restart MongoDB after any bindIp change.

1// Create Retool user in MongoDB shell
2// Run in mongo shell connected as admin
3use admin
4db.createUser({
5  user: "retool",
6  pwd: "YOUR_STRONG_PASSWORD_HERE",
7  roles: [
8    {
9      role: "readWrite",
10      db: "your_database_name"
11    }
12  ],
13  passwordDigestor: "server"
14})
15
16// Verify user creation:
17db.getUser("retool")
18
19// To grant read-only access instead:
20// role: "read" instead of "readWrite"

In your Retool instance, navigate to the Resources tab in the left sidebar. Click Add Resource. In the resource type list, find 'MongoDB' under the Database category. Enter a descriptive name: 'MongoDB Production' or 'App Database (MongoDB)'. In the connection settings section: - Host: the hostname or IP of your MongoDB server (e.g., mongodb.internal or 10.0.1.45) - Port: 27017 (default) or your custom port - Database Name: the name of the specific database you want Retool to access - Username: the MongoDB user you created (retool) - Password: the user's password - Authentication Database: this is a critical field. MongoDB authenticates users against a specific database. If you created the user in the admin database (which is standard), enter admin here. If you created the user in the application database itself, enter that database name. For replica set connections: check the 'Use replica set?' toggle and enter the replica set name (found in your mongod.conf under replication.replSetName, e.g., rs0). Retool will connect to the replica set and automatically route read queries to secondaries if configured. For SSL/TLS: if your MongoDB requires encrypted connections (common in production), enable 'Use SSL' and optionally provide a CA certificate for self-signed certs. For SSH tunneling (MongoDB behind a VPN or in a private subnet): enable the SSH tunnel option. Provide the bastion host's public IP or hostname, SSH port (usually 22), SSH username, and the SSH private key (paste the private key content). Retool will create an SSH tunnel through the bastion and connect to MongoDB's internal address through that tunnel. The Host field should be MongoDB's internal hostname as visible from within the bastion's network (e.g., mongodb.internal or a private IP). Click Save Changes and Retool will test the connection.

Open a Retool app and create a new query. Select your MongoDB resource. Retool's MongoDB query editor exposes the core MongoDB operations: find, findOne, insert, updateOne, updateMany, deleteOne, deleteMany, aggregate, count, and distinct. For a find operation: select 'find' as the action. In the Collection field, enter your collection name. The Query field accepts a MongoDB query document as JSON — equivalent to the first argument to db.collection.find(). Use {{ }} expressions to reference Retool component values dynamically. For example, to search by email with an optional status filter: - Query: { "email": { "$regex": "{{ emailSearch.value }}", "$options": "i" } } - If statusFilter.value is not empty, add: "status": "{{ statusFilter.value }}" The Projection field controls which fields are returned (1 = include, 0 = exclude). Use projections to avoid fetching large embedded documents you don't need in your UI. The Sort field takes a sort document: { "createdAt": -1 } for newest first. Limit and Skip enable pagination: bind these to Retool's Table pagination component. For an aggregation pipeline: select 'aggregate' as the action. Enter the pipeline as a JSON array of stage objects. Each stage is a MongoDB aggregation stage like $match, $group, $sort, $project, $lookup, or $unwind. Create a JavaScript transformer to flatten or reshape the MongoDB response for display in Retool components.

1// Example 1: Find documents with dynamic filtering
2// Action: find
3// Collection: users
4// Query (evaluates to JSON):
5{
6  "$and": [
7    {{ emailSearch.value ? { "email": { "$regex": emailSearch.value, "$options": "i" } } : {} }},
8    {{ statusFilter.value ? { "status": statusFilter.value } : {} }},
9    {{ planFilter.value ? { "plan": planFilter.value } : {} }}
10  ]
11}
12// Sort: { "createdAt": -1 }
13// Limit: {{ table1.pageSize }}
14// Skip: {{ table1.pageIndex * table1.pageSize }}
15
16// Example 2: Aggregation pipeline
17// Action: aggregate
18// Collection: orders
19// Pipeline:
20[
21  { "$match": { "createdAt": { "$gte": { "$date": "{{ dateRange.startDate }}" }, "$lte": { "$date": "{{ dateRange.endDate }}" } } } },
22  { "$group": { "_id": "$status", "count": { "$sum": 1 }, "revenue": { "$sum": "$total" } } },
23  { "$sort": { "revenue": -1 } }
24]

Retool's MongoDB connector supports all four CRUD operations. Building a complete admin panel requires understanding when to use updateOne versus updateMany, and how to structure MongoDB update operators. For update operations: Retool's MongoDB query editor exposes updateOne and updateMany actions. The Filter field specifies which documents to match (same as the Query field in find). The Update field specifies the update to apply using MongoDB update operators. The $set operator updates specific fields without replacing the entire document — this is almost always what you want in an admin tool. Using { "newValues" } without an operator would replace the entire document, potentially deleting fields the form didn't include. For insert operations: use the 'insert' action with a Document field containing the new document as JSON. Reference form component values using {{ }} expressions. MongoDB automatically adds an _id field if not provided. For delete: Retool provides deleteOne (deletes the first matching document) and deleteMany. For admin tools, deleteOne is safer — always filter by _id to ensure you're deleting only the intended document. Always chain write operations with a data refresh. In the write query's Event Handlers section: On Success → Trigger query (your find/list query to refresh the Table) and Show notification. On Failure → Show notification with the error message. Add a confirmation Modal before all delete operations — this is critical for production data safety. For updates affecting multiple fields from a form: dynamically build the $set object from changed form values using a JavaScript query rather than hardcoding each field.

1// updateOne query configuration
2// Action: updateOne
3// Collection: users
4// Filter (match by _id):
5{ "_id": { "$oid": "{{ table1.selectedRow.data._id }}" } }
6
7// Update (use $set to update only specified fields):
8{
9  "$set": {
10    "status": "{{ statusDropdown.value }}",
11    "plan": "{{ planDropdown.value }}",
12    "notes": "{{ notesInput.value }}",
13    "updatedAt": { "$date": "{{ new Date().toISOString() }}" },
14    "updatedBy": "{{ current_user.email }}"
15  }
16}
17
18// insertOne query configuration
19// Action: insert
20// Collection: users
21// Document:
22{
23  "email": "{{ emailInput.value }}",
24  "status": "active",
25  "plan": "{{ planSelect.value }}",
26  "createdAt": { "$date": "{{ new Date().toISOString() }}" }
27}

Self-hosted MongoDB deployments often use replica sets for high availability — a primary node handles all writes and typically reads, while secondary nodes maintain copies and can serve read traffic. Retool's MongoDB connector supports replica set connections through the dedicated replica set configuration in the resource settings. To connect to a replica set: in the Retool MongoDB resource settings, enable 'Use replica set?' and enter the replica set name (e.g., rs0). The Host field should contain one or more seed hosts from the replica set — Retool will discover the full replica set topology through these seeds. You can enter multiple hosts as a comma-separated list: mongodb1.internal:27017,mongodb2.internal:27017. Retool's connection automatically handles primary failover: if the current primary steps down (e.g., during maintenance or a network partition), Retool will reconnect to the new primary without requiring resource reconfiguration. For read preference: if your MongoDB replica set has read scaling configured (reading from secondaries), you can specify the readPreference in query options. Secondary reads reduce load on the primary but may return slightly stale data — appropriate for reporting dashboards but not for operational reads that require the latest data. If your MongoDB deployment uses authentication with a specific mechanism (SCRAM-SHA-256 is the default for MongoDB 4.0+), ensure your retool user was created with the correct authentication mechanism. MongoDB 3.x used SCRAM-SHA-1 by default. For ongoing connection health: Retool maintains a connection pool per resource. If your MongoDB instance is restarted or network connections drop, Retool automatically reconnects. If you see transient connection errors in a Retool app, try running the query again — a first-attempt error often reflects a dropped idle connection being reestablished.

1// Replica set connection configuration reference
2// In Retool MongoDB resource settings:
3// Host: mongodb1.internal:27017,mongodb2.internal:27017,mongodb3.internal:27017
4// Port: (leave blank when specifying ports in host field)
5// Database Name: your_database
6// Username: retool
7// Password: your_password
8// Authentication Database: admin
9// Use replica set: enabled
10// Replica Set Name: rs0
11
12// To verify replica set status from MongoDB shell:
13rs.status()
14// Should show all members with health: 1
15// and one member with stateStr: 'PRIMARY'