SQLite and MySQL

Choose a database#

Type	Recommended use
SQLite	One server, no external database, minimal maintenance
MySQL	Remote storage and an existing database backup workflow

SQLite is the default at plugins/KaFurnace/furnaces.db.

Prepare MySQL#

Create a database and a dedicated account first:

CREATE DATABASE kafurnace CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kafurnace'@'%' IDENTIFIED BY 'replace-with-a-strong-password';
GRANT ALL PRIVILEGES ON kafurnace.* TO 'kafurnace'@'%';
FLUSH PRIVILEGES;

Fill in database.mysql, set database.type to mysql, and restart the server. KaFurnace creates the virtual_furnaces table automatically.

Use the default sslMode=VERIFY_IDENTITY with a trusted certificate for a remote production database. Change it to sslMode=DISABLED only for an isolated temporary database on the same host. The default connection and socket timeouts are short, but a critical player action can still wait several seconds during an outage, so test the target network latency.

MySQL provides remote storage, but the first release is not a multi-server shared-state solution. Do not run multiple KaFurnace instances against the same database because their in-memory state can overwrite each other.

Write and failure semantics#

Player deposits, withdrawals, purchases, type switches, level upgrades, permanent unlocks, automatic delivery, notification claims, and conservation debits wait for database confirmation. On failure, the domain change is rolled back and the normal path does not deliver the item or upgrade state. This wait occupies the current Bukkit main thread or Folia player thread, so a high-latency MySQL server is not a suitable production backend.

A priced transaction waits for that critical write after withdrawal. If the database rejects it, KaFurnace restores domain state and attempts a refund through the original provider. If that provider also fails, administrators must reconcile the console SEVERE audit entry manually.

Ordinary background snapshots are coalesced by furnace ID, and a late old revision cannot overwrite a newer confirmed revision. Completed cycles and consumed fuel are queued immediately, but a forced process termination can still happen before a background write finishes. checkpoint-seconds is not an event log or a zero-data-loss guarantee.

Libby downloads SQLite JDBC or MySQL Connector/J on first use and verifies a SHA-256 value pinned in the plugin. KaFurnace rejects a modified cache entry or mismatched download.

Switch databases#

Changing the type does not migrate data. Have players empty all virtual items, stop the server, back up the old database, change the configuration, and start the new backend.

Pre-release test databases are incompatible with older internal schemas. Delete the old test database when validating the current schema as agreed. The current table stores five levels, three abilities, multi-slot items, experience per output slot, the active input-slot index, and notification batches.

Backups#

Back up furnaces.db while the server is stopped. For MySQL, use the existing scheduled backup or mysqldump workflow. The database contains player items and must not be omitted from backups that only cover worlds.