getting-started.txt

.. _rm-introduction:
.. _relational-migrator-get-started:

============================
{+rel-mig+} Overview
============================

.. facet::
   :name: genre
   :values: tutorial

.. meta::
   :description: MongoDB Relational Migrator is a tool to help you migrate your relational workloads to MongoDB.
   :keywords: database migration, database conversion

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

{+rel-mig+} is a free tool to help you migrate from a relational database to MongoDB.
This page provides an overview of {+rel-mig+}'s :ref:`key features <rm-key-features>`, 
:ref:`use cases <rm-use-cases>`, :ref:`migration scenarios <rm-migration-scenarios>`, 
and :ref:`supported databases and versions<supported-databases>`.

.. _rm-key-features:

Key Features
------------

Map and Model Data
~~~~~~~~~~~~~~~~~~

{+rel-mig+} provides an entity-relationship diagram builder to map your 
relational schema to a MongoDB schema. You can start with a recommended schema,
a 1:1 mapping, or create a new schema from scratch. For more information, 
see :ref:`<rm-mapping-rules>`.


Generate Application Code
~~~~~~~~~~~~~~~~~~~~~~~~~

{+rel-mig+} generates MongoDB-compatible C#, Java, and JavaScript application code
for entity classes, persistence layers, and APIs. 

Code generation templates support JSON output and common application frameworks like 
Spring Data, Node, and Mongoose. For more information, see :ref:`<rm-code-generation-templates>`.


Convert and Validate SQL Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{+rel-mig+} uses generative AI to :ref:`convert <rm-query-converter>` SQL queries, 
views, and stored procedures into MongoDB-compatible code for C#, Java, or JavaScript.

You can test queries within {+rel-mig+} to validate converted SQL and 
ensure that your queries are compatible with MongoDB.

Migrate to MongoDB
~~~~~~~~~~~~~~~~~~

Use {+rel-mig+} to migrate data from :ref:`supported relational databases <supported-databases>` 
to MongoDB Atlas or a self-managed MongoDB deployment. You can choose either a 
snapshot migration, or continuous synchronization with Change Data Capture (CDC).
For more information, see :ref:`<rm-use-cases>`.

{+rel-mig+} integrates with Apache Kafka and Confluent Cloud for large scale 
migrations. For more information, see :ref:`<kafka-intro>`.

.. _rm-use-cases:

Use Cases
---------

{+rel-mig+} supports both Snapshot and Continuous migration jobs.

.. include:: /includes/fact-short-sync-job-desc.rst

Some relational databases are only compatible with Snapshot migration jobs.
For more information, see the following table:

.. include:: /includes/table-supported-migration-types.rst

.. _rm-migration-scenarios:

Migration Scenarios
-------------------

You can use {+rel-mig+} to migrate one legacy application at a
time to MongoDB. Depending on your application's needs, you can migrate
either with or without downtime.

Migrate During Scheduled Downtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your application does not require constant uptime, such as in the
case of an internal application, you can have the migration occur during
scheduled downtime. Migrating during downtime is the easiest way to
configure and complete the migration process.

When you start the migration process, {+rel-mig+} takes a
snapshot of the data on the legacy application and migrates the data
from that point in time. During the migration process, your legacy
application can remain online to support incoming reads, but cannot
support incoming writes. The length of the migration process depends on
several factors, such as the amount of data being migrated and your
connection speed.

After the migration completes, take your legacy application offline and
launch your new application.


Migrate Without Downtime
~~~~~~~~~~~~~~~~~~~~~~~~

If your application must remain online to support reads and writes
during the migration process, you can use Change Data Capture (CDC) to
migrate data without downtime. This process is called a **continuous**
migration.

When you start a continuous migration job, {+rel-mig+} takes a
snapshot of the data on the legacy application and tracks database
updates in near real time. During the migration process, your source and
destination databases remain in sync.

After the continuous migration job completes, you can transfer users to
the new application and shut down the legacy application.

To learn more about migration jobs, see :ref:`rm-sync-jobs`.


Unsupported Scenarios
~~~~~~~~~~~~~~~~~~~~~

{+rel-mig+} currently does not support migrating an operational
data store. Depending on your workload, migrating a data store could
cause :abbr:`CDC (Change Data Capture)` to run indefinitely without
completing, which is not recommended with {+rel-mig+}.

{+rel-mig+} will support more migration scenarios and use cases
in future releases.

.. _supported-databases:

Supported Databases and Versions
--------------------------------

Source Databases and Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{+rel-mig+} supports the following source databases:

.. include:: /includes/table-supported-dbs-and-versions.rst


.. _jdbc-databases:

Databases Supported with a JDBC Driver
''''''''''''''''''''''''''''''''''''''

.. important::

   This feature is in public preview.

Some databases are supported for snapshot data migration through a JDBC
connection. You can run snapshot migration jobs against these databases, but
not continuous CDC sync jobs.

.. include:: /includes/table-supported-jdbc-driver-dbs.rst

Target Databases and Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{+rel-mig+} supports the following target databases:

.. include:: /includes/table-supported-mongodb-versions.rst


Learn More
----------

- `{+rel-mig+} Introductory Video Series <https://learn.mongodb.com/courses/mongodb-relational-migrator>`__
- :ref:`User Interface Overview <rm-project-overview>`



.. toctree::
   :titlesonly:
   :hidden:

   UI Overview </getting-started/overview>
   Create & Manage Projects </projects>