Skip to main content

Connect to MongoDB

Connect MongoDB to Retool and query and manage documents in your collections.

MongoDB is a document-oriented NoSQL database that stores data as flexible JSON-like documents. You can create a MongoDB resource to connect to a self-managed MongoDB server or a database hosted on MongoDB Atlas, and build apps and automations that use queries to read and write data.

What you can do with MongoDB in Retool​

After you create a MongoDB resource in Retool, you can:

  • Query collections with filters, projections, and sort options.
  • Insert, update, and delete documents.
  • Run aggregation pipelines to transform and analyze data.
  • Build admin panels and dashboards backed by your collections.

Before you begin​

To connect MongoDB to Retool, you need the following:

Cloud organizations can connect to a MongoDB server with a username and password or a connection string, or to MongoDB Atlas by signing in to Atlas. Select the option that matches your database.

  • MongoDB server: Version 3.6 or later.
  • Credentials: A username and password with appropriate permissions, or a connection string that includes authentication.
  • Network access: Your MongoDB server must accept connections from Retool's IP addresses.
  • Retool permissions: Ability to create and manage resources in your organization.

Create a MongoDB resource​

Follow these steps to create a MongoDB resource in your Retool organization.

Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for "MongoDB" and click the MongoDB tile to begin configuration.

Best practice

Use folders to organize your resources by team, environment, or resource type. This helps keep your resource list manageable as your organization grows.

Configure general settings​

Specify a name and description for the resource that indicates which database or cluster it connects to. The description provides more context to users about how to use the resource.

Example nameExample description
User databaseMongoDB database containing user profiles and preferences.
Product catalogRead-only MongoDB database with product and inventory data.

Configure resource credentials​

Configure the connection settings for your MongoDB resource.

MongoDB resource credentials.

Best practice

Click Autofill using connection string to fill most connection fields from a MongoDB connection string.

Connection string example
mongodb+srv://admin:password@cluster0.example.mongodb.net/mydb?retryWrites=true&w=majority

Host​

The hostname or IP address of your MongoDB server.

Example
db.example.com

Connection format​

Select the connection format that matches your MongoDB deployment.

FormatDescription
Standard (mongodb)For direct connections to a MongoDB server. Requires a host and port.
DNS seed list (mongodb+srv)For deployments that use DNS-based service discovery.

Port​

The port your MongoDB server listens on. Required for the Standard connection format. The default MongoDB port is 27017.

Default database​

The name of the MongoDB database to connect to.

Database username and password​

Enter the Database username and Database password for a MongoDB user with access to the database. Create a dedicated user for Retool rather than reusing an administrator account.

Mongo version​

Select the integration version to use. Version 2 - v2 connector (MongoDB 3.6+) is the default. Select Version 1 - legacy connector (MongoDB 3.6+) only if you need the legacy integration. Both versions support MongoDB 3.6 and later.

Connection options​

Additional connection string options to customize the connection. For SSL and TLS, use the Use SSL/TLS setting instead.

SSL/TLS​

important

Configuring SSL/TLS is optional but highly recommended for production deployments.

Enable Use SSL/TLS to encrypt connections between Retool and your MongoDB server. Refer to the SSL/TLS documentation for more about working with certificates.

SSH tunnel​

If your MongoDB server isn't publicly accessible, select Enable SSH tunnel to connect through a bastion host. Enter the Bastion host and Bastion port, then download Retool's public key and add it to your bastion host for a user named retool. Refer to the SSH tunnel documentation for details.

Configure advanced options​

Configure optional settings available under the Advanced options section of the resource configuration form.

Type​

Choose how the resource can be used. Read connection is for read-only access, and queries use raw statements. Write connection allows write operations, which you create with the query GUI to help prevent accidental destructive changes.

Disable converting queries to prepared statements​

Retool converts queries to prepared statements by default to improve performance and prevent injection attacks. Enable this option only if your use case requires disabling that behavior.

Outbound region​

If your organization uses outbound regions, select the region that should be used for requests to MongoDB. This controls which geographic region your requests originate from.

Test the connection​

Click Test connection to verify Retool can connect to MongoDB. If the test fails, check the following:

  • Network access: Ensure your MongoDB server accepts connections from Retool's IP addresses.
  • Credentials: Verify the username and password are correct and the user has access to the specified database.
  • Hostname and port: Confirm the hostname is correct and MongoDB is running on the specified port.
  • Connection format: If you use DNS seed list, ensure your deployment supports mongodb+srv connections.
  • SSL/TLS: If your server requires SSL, enable Use SSL/TLS.
Use Debug Tools for detailed connection information

After testing the connection, click View in console to open the Debug Tools console. The console displays the test details, execution time, and error details if the test fails. This information is helpful for troubleshooting connection issues.

Save the resource​

Click Create resource to save your MongoDB resource. You can now use it in queries across your Retool apps and automations.

Interact with MongoDB data​

Once you've created a MongoDB resource, you can interact with MongoDB data using Retool.

Switch to the app builder

Retool recommends using the app builder so you can use natural language to build React-based apps using AI.

  • To use MongoDB data in the app builder, reference the resource in the prompt with @, such as @User database. Refer to the data and functions documentation to learn more.
  • For classic apps, workflows, and agents, refer to the resource query documentation to learn how to write a resource query.

Best practices​

Follow these best practices to secure and manage your MongoDB resource.

  • Apply least privilege: Grant the MongoDB user only the permissions Retool needs. Use read-only access for resources that only read data.
  • Enable SSL/TLS: Encrypt connections to your MongoDB server, and validate the server certificate.
  • Use an SSH tunnel for private servers: Keep your server off the public internet and connect through an SSH tunnel.
  • Use resource environments: Configure multiple resource environments to maintain separate databases or credentials for production, staging, and development.