1.9. Upgrading from prior CouchDB releases

1.9.1. Important Notes

  • Always back up your data/ and etc/ directories prior to upgrading CouchDB.
  • We recommend that you overwrite your etc/default.ini file with the version provided by the new release. New defaults sometimes contain mandatory changes to enable default functionality. Always places your customizations in etc/local.ini or any etc/local.d/*.ini file.

1.9.2. Upgrading from CouchDB 2.x

If you are coming from a prior release of CouchDB 2.x, upgrading is simple.

1.9.2.1. Standalone (single) node upgrades

If you are running a standalone (single) CouchDB node:

  1. Plan for downtime.
  2. Backup everything.
  3. Check for new recommended settings in the shipped etc/local.ini file, and merge any changes desired into your own local settings file(s).
  4. Stop CouchDB.
  5. Upgrade CouchDB in place.
  6. Be sure to create an admin user if you do not have one. CouchDB 3.0+ require an admin user to start (the admin party has ended).
  7. Start CouchDB.
  8. Relax! You’re done.

1.9.2.2. Cluster upgrades

CouchDB 2.x and 3.x are explicitly designed to allow “mixed clusters” during the upgrade process. This allows you to perform a rolling restart across a cluster, upgrading one node at a time, for a zero downtime upgrade. The process is also entirely scriptable within your configuration management tool of choice.

We’re proud of this feature, and you should be, too!

If you are running a CouchDB cluster:

  1. Backup everything.
  2. Check for new recommended settings in the shipped etc/local.ini file, and merge any changes desired into your own local settings file(s), staging these changes to occur as you upgrade the node.
  3. Stop CouchDB on a single node.
  4. Upgrade that CouchDB install in place.
  5. Start CouchDB.
  6. Double-check that the node has re-joined the cluster through the /_membership <api/server/membership> endpoint. If your load balancer has health check functionality driven by the /_up <api/server/up> endpoint, check whether it thinks the node is healthy as well.
  7. Repeat the last 4 steps on the remaining nodes in the cluster.
  8. Relax! You’re done.

1.9.3. Upgrading from CouchDB 1.x

To upgrade from CouchDB 1.x, first upgrade to a version of CouchDB 2.x. You will need to convert all databases to CouchDB 2.x format first; see the Upgrade Notes there for instructions. Then, upgrade to CouchDB 3.x.