Getting Started

Run the server from the go directory. Building needs ICU headers. The SQL engine is the go-mysql-server fork (opens in a new tab), pinned in go/go.mod and downloaded by the Go toolchain.

One process

Cluster mode stays off unless HARDHATDB_RAFT_ADDR is set.

HARDHATDB_SEED_EXAMPLE=1 HARDHATDB_BOOTSTRAP_PASSWORD=secret go run ./cmd/hardhatdb sql-server
mysql --host=127.0.0.1 --port=3306 --user=root --password=secret mydb --execute="SELECT name, email FROM accounts;"

HARDHATDB_SEED_EXAMPLE=1 creates mydb.accounts and mydb.notes when those tables are missing. accounts.id is the shard column. Leave it unset for an empty data directory. A volume created for the previous example still has mydb.mytable. Remove it before the first start on this schema: docker compose down -v.

The first boot creates one caching_sha2_password superuser. HARDHATDB_BOOTSTRAP_PASSWORD is required then and is not saved for later boots; the account lives in the data directory. The default user is root and the default host is %. CREATE USER and GRANT add further accounts.

The server listens on localhost:3306. Data is stored in data/hardhatdb. Set HARDHATDB_DATA to use another directory. Leave HARDHATDB_TLS_CERT and HARDHATDB_TLS_KEY unset to stay on plaintext. Set both to require TLS.

On a machine where ICU is installed with Homebrew:

CGO_CPPFLAGS="-I/opt/homebrew/opt/icu4c/include" \
CGO_LDFLAGS="-L/opt/homebrew/opt/icu4c/lib" \
go run ./cmd/hardhatdb sql-server

One container

docker compose build
docker run --rm -p 3306:3306 -v hardhatdb-data:/data \
  -e HARDHATDB_MYSQL_HOST=0.0.0.0 \
  -e HARDHATDB_BOOTSTRAP_PASSWORD=secret \
  hardhatdb

HARDHATDB_MYSQL_HOST=0.0.0.0 is required for the published port to accept connections. Data inside the container is /data/hardhatdb.

docker compose up n1 still starts n2 and n3, because n1 depends on them and every service sets HARDHATDB_RAFT_ADDR.

Next steps

Demo starts the three-node Compose cluster and checks a follower.
Replication covers write forwarding, the binlog, and an upstream MySQL source.
Migration loads an existing MySQL database and points clients at HardhatDB.
Reference lists every environment variable.
Operations covers shutdown, membership changes, and TLS.

Introduction Architecture