Migrating from CouchDB

Migrating from CouchDB

Migration guidelines for CouchDB users

Although Couchbase Server incorporates the view engine functionality built into CouchDB, most of the remaining functionality is supported through the components and systems of Membase Server.

This change introduces a number of significant differences for CouchDB users who want to use Couchbase Server, particularly when migrating existing applications. However, they also gain the scalability and performance advantages of the Membase Server components.

Differences in terms and concepts

CouchDB stores information using the concept of a document ID (either explicit or automatically generated), against which the document (JSON) is stored. Within Couchbase there is no document ID, and information is stored in the form of a key-value pair instead. The key is equivalent to the document ID, the value is equivalent to the document, and the format of the data is the same.

Almost all of the HTTP REST API that makes up the interface for communicating with CouchDB does not exist within Couchbase Server. The basic document operations for creating, retrieving, updating and deleting information are entirely supported by the memcached protocol.

Also, beyond views, many of the other operations are unsupported at the client level within CouchDB. For example, you cannot create a new database as a client, store attachments, or perform administration-style functions, such as view compaction.

Couchbase Server does not support the notion of databases. Instead, information is stored within logical containers called Buckets . These are logically equivalent and can be used to compartmentalize information according to projects or needs. With Buckets you get the additional capability to determine the number of replicas of the information, and the port and authentication required to access the information.

Consistent functionality

The operation and interface for querying and creating view definitions in Couchbase Server are mostly identical. Views are still based on the combination of map/reduce functions, and you can port your map/reduce definitions to Couchbase Server without any issues. The main difference is that the view does not output the document ID. Instead, it outputs the key against which the key-value was stored into the database.

Querying views is also the same, and you can use the same arguments to perform a query, such as a start and end docIDs, returned row counts and query value specification, including the requirement to express your key in the form of a JSON value if you are using compound (array or hash) types in your view key specification. Stale views are also supported, and just as with CouchDB, accessing a stale view prevents Couchbase Server from updating the index.

Changed functionality

There are many changes in the functionality and operation of Couchbase Server compared to CouchDB:

* Basic data storage operations must use the memcached API.

* Explicit replication is unsupported. Replication between nodes within a cluster
  is automatically configured and enabled and is used to help distribute
  information around the cluster.

* You cannot replicate between a CouchDB database and Couchbase Server.

* Explicit attachments are unsupported, but you can store additional files as new
  key-value pairs into the database.

* CouchApps are unsupported.

* Update handlers, document validation functions, and filters are not supported.

* Futon does not exist, instead there is an entire Web Administration Console
  built into Couchbase Server that provides cluster configuration, monitoring and
  view/document update functionality.

Operational and deployment differences

The major differences between CouchDB and Couchbase Server are in options for clustering and distribution of information. With CouchDB, you need to handle the replication of information between multiple nodes and then use a proxy service to distribute the load from clients over multiple machines.

With Couchbase Server, the distribution of information is automatic within the cluster, and any Couchbase Server client library will automatically handle and redirect queries to the server that holds the information as it is distributed around the cluster.

Client and application changes

As your CouchDB based application already uses JSON for the document information and a document ID to identify each document, the bulk of your application logic and view support remain identical. However, the HTTP REST API for basic CRUD operations must be updated to use the memcached protocol.

Additionally, because CouchApps are unsupported, you need to develop a client side application to support any application logic.