Choose SQLite or MySQL

SQLite by default

SQLite needs no separate database server. Blockinator uses WAL mode, batched query logging, and serialized list-refresh commits to reduce writer contention. Keep its data directory persistent.

Connect MySQL

Create a MySQL 8.x database and user with privileges to create and alter application tables, indexes, views, and foreign keys. Set database variables before starting:

DATABASE_BACKEND=mysql
MYSQL_HOST=mysql.example.internal
MYSQL_PORT=3306
MYSQL_DATABASE=blockinator
MYSQL_USER=blockinator
MYSQL_PASSWORD=REPLACE_WITH_YOUR_PASSWORD

Use MYSQL_SSL_* settings when needed for database TLS. Inside a container, localhost refers to that container.

Migrate while offline

Changing DATABASE_BACKEND selects another store; it does not migrate existing records. The upstream migration tool supports SQLite ↔ MySQL with a dry run, explicit offline confirmation, row-count checks, and content verification.

Retain filesystem state

Database migration does not copy ./data/tls or ./data/caddy. Move those separately when changing hosts. Run one application process: background workers and policy snapshots are process-local.