Database

The decision is really one question: does more than one server need to see these punishments?

No means SQLite. It is a file, needs no service, and is fast enough for any single server's punishment volume.

Yes means MySQL, MariaDB, or PostgreSQL. SQLite is a local file and cannot be shared between servers, even on the same machine. Two servers pointed at the same SQLite file will corrupt it.

storage:
  type: "sqlite"
  table-prefix: "blazebans_"

type accepts sqlite, mysql, mariadb, postgresql, or h2.

table-prefix is prepended to every table name. Change it only if you are sharing a database with something that would collide, and change it before there is data, since existing tables are not renamed.

sqlite:
  file: "blazebans.db"

The filename inside plugins/BlazeBans/. Nothing else to configure.

Back it up by copying the file while the server is stopped. Copying it live can catch a write in progress.

mysql:
  host: "127.0.0.1"
  port: 3306
  database: "blazebans"
  username: "blazebans"
  password: "change-me"
  jdbc-parameters:
    useUnicode: "true"
    characterEncoding: "utf8"
    useSSL: "false"

MariaDB uses the same shape under a mariadb: key, with jdbc-parameters empty by default.

jdbc-parameters is passed straight to the driver. Add TLS options there when your database requires an encrypted connection:

mysql:
  jdbc-parameters:
    sslMode: "VERIFY_IDENTITY"
    trustCertificateKeyStoreUrl: "file:/path/to/truststore.jks"
    trustCertificateKeyStorePassword: "change-me"

Before starting, create the database and a user with rights on it:

# Run these on the database server, not in a config file:
# CREATE DATABASE blazebans CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# CREATE USER 'blazebans'@'%' IDENTIFIED BY 'a-real-password';
# GRANT ALL PRIVILEGES ON blazebans.* TO 'blazebans'@'%';

BlazeBans creates and migrates its own tables on first connection.

postgresql:
  host: "127.0.0.1"
  port: 5432
  database: "blazebans"
  username: "blazebans"
  password: "change-me"
  jdbc-parameters: {}

Same shape. Add driver-specific TLS options under jdbc-parameters.

h2:
  file: "blazebans-h2"
  username: "sa"
  password: ""

Useful for development. For a live single server, SQLite is the better choice.

You do not install anything. Whichever backend you configure, BlazeBans has the driver for it.

On Paper and Folia those drivers are downloaded the first time the plugin starts, so that one start needs outbound internet access. If your host blocks it, allow repo.papermc.io and Maven Central beforehand. On Velocity they are already inside the jar, which is why that download does not apply there.

If the configured backend cannot be reached at startup, BlazeBans falls back to SQLite rather than failing to load, and warns administrators in game and in console.

That keeps moderation working during a database outage, but the punishments issued during the fallback are written to the local file, not to your real database. They will not be there when the connection comes back.

Treat the fallback warning as urgent. Fix the connection, restart, and check whether anything was issued in the meantime.

Changing storage.type and reloading points BlazeBans at the new backend. It does not move your data.

To migrate:

1. Stop the server.
2. Export the existing data with your database's own tools.
3. Import it into the new backend.
4. Change database.yml.
5. Start the server and check /blazebans version reports the backend you expect.

For a small SQLite database, the simplest route is often a fresh start plus an import, depending on where the history came from.

/blazebans version

Prints the version, platform, and storage backend in use. If the storage line says SQLite when you configured MySQL, either the reload did not take or the fallback is active. Check the console for the reason.

Punishment history is the record of every moderation decision your team has made. It is worth backing up properly.

• SQLite: copy the file with the server stopped.
• MySQL and MariaDB: mysqldump on a schedule.
• PostgreSQL: pg_dump on a schedule.

Test a restore at least once. A backup you have never restored is a hypothesis.

database.yml holds a password. BlazeBans redacts it from /blazebans dump, so diagnostics are safe to share, but the file itself is not. Do not paste it into a support channel and do not commit it to a public repository.