2.8. Upgrading from CouchDB 1.x¶
CouchDB 2.x fully supports upgrading from CouchDB 1.x. A data migration
process is required to use CouchDB 1.x databases in CouchDB 2.x. CouchDB
2.1 supplies a utility,
couchup, to simplify the migration process.
couchup utility is a Python script that supports listing CouchDB
1.x databases on a CouchDB 2.x installation, migrating them for use with
CouchDB 2.x, rebuilding any database views after migration, and deleting
the 1.x databases once migration is complete.
couchup makes it easy to migrate your CouchDB 1.x databases to CouchDB 2.x by providing 4 useful sub-commands:
list- lists all CouchDB 1.x databases
replicate- replicates one or more 1.x databases to CouchDB 2.x
rebuild- rebuilds one or more CouchDB 2.x views
delete- deletes one or more CouchDB 1.x databases
Once you have installed CouchDB 2.x, copy the .couch files from your 1.x installation (or, if you’ve upgraded in-place, do nothing), then use commands similar to the following:
$ couchup list # Shows your unmigrated 1.x databases $ couchup replicate -a # Replicates your 1.x DBs to 2.x $ couchup rebuild -a # Optional; starts rebuilding your views $ couchup delete -a # Deletes your 1.x DBs (careful!) $ couchup list # Should show no remaining databases!
The same process works for moving from a single 1.x node to a cluster of 2.x nodes; the only difference is that you must complete cluster setup prior to running the couchup commands.
- Lots of extra help is available via:
$ couchup -h $ couchup <sub-command> -h
Various optional arguments provide for admin login/password, overriding ports, quiet mode and so on.
couchup deletewill NOT delete your 1.x DBs unless the contents are identical to the replicated 2.x DBs, or you override with the
-f/--forcecommand (be VERY careful with this!!)
couchup replicatesupports an optional flag,
-f/--filter-deleted, to filter delete documents during the replication process. This can improve the performance and disk-size of your database if it has a lot of deleted documents.
It is IMPORTANT that no documents be deleted from the 1.x database during this process, or those deletions may not successfully replicate to the 2.x database. (It’s recommended that you not access or modify the 1.x database at all during the whole
2.8.2. Manual CouchDB 1.x migration¶
If you cannot use the
couchup utility, or prefer to migrate
yourself, a manual migration is also possible. In this process, a
full-featured HTTP client such as
curl is required.
The process is similar to the automated approach:
- Copy all of your 1.x .couch files to the CouchDB 2.x
data/directory and start CouchDB (2.x).
- Set up replication for each database from the node-local port (default: 5986) to the clustered port (default: 5984). This can be done via the /_replicate endpoint or the replicator database.
- Rebuild each view by accessing it through the clustered port.
- Confirm that all databases and views can be accessed as desired.
- Remove the 1.x databases via a
DELETErequest on the node-local port (default: 5986).