SQL to MongoDB migration

Moving from a relational database to MongoDB is a data modelling project with a data transfer attached, not the other way round. This page covers the decision, the process and the tools, and links to the detailed guide for each source database.

8 min read · Updated 21 August 2026

First: should you migrate at all?

Most migration guides skip this question because they are published by someone selling the destination. It is worth thirty minutes of your time, because the cheapest migration is the one you correctly decide not to do.

MongoDB is a good fit when

  • Your data is naturally hierarchical and read as whole objects — a product with its variants, an order with its lines, a document with its revisions
  • The schema changes often, or differs across records, and you are tired of migration scripts on a large table
  • You need horizontal scaling for writes, and sharding by a natural key is straightforward
  • Your busiest read paths currently require three or more joins

Stay relational when

  • Ad-hoc reporting across many entities is a core requirement — SQL is genuinely better at it
  • You depend on database-enforced referential integrity and cannot move it into the application
  • Transactions spanning several entities are ordinary rather than exceptional
  • The pain you are trying to fix is actually a missing index or an ORM generating bad queries

That last one deserves emphasis. A meaningful share of migrations are launched to fix performance problems that a well-chosen composite index would have solved in an afternoon. Before planning a migration, run EXPLAIN on your ten slowest queries. If the fix is indexing, migrating will not help — you will carry the same modelling mistakes into a database with fewer guardrails.

There is also a middle path that gets overlooked: modern MySQL and PostgreSQL both have capable JSON column types. If you need flexibility in two tables out of forty, that may be the whole answer.

What the process looks like

Regardless of the source database, a migration has the same five phases. The proportions are the surprise: the actual data transfer is usually the smallest part.

  1. Catalogue your access patterns. Which queries run, how often, returning how much. This drives everything downstream, and it comes from your query logs rather than from your schema diagram.
  2. Design the document model. For each relationship, decide whether to embed the related data or reference it. This is where a migration is won or lost.
  3. Map the data types. Mostly mechanical, with decimals, dates and NULL-versus-missing as the three recurring hazards.
  4. Move the data. A tool, an export/import pipeline, or a script that reshapes rows into documents.
  5. Translate queries and constraints. Query syntax converts readily. Foreign keys, CHECK constraints and NOT NULL do not — they move into JSON schema validation or into your application.

Phase 2 is the one to protect. Every tool on the market will happily give you one collection per table, and that shape reproduces all your joins while discarding the constraints that made them safe. If you only do one thing deliberately, make it the embed-or-reference decision.

The tools, and what each is actually for

MongoDB Relational Migrator

MongoDB's own migration tool, free, supporting Oracle, SQL Server, MySQL, PostgreSQL, Sybase and DB2. It analyses the source schema, lets you map it to a document model visually, and runs either a snapshot migration or a continuous one via change data capture. It also converts SQL queries, views and stored procedures using generative AI, and can test the converted code against both databases side by side.

Use it for: any migration of non-trivial size. Watch out for: the default one-to-one mapping, which is exactly the shape you should be designing away from.

mongoimport and mongoexport

Command-line utilities shipped with the MongoDB Database Tools. Combined with a CSV or JSON export from your source database, they cover small migrations completely.

Use it for: a handful of tables, or seeding a development environment. Watch out for: type handling — always pass --columnsHaveTypes with explicit field types.

A custom script

Read rows in batches, assemble documents in the shape you designed, bulk-insert. Slower to write, but it is the only approach that gives complete control over reshaping, and for a heavily denormalised target it is frequently the shortest path overall.

Use it for: targets whose document shape differs substantially from the source tables. Watch out for: reinventing change data capture — if you need continuous sync, use a tool.

Query conversion

Query translation is mechanical enough to automate for the common cases. The converter on this site handles SELECT, INSERT, UPDATE and DELETE with WHERE, GROUP BY, HAVING, ORDER BY, LIKE and IN, and shows how each clause maps. What no converter can do for you is decide the document model — and until that is settled, the translated queries are aimed at the wrong target anyway.

Guides by source database

The principles are shared; the specifics — data types, export tooling, quirks — differ by source.

  • MySQL to MongoDB — the full step-by-step walkthrough, with type mapping, embedding rules and the five most expensive mistakes.
  • PostgreSQL to MongoDB — coming soon. Broadly the same process, with extra attention to arrays, JSONB columns and custom types, which often already encode the document model you want.
  • SQL Server to MongoDB — coming soon. Usually the most involved case, because stored procedures and T-SQL business logic have to be relocated into the application layer.

Frequently asked questions

What is the difference between SQL and MongoDB?

SQL databases store data in tables of rows and columns with a fixed schema, and combine them at query time using joins. MongoDB stores JSON-like documents in collections, where a document can nest related data directly and different documents in the same collection can have different fields. The practical consequence is that relational databases optimise for storing each fact once, while MongoDB optimises for reading everything one operation needs in a single fetch.

Is there an automatic SQL to MongoDB migration tool?

MongoDB Relational Migrator automates the mechanical parts — reading the source schema, moving the data, and converting query syntax — and it is free. What it cannot automate is the document model: deciding which relationships to embed and which to reference depends on your application read patterns, and getting that wrong is what makes migrations fail.

Can MongoDB replace SQL entirely?

For many applications yes, but it is not a universal replacement. MongoDB supports multi-document ACID transactions, joins via $lookup and schema validation, so the old objections are largely obsolete. It remains a weaker fit for workloads dominated by ad-hoc analytical queries across many entities, where the relational model and a mature SQL optimiser still win.

How do I convert a SQL query to MongoDB syntax?

SELECT becomes find() with a query filter and a projection, WHERE conditions become filter operators such as $gt and $in, ORDER BY becomes sort(), and LIMIT and OFFSET become limit() and skip(). GROUP BY becomes an aggregation pipeline with a $group stage, and HAVING becomes a second $match after it. You can paste a statement into the converter on the home page to see the full mapping.