neighbourhoodie-nnh-logo
Consulting & Development CouchDB Support & Services Greenkeeper Training

Local.ini is Never Overwritten on CouchDB Updates posted 20/10/2020 by The Neighbourhoodie CouchDB Team

This post is part of our CouchDB Tips Series (RSS) that we publish every week. The team at Neighbourhoodie works on and with CouchDB every day and we are happy to pass on all the tips and tricks we learn along the way. If you like what you see, check out our Professional Services for CouchDB, including production support and training. If you want to continuously ensure that your CouchDB is running optimally, sign up for Opservatory, our 24/7 CouchDB analysis and diagnostics tool.

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.