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.