Database Settings

The following database settings are implemented in the libbitcoin-database and exposed in both Bitcoin Node (BN) and Bitcoin Server (BS).

[database]
# The blockchain database directory, defaults to 'blockchain'.
directory = blockchain
# Flush each write to disk, defaults to false.
flush_writes = false
# Full database files increase by this percentage, defaults to 50.
file_growth_rate = 50
# Block hash table size, defaults to 650000.
block_table_buckets = 650000
# Transaction hash table size, defaults to 110000000.
transaction_table_buckets = 110000000
# Spend hash table size, defaults to 250000000.
spend_table_buckets = 250000000
# History hash table size, defaults to 107000000.
history_table_buckets = 107000000
# The maximum number of entries in the unspent outputs cache, defaults to 10000.
cache_capacity = 10000

directory

This should be an SSD. There must be sufficient space to hold the database, including operating expansion. See also hardware requirements. The node files are block_index, block_table and transaction_table. The additional server index files are history_rows, history_table, spend_table, and stealth_rows. The (zero byte) lock files are flush_lock and exclusive_lock.

flush_writes

The store signals the start of a transactional commit using an empty file named flush_lock. The file is cleared when the write is flushed to disk. Therefore if the process is running the presence of the file indicates an unflushed write. If the node detects the file at startup it assumes that the preceding write was not flushed and fails to start the blockchain. In this case the blockchain must be deleted and a new one initialized before starting the node. Deleting the flush_lock file and starting with a corrupt store will produce undefined behavior (including seemingly proper operation for some arbitrary period of time). See also withstanding hard shutdowns. Enabling this setting significantly slows initial block download and may slow transaction processing, but due to block prioritization will not cause the server to fall behind in confirmed blocks.

file_growth_rate

When more space is required for writing to a file it is expanded at this rate. For example, if the file is logically full at 10,423,553 bytes, 1 new byte must be written, and configuration is file_growth_rate = 43, the file will be expanded to 143% * 10,423,553 = 14,905,680 bytes. This expansion is initially "empty" and is filled over time. When the process terminates the file is reduced to match its logical size. The reallocation process can be costly, especially on a machine with limited available memory. Additionally reallocation is frequent early in the chain since the initial sizes are almost zero. Once the files are large it makes sense to reduce this rate.

block_table_buckets

This value is for tuning the block hash table. Once the store is created this value must not be changed (and must remain in the configuration file).

transaction_table_buckets

This value is for tuning the transaction hash table. Once the store is created this value must not be changed (and must remain in the configuration file).

spend_table_buckets

This value is for tuning the spend hash table. Once the store is created this value must not be changed (and must remain in the configuration file).

history_table_buckets

This value is for tuning the history hash table. Once the store is created this value must not be changed (and must remain in the configuration file).

cache_capacity

The implementation maintains no unspent output (UTXO) database apart from transactions. However a configurable unspent output cache is implemented internal to the database. Zero cache is optimal for machines with high levels of RAM. Other machines should configure this value. The number represents a count of transactions, where the unspent outputs of these transactions are maintained in a circular buffer, ordered by age, until they are either spent or pushed out of the buffer by new transactions. Since full blocks contain on the order of 2,500 transactions, a value of 10,000 represents about four such blocks worth of unspent outputs.