| .. Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| .. use this file except in compliance with the License. You may obtain a copy of |
| .. the License at |
| .. |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| .. |
| .. Unless required by applicable law or agreed to in writing, software |
| .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| .. License for the specific language governing permissions and limitations under |
| .. the License. |
| |
| .. _install/upgrading: |
| |
| ===================================== |
| Upgrading from prior CouchDB releases |
| ===================================== |
| |
| 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. |
| |
| Upgrading from CouchDB 2.x |
| ========================== |
| |
| If you are coming from a prior release of CouchDB 2.x, upgrading is simple. |
| |
| Standalone (single) node upgrades |
| --------------------------------- |
| |
| If you are running a standalone (single) CouchDB node: |
| |
| #. Plan for downtime. |
| #. Backup everything. |
| #. Check for new recommended settings in the shipped ``etc/local.ini`` file, |
| and merge any changes desired into your own local settings file(s). |
| #. Stop CouchDB. |
| #. Upgrade CouchDB in place. |
| #. Be sure to :ref:`create an admin user<config/admins>` if you do not have |
| one. CouchDB 3.0+ **require** an admin user to start (the admin party has |
| ended). |
| #. Start CouchDB. |
| #. Relax! You're done. |
| |
| 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: |
| |
| #. Backup everything. |
| #. 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. |
| #. Stop CouchDB on a single node. |
| #. Upgrade that CouchDB install in place. |
| #. Start CouchDB. |
| #. Double-check that the node has re-joined the cluster through the |
| :ref:`/_membership<api/server/membership>` endpoint. If your load balancer has |
| health check functionality driven by the :ref:`/_up<api/server/up>` endpoint, |
| check whether it thinks the node is healthy as well. |
| #. Repeat the last 4 steps on the remaining nodes in the cluster. |
| #. Relax! You're done. |
| |
| 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. |