A newer version of this documentation is available.

View Latest

Migrating from Apache CouchDB

      +
      Migration guidelines for Apache CouchDB users.

      While related from a technology perspective, Apache CouchDB and Couchbase have significantly different capabilities that support very different application developer needs and use cases:

      • Couchbase Server, same as Membase, has a built-in memcached-based caching technology that consistently provides sub-millisecond read/write performance and is capable of hundreds of thousands of operations per second, per node. Couchbase Server also has a built-in clustering system that allows data to be automatically spread across multiple nodes.

      • Apache CouchDB is a disk-based database that is usually better suited for the use cases where super-low latency or high throughput are not a requirement. It is a single node solution with peer-to-peer replication technology and is better suited for decentralized systems and for holding data amounts that do not need to be spread out across multiple nodes.

      These differences introduce a number of significant differences for CouchDB users who want to migrate to Couchbase Server. However, once they migrate to Couchbase Server, they gain the scalability and performance advantages that Couchbase Server provides.

      Differences in Terms and Concepts

      CouchDB stores information using the concept of a document ID, which is either explicit or automatically generated. Documents are stored in JSON format. Within Couchbase Server 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 the 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.

      To query views you can use the same arguments, such as a start and end docIDs, returned row counts and query value specification. You can also use 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, the Couchbase Web Console is built into Couchbase Server that provides cluster configuration, monitoring, and view/document update functionality.

      Operation and Deployment

      With Couchbase Server, the distribution of information is automatic within the cluster. 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.