From 5537c963c08162b7f660e2f622f894e123e4ed94 Mon Sep 17 00:00:00 2001 From: Martin Habovstiak Date: Wed, 29 Sep 2021 22:15:53 +0200 Subject: [PATCH] Detailed documentation of db_dir This warns users that they shouldn't touch `db_dir` internals except for deleting the old `mainnet` database. It explains in details how to do upgrade and deleting properly, calls it out in release notes and fixes small style mistake in nearby heading. It can be thought of as more explicit/detailed version of 8b8ebea0018d3e9a97ce965845b1914df4b4d8a4 or a textual alternative to PR #513. --- RELEASE-NOTES.md | 3 ++- doc/usage.md | 11 +++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 9c4ba9325..fead9f199 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -2,9 +2,10 @@ **IMPORTANT: This release contains major changes, please read carefully!** -The three main things to watch out for: +The four main things to watch out for: * Database schema changed - this will cause **reindex after upgrade**. +* `mainnet` subdirectory was renamed to `bitcoin`, you should delete `mainnet` after successful reindex. * We now use **bitcoin p2p protocol** to fetch blocks - some configurations may not work. * Trace log level now logs much more information - make sure it's not used in production. diff --git a/doc/usage.md b/doc/usage.md index ab67fa39d..0f57956a9 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -215,7 +215,11 @@ Electrs can be configured using command line, environment variables and configur It is highly recommended to use configuration files for any non-trivial setups since it's easier to manage. If you're setting password manually instead of cookie files, configuration file is the only way to set it due to security reasons. -### Configuration files and priorities +**Important:** you must configure `db_dir` to be either an empty directory or previously used by `electrs`! +The contents of this directory is considered **internal to `electrs`** and any tampering that is **not** explicitly allowed by documentation +can lead to serious problems! Currently the *only* permitted operation is *deleting whole `mainnet` subdirectory when upgrading to version 0.9.0* - see the upgrading section. + +#### Configuration files and priorities The Toml-formatted config files ([an example here](config_example.toml)) are (from lowest priority to highest): `/etc/electrs/config.toml`, `~/.electrs/config.toml`, `./electrs.toml`. @@ -499,13 +503,16 @@ Upgrading checklist: Because of reindex electrs will be unable to serve your requests for a few hours. (The exact time depends on your hardware.) If you wish to check the database without reindexing run electrs with `--no-auto-reindex`. -* The default DB path for the mainnet index was changed to `./db/bitcoin` (from `./db/mainnet`). +* If you have less than 40 GB of free space delete `mainnet` subdirectory inside your `db_dir` *before* running the new version. + Note however if you have less than 40 GB of free space you should consider extending your storage soon + since in the worst case scenario you will run out of space in ~69 days. * Make sure to allow accesses to bitcoind from local address, ideally whitelist it using `whitelist=download@127.0.0.1` bitcoind option. Either don't use `maxconnections` bitcoind option or set it to 12 or more. * If you use non-default P2P port for bitcoind adjust `electrs` configuration. * If you still didn't migrate `cookie` electrs option you have to now - see below. * If you use `verbose = 4` (or `-vvvv` argument) lower it down to `2` (`-vv`) for production use. Keeping it would waste resources because we utilize it more now. +* **After reindexing**, if you did **not** delete `mainnet` subdirectory within `db_dir` check that `electrs` works as expected and then *delete whole `mainnet` subdirectory*. ### Important changes from version older than 0.8.8