Local.ini is Never Overwritten on CouchDB Updates posted Tuesday, October 20, 2020 by The Neighbourhoodie CouchDB Team
CouchDB is configured through configuration files on disk. The format of the files is INI.
When it starts, CouchDB reads a series of .ini files to make up the final configuration it is going to start with. This series of .ini files is called the config file chain.
By default, two config files are read: default.ini
and local.ini
and they are loaded in this order default.ini
first, local.ini,
second. This makes local.ini
the end of the config file chain. This will become important shortly.
When making changes to the configuration, CouchDB users are advised to make their configurations in local.ini.
If you’ve ever changed your bind_address
or admin
password, you likely have made changes to your local.ini file.
Why are there two files? And why do they form a chain? — Let’s dig in.
First: default.ini
includes all configuration options available for CouchDB. Since different versions of CouchDB have different configuration options, as new features added require new options, e.g., a default.ini
file is always specific to a particular version of CouchDB.
When installing CouchDB for the first time, default.ini
gets installed on the target system. When upgrading CouchDB to a newer version, default.ini
gets overwritten with the newer version, because it might include new configuration options.
Second: local.ini
is also installed the first time around, so you can make your required changes. But when you update CouchDB, local.ini
does not get overwritten, so your custom configuration will be applied to the updated version of CouchDB. Your networking and admin configuration, and whatever else you have changed continues to work just fine in the new version of CouchDB.
So here we have the answer for the first question: there are two files, so we can have both: new configuration options when new CouchDB versions come out, and: retain your custom configurations across CouchDB upgrades.
« Back to the blog post overview