Skip to content

Detailed documentation of db_dir #514

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

Merged
romanz merged 1 commit into from
Sep 30, 2021
Merged

Detailed documentation of db_dir #514

Show file tree
Hide file tree
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
3 changes: 2 additions & 1 deletion RELEASE-NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
11 changes: 9 additions & 2 deletions doc/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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

Expand Down