This integration is certified by Stitch. For support, contact Stitch support.
MongoDB feature snapshot
A high-level look at Stitch's MongoDB (v11-01-2016) integration, including release status, useful links, and the features supported in Stitch.
Sunset on February 2, 2020
2.4 through 3.4
|Singer GitHub repository||
|Configurable Replication Methods||
|Full Table Replication||
MongoDB setup requirements
To set up MongoDB in Stitch, you need:
- A Standard or higher Stitch plan. While those currently in the Free Trial will also be able to set up MongoDB, replication will be paused until a Standard plan or higher is selected after the trial ends.
Permissions in MongoDB that allow you to create/manage users. This is required to create the Stitch database user.
A MongoDB server that uses Auth mode. Auth mode requires every user who connects to Mongo to have a username and password. These credentials must be validated before the user will be granted access to the database.
To be using MongoDB version 2.4 through 3.4. While older versions may be connected to Stitch, we may not be able to provide support for issues that arise due to unsupported versions.
We recommend always keeping your version current as a best-practice. If you encounter connection issues or other unexpected behavior, verify that your MongoDB version is one supported by Stitch.
Additionally, note that:
- If using SSL, your server must require SSL connections. Note: SSL is not required to connect a MongoDB database to Stitch.
- If connecting via Atlas, Stitch can only connect to instances using a paid Atlas plan with a dedicated cluster. The Free Atlas plan and shared clusters utilize a setup that Stitch doesn’t currently support.
Step 1: Index Replication Key fields
Before you jump into the actual setup, consider how the documents in your Mongo database are updated.
Our Mongo integration uses Key-based Incremental Replication to replicate Mongo data, which means that only new and updated data will be replicated to your destination when a replication job runs. Stitch uses a field you designate - called a Replication Key - to identify new and updated data.
There are two requirements for Mongo Replication Keys:
- The field must be indexed. Only indexed fields will display in the Replication Key drop-down.
- The field must exist in the root of the document.
Additionally, while this is not a strict requirement, Replication Key fields should only contain a single, auto-incrementing data type. If a field contains multiple data types or a data type that doesn’t auto-increment, Stitch may have issues with detecting new/updated data.
For a detailed look at Mongo Replication Keys, check out the Selecting & Changing Mongo Replication Keys guide before continuing.
Step 2: Configure database connection settings
In this step, you’ll configure the database server to allow traffic from Stitch to access it. There are two ways to connect your database:
- A direct connection will work if your database is publicly accessible.
- An SSH tunnel is required if your database isn’t publicly accessible. This method uses a publicly accessible instance, or an SSH server, to act as an intermediary between Stitch and your database. The SSH server will forward traffic from Stitch through an encrypted tunnel to the private database.
Click the option you’re using below and follow the instructions.
For the connection to be successful, you’ll need to configure your firewall to allow access from our IP addresses. Whitelist the following IPs before continuing onto the next step:
- Follow the steps in the Setting up an SSH Tunnel for a database connection guide to set up an SSH tunnel for MongoDB.
- Complete the steps in this guide after the SSH setup is complete.
Step 3: Create a Stitch database user
Atlas MongoDB authentication
Stitch’s MongoDB integration is designed to use a user authentication method that requires Mongo database users to be validated against their authentication database. Read more about Mongo authentication here.
Currently, Stitch’s MongoDB integration currently assumes the database entered in the Integration Settings page is the authentication database. Due to MongoDB’s authentication process and Stitch’s current functionality, the database entered into Stitch in the next step must be the user’s authentication database.
For Atlas-based instances, the Stitch user must be able to perform the actions in the Privileges list tab on the
admin database and the other databases you want to replicate, if any. This is due to the design of Stitch’s integration and Mongo’s authentication requirements.
Step 3.1: Connect to your database
- Connect to your MongoDB server.
Navigate to the authentication database. In this example, we’re using
<port>with your MongoDB username, database host address, and the port used by the database, respectively.
Note: If you’re connecting an Atlas-based instance, the authentication database will always be
Step 3.2: Create the Stitch user
Next, you’ll create the Stitch user, set a password, and assign roles. This guide uses the built-in
readAnyDatabase role, but you can use or create another role as long as it assigns the same privileges.
Select the version your MongoDB database is using to view the correct command to create the Stitch database user.
See the Privileges list tab for an explanation of why these permissions are required by Stitch.
In the table below are the database user privileges Stitch requires to connect to and replicate data from a MongoDB database.
|Privilege name||Reason for requirement|
Required to read data from databases in the cluster.
Note: You only need to explicitly grant this role if you’re using MongoDB version 3.4 or greater.
Required to read from the
Step 4: Connect Stitch
Stitch and MongoDB connections
Stitch uses a standalone server connection to connect to your MongoDB instance. What this means is that if you want Stitch to run on secondary instances, you have to give Stitch a host IP for one of your secondary instances.
In the case of Mongos (sharded Mongo), Stitch will always attempt to run data sync queries on your secondaries by default and you can provide the host IP for the master node.
In this step, you’ll complete the setup by entering the database’s connection details and defining replication settings in Stitch.
Step 4.1: Define the database connection details
- If you aren’t signed into your Stitch account, sign in now.
On the Stitch Dashboard page, click the Add Integration button.
- Locate and click the MongoDB icon.
Fill in the fields as follows:
Integration Name: Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.
For example, the name “Stitch MongoDB” would create a schema called
stitch_mongodbin the destination. Note: The schema name cannot be changed after the integration is saved.
Host (Endpoint): Enter the host address (endpoint) used by the MongoDB instance. For example: This could be a network address such as
220.127.116.11, or a server endpoint like
Port: Enter the port used by the instance. The default is
Username: Enter the Stitch MongoDB database user’s username.
Password: Enter the password for the Stitch MongoDB database user.
Database: Enter the name of the MongoDB database where the Stitch user is to be authenticated. Stitch will ‘find’ all the databases you gave the Stitch user access to - this is needed only to complete the connection.
Note: If you’re connecting an Atlas-based MongoDB instance, this must be the
admindatabase. See the Create a Mongo database user section for more info on this requirement.
Step 4.2: Define the SSH connection details
If you’re using an SSH tunnel to connect your MongoDB database to Stitch, you’ll also need to define the SSH settings. Refer to the Setting up an SSH Tunnel for a database connection guide for assistance with completing these fields.
- Click the Encryption Type menu.
Select SSH to display the SSH fields.
Fill in the fields as follows:
Remote Address: Enter the public IP address or hostname of the server Stitch will SSH into.
SSH Port: Enter the SSH port on your server. (
SSH User: Enter the Stitch Linux (SSH) user’s username.
Step 4.3: Define the SSL connection details
Click the Connect using SSL checkbox if you’re using an SSL connection. Note: The database must support and allow SSL connections for this setting to work correctly.
Step 4.4: Create a replication schedule
In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.
MongoDB integrations support the following replication scheduling methods:
To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.
Step 4.5: Save the integration
When finished, click Save Integration.
Stitch will perform a connection test to the MongoDB database; if successful, a Success! message will display at the top of the screen. Note: This test may take a few minutes to complete.
Step 5: Select data to replicate
The last step is to select select the collections you want to replicate.
When you track a collection, you’ll also need to define its Replication Key. Note: Any table set to replicate will use Key-based Incremental Replication. Stitch doesn’t currently support other Replication Methods for this version (v11-01-2016) of the MongoDB integration.
You can select collections by:
- In the Integration Details page, click the Collections to Replicate tab.
- Locate a collection you want to replicate.
- Click the checkbox next to the object’s name. A green checkmark means the object is set to replicate.
If there are child objects, they’ll automatically display and you’ll be prompted to select some. Note: When you track a table, by default all fields will also be tracked; additionally, tracking individual fields isn’t currently supported at this time.
After you set a collection to replicate, a page with the collection’s fields will display. De-select fields if needed.
In the Collection Settings page, define the collection’s Replication Key.
- Repeat this process for every collection you want to replicate.
Initial and historical replication jobs
After you finish setting up MongoDB, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.
For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.
Initial replication jobs with Anchor Scheduling
If using Anchor Scheduling, an initial replication job may not kick off immediately. This depends on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.
Free historical data loads
The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.
Supported Replication Methods
Only Key-based Incremental Replication is supported for MongoDB integrations at this time. If a collection ever requires full replication - for example, to backfill existing rows with a new field’s values - will require a full re-replication of the integration’s data. Refer to the Reset Replication Keys guide for more info.
MongoDB Replication Keys
Unlike Replication Keys for other database integrations, those for MongoDB have special considerations due to MongoDB functionality. For example: MongoDB allows multiple data types in a single field, which can cause records to be skipped during replication.
Refer to the MongoDB Replication Keys guide before you define the Replication Keys for your collections, as incorrectly defining Replication Keys can cause data discrepancies.
Data selection limitations
MongoDB data can only be tracked at the collection level. This means that when a collection is set to replicate in Stitch, all documents in the collection will also be selected.
Heavily nested data and destination column limits
MongoDB documents can contain heavily nested data, meaning an attribute can contain many other attributes.
If your destination doesn’t natively support nested data structures, Stitch will de-nest them to load them into the destination. Depending on how deeply nested the data is and the per table column limit of the destination, Stitch may encounter issues when loading heavily nested data.
Refer to the Nested Data Structures guide for more info and examples.
SSL Connection Errors
Fields Missing from Replication Key Menu
If fields you expect to see are missing from a collection’s Replication Key menu, it may be that the fields aren’t indexed. Refer to the Mongo Replication Keys guide for more info.