Configuration Reference

HardhatDB is configured with environment variables. There is no config file. Cluster mode stays off unless HARDHATDB_RAFT_ADDR is set.

Run the server from the go directory:

go run ./cmd/hardhatdb sql-server

Data and MySQL

Variable	Role
`HARDHATDB_DATA`	Badger directory. Default `data/hardhatdb`.
`HARDHATDB_MYSQL_HOST`	MySQL bind address. Default `localhost`. Use `0.0.0.0` for one published container. The three-node compose file binds each node's private address.
`HARDHATDB_MYSQL_PORT`	MySQL port. Default `3306`.
`HARDHATDB_TLS_CERT`	PEM certificate for the MySQL listener. Set together with `HARDHATDB_TLS_KEY` to require TLS.
`HARDHATDB_TLS_KEY`	PEM private key for the MySQL listener.
`HARDHATDB_MAX_CONNECTIONS`	Boot connection cap. Default `151`. `SET GLOBAL max_connections` updates this process.
`HARDHATDB_NET_READ_TIMEOUT`	Boot connection read timeout. Unset means no socket deadline. A bare number is seconds. `SET GLOBAL net_read_timeout` applies to connections accepted after the change.
`HARDHATDB_NET_WRITE_TIMEOUT`	Boot connection write timeout. Unset means no socket deadline. A bare number is seconds. `SET GLOBAL net_write_timeout` applies to connections accepted after the change.
`HARDHATDB_MAX_EXECUTION_TIME`	Boot per-statement deadline in milliseconds. Default `0`, which sets no deadline. `SET GLOBAL max_execution_time` updates this process.
`HARDHATDB_BACKUP_INTERVAL`	How often the leader writes a backup. A Go duration or a number of seconds. Unset disables the schedule.
`HARDHATDB_BACKUP_DIR`	Directory that receives each scheduled backup as a new subdirectory.
`HARDHATDB_BACKUP_KEEP`	How many scheduled backups to retain. Default `7`.
`HARDHATDB_SHUTDOWN_TIMEOUT`	How long `SIGTERM` waits for sessions before closing the store. Default `15s`.
`HARDHATDB_METRICS_ADDR`	Optional `host:port` for `/healthz`, `/readyz`, and `/metrics`. Unset means those routes are not served.
`HARDHATDB_SEED_EXAMPLE`	`1` creates `mydb.accounts` and `mydb.notes`, with the example rows, when `accounts` is missing. Default is off.

Accounts

Variable	Role
`HARDHATDB_BOOTSTRAP_PASSWORD`	Password for the first account. Required on the first boot of a standalone process or the Raft leader. Ignored once accounts are stored.
`HARDHATDB_BOOTSTRAP_USER`	First account name. Default `root`.
`HARDHATDB_BOOTSTRAP_HOST`	Host pattern for that account. Default `%`, so published Docker ports and other containers can connect.

Raft

Variable	Role
`HARDHATDB_RAFT_ADDR`	Turns cluster mode on and sets the Raft bind address, such as `10.116.0.2:7001`. `0.0.0.0` listens on every interface. A non-loopback address requires the three TLS variables below.
`HARDHATDB_RAFT_TLS_CERT`	PEM certificate for Raft and the write-forward port. It needs `serverAuth` and `clientAuth`.
`HARDHATDB_RAFT_TLS_KEY`	PEM private key for that certificate.
`HARDHATDB_RAFT_TLS_CA`	PEM CA that signed the certificate. Peers present the certificate and verify it with this CA.
`HARDHATDB_FORWARD_ADDR`	Write-forward listen address. The default is port 7002 on the Raft advertise host.
`HARDHATDB_RAFT_ADVERTISE`	Address other nodes dial. Defaults to `HARDHATDB_RAFT_ADDR`.
`HARDHATDB_NODE_ID`	Raft server id. Defaults to the bind address.
`HARDHATDB_RAFT_PEERS`	`id=host:port` list, comma-separated.
`HARDHATDB_RAFT_BOOTSTRAP`	`1` on exactly one node, the first time the group starts. A restart that still has Raft state ignores the flag, logs that, and joins as a follower. An empty directory asks every other peer and refuses when one already has a group or does not answer.
`HARDHATDB_RAFT_BOOTSTRAP_FORCE`	`1` creates the group even when a peer already has state or cannot be reached.
`HARDHATDB_READ_FROM`	`local` (default) serves reads on this node after it has applied its commit index. `leader` forwards ordinary reads to the leader.
`HARDHATDB_RAFT_DIR`	Raft log, snapshots, server UUID, and binlog. Default is beside the data directory.
`HARDHATDB_SERVER_UUID`	Shared by every node. It is the GTID server id in the binlog.
`HARDHATDB_BINLOG_MAX_SIZE`	Rolls the binlog after a transaction crosses this many bytes. Default is 1 GiB. `FLUSH BINARY LOGS` rolls it immediately.

Upstream replica

Variable	Role
`HARDHATDB_SOURCE_HOST`	Upstream MySQL host. When set, the current primary replicates from it. Set the same value on every node.
`HARDHATDB_SOURCE_PORT`	Upstream MySQL port. Default `3306`.
`HARDHATDB_SOURCE_USER`	Upstream MySQL user.
`HARDHATDB_SOURCE_PASSWORD`	Upstream MySQL password. It stays in a local file beside the Raft directory. A promoted node can dial only if it already has this password.
`HARDHATDB_SOURCE_TLS`	`1` stores TLS on the env-configured source. `SOURCE_SSL` does the same for `CHANGE REPLICATION SOURCE`.
`HARDHATDB_SOURCE_TLS_CA`	CA file for the upstream dial. When set, the mode is verify-CA.
`HARDHATDB_SOURCE_TLS_CERT`	Client certificate for the upstream dial.
`HARDHATDB_SOURCE_TLS_KEY`	Client key for the upstream dial.

CHANGE REPLICATION SOURCE TO, START REPLICA, and STOP REPLICA configure that job after start. The primary is the only node that connects. After a failover the new primary continues from the GTID stored with the applied rows. Accepted filters are REPLICATE_DO_TABLE, REPLICATE_IGNORE_TABLE, REPLICATE_WILD_DO_TABLE, REPLICATE_WILD_IGNORE_TABLE, REPLICATE_DO_DB, and REPLICATE_IGNORE_DB. REPLICATE_REWRITE_DB is rejected. See Replication and Migration.

Sharding

Variable	Role
`HARDHATDB_META_ADDR`	Turns the meta catalog on. Raft address of this node's meta group. The `HARDHATDB_RAFT_*` variables are the data group this process stores.
`HARDHATDB_META_ADVERTISE`	Meta address other nodes dial. Defaults to `HARDHATDB_META_ADDR`.
`HARDHATDB_META_PEERS`	Meta voters, `id=host:port`, comma-separated.
`HARDHATDB_META_NONVOTERS`	Meta replicas that copy the catalog and do not vote.
`HARDHATDB_META_BOOTSTRAP`	`1` on one meta voter, the first time the group starts. An empty directory asks the other meta peers and refuses when one already has a group.
`HARDHATDB_META_BOOTSTRAP_FORCE`	`1` creates the meta group even when a peer already has state or cannot be reached.
`HARDHATDB_META_DATA`	Badger directory for the catalog. Default `data/meta`.
`HARDHATDB_META_DIR`	Raft directory for the catalog. Default `data/meta-raft`.
`HARDHATDB_META_UUID`	Server UUID for the meta group, shared by every meta member the way `HARDHATDB_SERVER_UUID` is for a data group. Unset reuses `server.uuid` in the meta Raft directory, or generates one on first start.
`HARDHATDB_META_FORWARD`	Meta write-forward address. Required when the shard forward port would otherwise collide with it.
`HARDHATDB_SHARD_FORWARD`	`index=host:port` for one member of each data group. Schema statements are sent to every address. The index is a label.
`HARDHATDB_RANGE_SPLIT_BYTES`	When the leader's tables pass this many bytes, split one range. Unset disables the watcher.
`HARDHATDB_SPLIT_PEERS`	Spare processes for one automatic split, `id=raft=forward`, comma-separated. After that split, later splits stay on the current hosts and the watcher keeps running.

SHARD TABLE db.table BY column [CHECK column] RANGE ... records a key range in meta; the full syntax is in Sharding. A sharded insert includes the shard column. A read that does not name the shard column is sent to every range that holds the table. A write that names the shard column and touches more than one range is split per range and committed in two phases. A write with no shard key is refused.

Prometheus Metrics Demo