{"id":2454,"date":"2016-12-12T14:52:52","date_gmt":"2016-12-12T14:52:51","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=2454"},"modified":"2025-06-13T19:29:36","modified_gmt":"2025-06-14T02:29:36","slug":"moving-from-mongodb-to-couchbase-server-revisited","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/moving-from-mongodb-to-couchbase-server-revisited\/","title":{"rendered":"Moving from MongoDB to Couchbase server (revisited)"},"content":{"rendered":"
\n
\n
\n

Note: this blog post is a revist of Matthew Revell\u2019s Moving from MongoDB to Couchbase Server<\/a><\/em><\/p>\n<\/div>\n

\n

This is a developer-focused guide to moving your application\u2019s data store from MongoDB to Couchbase Server<\/a>. If you\u2019re interested in migrating from a relational database to Couchbase, start with Laurent\u2019s guide to making the move from PostgreSQL<\/a>, and I will be working on a SQL Server migration post in the future.<\/p>\n<\/div>\n

\n

While this guide doesn\u2019t cover every corner-case, it does offer pointers to what you should consider when planning your migration. If you\u2019re interested in learning about why<\/em> you would do this migration, or learning about a Couchbase customer that has done this migration, check out Viber<\/a>.<\/p>\n<\/div>\n

\n

If you currently use MongoDB, and you\u2019re using Mongoose ODM with Node, here is a video from the Connect 2016 conference on Migrating from MongoDB with Ottoman.js<\/a>.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

Versions<\/h2>\n
\n
\n

This guide is written for Couchbase Server 4.5 and MongoDB 3.4.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

Key differences<\/h2>\n
\n
\n

Couchbase Server and MongoDB are both document stores that can operate on one or many servers. However, they approach things in some significantly different ways.<\/p>\n<\/div>\n

\n

When you begin your migration from MongoDB to Couchbase Server, you\u2019ll need to consider the following differences:<\/p>\n<\/div>\n

\n\n\n\n\n\n\n\n
<\/td>\n\n

Couchbase Server<\/p>\n<\/td>\n

\n

MongoDB<\/p>\n<\/td>\n<\/tr>\n

\n

Data models<\/strong><\/p>\n<\/td>\n

\n

Document, key-value<\/p>\n<\/td>\n

\n

Document<\/p>\n<\/td>\n<\/tr>\n

\n

Query<\/strong><\/p>\n<\/td>\n

\n

N1QL (SQL for JSON), map\/reduce views, key-value<\/p>\n<\/td>\n

\n

Ad-hoc query, map\/reduce aggregation<\/p>\n<\/td>\n<\/tr>\n

\n

Concurrency<\/strong><\/p>\n<\/td>\n

\n

Optimistic and pessimistic locking<\/p>\n<\/td>\n

\n

Optimistic and pessimistic locking (with WiredTiger)<\/p>\n<\/td>\n<\/tr>\n

\n

Scaling model<\/strong><\/p>\n<\/td>\n

\n

Distributed master-master<\/p>\n<\/td>\n

\n

Master-slave with replica sets<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n<\/div>\n

\n

Data model<\/h2>\n
\n
\n

Couchbase Server is both a document store and a key-value store.<\/p>\n<\/div>\n

\n

Everything starts with key-value, as every document has a key that you can use to get and set the document\u2019s contents. However, you can use Couchbase Server as a document database by indexing and querying document contents. Note: if you\u2019re interested in using Couchbase as a plain key-value store, read my blog post on Using Couchbase to Store Non-JSON Data<\/a>.<\/em><\/p>\n<\/div>\n

\n

Differences between BSON and JSON<\/h3>\n
\n

It\u2019s likely that your application stores JSON-style documents in MongoDB, so we\u2019ll start there.<\/p>\n<\/div>\n

\n

MongoDB stores data in the BSON format, which is a binary JSON-like format. The key difference when migrating is that BSON records additional type information.<\/p>\n<\/div>\n

\n

When you export data from MongoDB using a tool such as mongoexport<\/em>, the tool will produce JSON that preserves that type information in a format called Extended JSON.<\/p>\n<\/div>\n

\n

Let\u2019s take a look at an example in Extended JSON:<\/p>\n<\/div>\n

\n
\n
{\r\n \"myInt\": {\r\n  \"$numberLong\": \"123\"\r\n }\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
As you can see, the Extended JSON is still valid JSON. That means you can store, index, query and retrieve it using Couchbase Server. However, you\u2019ll need to maintain that additional type information (in the above example, Extended JSON is storing a long integer as a string, for instance) in the application layer.<\/p>\n<\/div>\n
\n
Alternatively, you could convert the Extended JSON to standard JSON before (or after) you import it into Couchbase Server. With N1QL queries, this should be relatively straightforward, though potentially tedious. Here\u2019s an example that converts the “myInt” field above to a standard JSON number field:<\/p>\n<\/div>\n
\n
\n
UPDATE `default`\r\nSET myInt = TONUMBER(myInt.`$numberLong`)\r\nWHERE myInt.`$numberLong` IS NOT MISSING<\/code><\/pre>\n<\/div>\n<\/div>\n
\n
Which would result in:<\/p>\n<\/div>\n
\n
\n
{\r\n  \"myInt\": 123\r\n}<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
\n
Non-JSON data<\/h3>\n
\n
Both MongoDB and Couchbase Server can store opaque binary data.<\/p>\n<\/div>\n
\n
Although the internal representation of the binary data differs greatly between the two, you can continue to store in Couchbase Server the binary data that you\u2019ve been storing in MongoDB.<\/p>\n<\/div>\n
\n
The main difference is that Couchbase Server can store binaries of up to 20MB in size, while MongoDB offers a convenience layer for chunking very large files into multiple documents.<\/p>\n<\/div>\n
\n
There are strong arguments against storing large binaries in your database<\/a>. When you have many very large binaries, you might consider using a dedicated object storage service to store them while using Couchbase to hold metadata on those binaries.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n
\n
Architecture<\/h2>\n
\n
\n
Sharding<\/h3>\n
\n
Couchbase Server shards data, and scales horizontally, by automatically distributing a hash space amongst nodes in a cluster.<\/p>\n<\/div>\n
\n
It then uses the key of your document to decide where in the hash space\u2009\u2014\u2009and so on which node in the cluster\u2009\u2014\u2009that document resides. As a developer, this is abstracted away for you by the client SDK.<\/p>\n<\/div>\n
\n
With MongoDB you need to choose a sharding method and a shard key. The shard key is an indexed field inside your document that determines where in the cluster the document resides.<\/p>\n<\/div>\n
\n
The primary difference here is that Couchbase Server automatically handles all sharding for you, whereas MongoDB gives you the choice of sharding method and the shard key. If your applications relies on a particular distribution of data across the cluster then you\u2019ll need to adjust it to allow for the hash-based distribution used by Couchbase.<\/p>\n<\/div>\n
\n
Hash-based sharding greatly simplifies scaling compared to MongoDB. As a developer, you might think this doesn\u2019t concern you, and is an ops issue. However, it does mean that it\u2019s easier to rely on Couchbase Server should usage of your software grow.<\/p>\n<\/div>\n<\/div>\n
\n
Replication and consistency<\/h3>\n
\n
\"Three<\/div>\n<\/div>\n
\n
Couchbase Server maintains a single active copy of each document and then up to three replicas; you can configure the number of replicas on a bucketwide or per operation basis.<\/p>\n<\/div>\n
\n
This means that, during normal operation, you deal with the same live copy each time you write into and read from a document. As a result, you don\u2019t have to handle conflicting versions of documents. The replicas come into play only when the active copy is unavailable.<\/p>\n<\/div>\n
\n
As a developer, the distribution and replication of documents is abstracted away for you. You write, read and query using your connection to the bucket and the SDK handles precisely where that data is stored. There\u2019s no need to factor in replica sets or sharding schemes.<\/p>\n<\/div>\n
\n
If you know the CAP theorem<\/a>, then you also know that favoring consistency has an effect on availability. In the event of a node failure, its active documents will be unavailable for a short time to allow the cluster to promote the appropriate replicas to active status. In your code, all you need to do is retry a failed operation.<\/p>\n<\/div>\n<\/div>\n
\n
Indexing<\/h3>\n
\n
Couchbase Server offers two broad types of index:<\/p>\n<\/div>\n
\n