Database Setup

Database Setup

SXBans supports five storage backends. Here's how to pick one, and how to set up each.

Which one should I actually use?

JSON — if you're running one server, or a small network, and you don't already have a database server running for something else. Zero configuration, works immediately, easy to back up (it's just files). The only real downside is it doesn't scale as gracefully to tens of thousands of punishment records, and you can't query it with normal SQL tools if you ever want to.

SQLite — a nice middle ground. Still a single file, still no external server needed, but it's a real relational database under the hood so it holds up better at scale than JSON and you can query it with SQL tools if you want to poke around.

MySQL / PostgreSQL — if you're running a network of servers sharing one punishment database, or you already run one of these for other plugins and would rather not manage a second storage system. This is also the right call if you want other tools/dashboards querying punishment data directly.

H2 — an embedded SQL database, similar niche to SQLite. Include it if you specifically want H2 for other reasons in your stack; for most people SQLite covers the same use case more simply.

JSON (default)

Nothing to configure. Data lives under plugins/SXBans/data/.

database:
  type: json

SQLite

database:
  type: sqlite

Also nothing to configure — the .db file is created automatically under the plugin's data folder.

MySQL

1. Create a database and a user with privileges on it:

   CREATE DATABASE sxbans CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'sxbans_user'@'%' IDENTIFIED BY 'a-real-password';
   GRANT ALL PRIVILEGES ON sxbans.* TO 'sxbans_user'@'%';
   FLUSH PRIVILEGES;

   Note the utf8mb4 charset — SXBans' own table creation already specifies this, but if you're pre-creating the database yourself, match it. MySQL's older default utf8 charset can't store emoji or a lot of Unicode symbols, and you'll end up with mangled punishment reasons if the charset doesn't match.

2. Point the config at it:

   database:
     type: mysql
     mysql:
       host: localhost
       port: 3306
       database: sxbans
       username: sxbans_user
       password: 'a-real-password'

3. Restart. SXBans creates its own tables on first connect — you don't need to run any schema scripts yourself.

PostgreSQL

Same idea as MySQL:

database:
  type: postgresql
  postgresql:
    host: localhost
    port: 5432
    database: sxbans
    username: sxbans_user
    password: 'a-real-password'

PostgreSQL is UTF-8 by default, so there's no charset gotcha to worry about here.

H2

database:
  type: h2

Runs embedded, file lives in the plugin's data folder, no server process required.

Switching backends later

SXBans doesn't currently migrate data automatically when you switch database.type — it'll just start writing to the new backend from a clean slate. If you need your existing punishment history carried over to a new backend, that's a manual export/import job (the /sxbans backup command gives you a JSON snapshot as a starting point, regardless of which backend you're currently on).

Connection pooling

MySQL and PostgreSQL connections go through HikariCP under the hood, so you don't need to worry about connection leaks or manually tuning pool sizes for a typical server — the defaults are sane for anything short of a very large network.