Migration jobs are the worker processes responsible for transferring your data and schemas from a relational database to MongoDB. Create a new migration job from the Data Migration tab.
About this Task
The URI credentials you provide when creating a migration job do not need to be the same as the credentials you used when creating your project.
You can use an existing Relational Database Connection, or create one when you create the migration job.
Before you Begin
Create one or more mapping rules in your Relational Migrator project.
For both Atlas and on-premises deployments, create a separate MongoDB user for Relational Migrator with
readWriteaccess to your MongoDB database.If you're using a JDBC driver to perform a snapshot migration, contact your MongoDB representative for configuration information.
Steps
Enter the relational database connection details
On the Connect to your source database form, enter the connection details to create the JDBC URI for your relational database.
To use a saved relational database connection, click Use a saved connection and select it from the drop-down, then enter credentials if required.
To create a new connection:
In the Database type drop-down, select the database type.
To enter a connection string directly, enable the Enter URI manually toggle and paste your connection string into the JDBC URI.
To create a connection string by entering database information, enter the following:
FieldValueHost
The host IP or DNS name.
Port
The port number.
Database
The database name. Required.
Identifier
One of Service Name or SID.
Username and Password
The credentials to use for authentication.
Checking Save password saves the password securely on your machine, so you don't have to enter the Username and Password again when using the saved connection.
FieldValueHost
The host IP or DNS name.
Port
The port number.
Database
The database name. If blank, you only see objects in the default
dboschema in all databases.Authentication
By default, this is set to SQL Server. Set to Windows to enable Windows Integrated Authentication, using the credentials of the user who launched the Relational Migrator executable. This disables the Username and Password fields.
Username and Password
The credentials to use for authentication. Disabled if Authentication is set to Windows.
Checking Save password saves the password securely on your machine, so you don't have to enter the Username and Password again when using the saved connection.
General / SSL toggle
View SSL settings for the connection.
To use SSL, you must first uncomment and update the
server.sslconfiguration properties in youruser.propertiesfile.SSL: Use SSL
Enable or disable SSL.
SSL: Trust server certificate
With SSL enabled, check this to trust the stored certificate. Leave unchecked to verify the server certificate against a trusted Certificate Authority.
FieldValueHost
The host IP or DNS name.
Port
The port number.
Database
The database name. Leave blank to load all databases.
Username and Password
The credentials to use for authentication.
Checking Save password saves the password securely on your machine, so you don't have to enter the Username and Password again when using the saved connection.
General / SSL toggle
View SSL settings for the connection.
To use SSL, you must first uncomment and update the
server.sslconfiguration properties in youruser.propertiesfile.SSL: Use SSL
Enable or disable SSL.
SSL: SSL mode
With SSL enabled, choose from:
Preferred (default): Make an encrypted connection if possible, otherwise fall back to an unencrypted connection.
Required: Require an encrypted connection.
Verify CA: Verify the server certificate against a trusted Certificate Authority.
Verify identity: Verify the database connection information against the certificate contents.
FieldValueHost
The host IP or DNS name.
Port
The port number.
Database
The database name. Leave blank to connect to the default database.
Username and Password
The credentials to use for authentication.
Checking Save password saves the password securely on your machine, so you don't have to enter the Username and Password again when using the saved connection.
General / SSL toggle
View SSL settings for the connection.
To use SSL, you must first uncomment and update the
server.sslconfiguration properties in youruser.propertiesfile.SSL: Use SSL
Enable or disable SSL.
SSL: SSL mode
With SSL enabled, choose from:
Prefer (default): Make an encrypted connection if possible, otherwise fall back to an unencrypted connection.
Require: Require an encrypted connection.
Verify CA: Verify the server certificate against a trusted Certificate Authority.
Verify full: Verify the database connection information against the certificate contents.
Enter a Connection name and optional Environment tag.
Click Connect.
The saved connection is available for use in all jobs and projects.
Enter MongoDB connection details
To use a saved MongoDB connection, click Use a saved connection and select it from the drop-down, then enter credentials if required.
To create a new connection:
Enter the MongoDB connection string.
In MongoDB connection string (URI), enter your MongoDB URI.
If you're using X.509 authentication, Relational Migrator verifies the connection string syntax and the certificate file format.
If it isn't included in the connection string, enter the Database to connect to.
If they aren't included in the connection string and you aren't using X.509 authentication, enter the Username and Password of your Relational Migrator MongoDB user.
Enter a Connection name and optional Environment tag.
Click Connect.
The saved connection is available for use in all jobs and projects.
On the Migration Options form, select Migration Options:
Migration Option | Description |
|---|---|
Drop destination collections before migration | Boolean. Indicates whether Relational Migrator drops a destination collection before transferring data. |
Stop after errors | Integer. Indicates the number of errors after which Relational Migrator stops the migration job. |
Verify migrated data | Boolean. If true, the sync engine verifies migrated data against the source database. Only supported for snapshot mode. |
Data truncation | Enum. Controls how Relational Migrator handles truncation issues during migration. |
When you set the Mode, Relational Migrator runs preflight checks against your source database to confirm that it has the required configuration and permissions. If the database does not meet a requirement, Relational Migrator displays a warning below the mode selection with the number of failed checks.
To review the failures, click View details. The Preflight checks failed dialog lists each failed check, the tables it affects, and the remediation SQL. You can copy an individual statement or download a script that contains the fixes for every failed check.
Important
The remediation script grants permissions and changes the configuration of your source database. Before you run it, review the script with a database administrator.
(Optional) Indicate collections to migrate for a selective migration.
If you want to migrate only a subset of the collections in your project, click Selective Migrations and choose the collections you want to migrate. If you want to migrate all collections in your database, skip this step.
The tabs below explain the different ways you can select collections to migrate:
Under Selective migration, use the check marks to select collections:
All collections within a database: Click the check mark for the database.
Specific collections within a database: Expand the database and select individual collections.
Switch to Bulk Selection.
Paste or type a comma-separated list of collection names. For example,
collection1,collection2.As you type, Relational Migrator filters the list and lets you click matching collections to include or exclude them.
Review and start your migration job
On the Review Summary form, review the following details before starting your migration job:
Type: The migration mode.
Tables and rows affected: The number of tables and rows included in the migration.
Estimated data size: The approximate size of the data to migrate.
Drop destination collections: Whether Relational Migrator drops collections before migration.
Stop migration after: The number of errors after which the migration stops.
Collections to migrate: The collections included in this migration.
To start your migration job, click Start.
Important
For large migration jobs to an Atlas cluster, the Review Summary may include Atlas Performance Suggestions that recommend higher cluster tiers. Upgrading is optional, but reduces migration time.
Click Upgrade on Atlas to open Atlas in a new browser tab or window. If you want to upgrade, but don't have the necessary permissions, please contact your administrator.
Next Steps
Learn More
For detailed information regarding the configuration requirements for each database, see the following: