Skip to content

:Added practical upgrade lessons learned that may help others #5407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+21 −0
Open

:Added practical upgrade lessons learned that may help others #5407

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions src/docs/src/install/upgrading.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,24 @@ 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.

Upgrading from CouchDB 2.x
==========================

However CouchDB is backwards compatible between 2.x and 3.x there are a few practical
issues when upgrading. These were taken from the field upgrading a cluster with 10k dbs:

#. Newer releases are most likely built using a newer Erlang/OTP version. If your
current CouchDB cluster is running on OTP < 23 and you are upgrading to a version
which is built and will be running OTP > 26 the nodes won't communicate while in
the rolling upgrade. If downtime is not an option then you should consider
a staged upgrade.
#. When upgrading from 2.1 there is a breaking change causing errors on document
attachment uploads. Please
`see issue: <https://github.com/apache/couchdb/issues/1578>`_
#. There is are new default thresholds for smoosh that may or may not be present in your old config.
If the configuration is not adjust you may experience high cpu usage on the upgraded cluster.
`see issue: <https://github.com/apache/couchdb/issues/3047>`_
#. Make sure you have configured the :ref:`view_index_dir<config/view_index_dir>` parameter. In previous version this defaulted
to the value of :ref:`database_dir<config/database_dir>`. Not setting this may cause the cluster to start rebuilding all
views and they may end up in the wrong place on the filesystem.