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 true.
flush_writes = true
# 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 0.
cache_capacity = 0

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

This defaults to true for server and false for node. 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 transaction processing.

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

Block hash table size, defaults to 650000.

transaction_table_buckets

Transaction hash table size, defaults to 110000000.

spend_table_buckets

Spend hash table size, defaults to 250000000.

history_table_buckets

History hash table size, defaults to 107000000.

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. By default there is no allocation for cache, which 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 the transaction is pushed out of the buffer by new transactions. Since full blocks are on the order of 5,000 transactions, a value of 10,000 represents about two such blocks worth of unspent outputs.