SQLite and MySQL

Choose a database#

Type	Recommended use
SQLite	One server, no external database, minimal maintenance
MySQL	Sharing furnaces between backends, or using an existing MySQL 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 the MySQL connection settings in config.yml, set database.type to mysql, and fully restart. KaFurnace creates the required tables automatically. For multiple backends, also set cross-server.enabled: true on every server.

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.

When backends share MySQL, enable cross-server.enabled on every one of them. On transfer, the new server waits for the old server to finish saving before loading the player. Without this setting, do not connect several KaFurnace instances to the same database; they may overwrite player data. See the cross-server example.

When is data saved?#

Important actions such as depositing and withdrawing items or buying upgrades wait for database confirmation. If saving fails, the action is cancelled and its previous state restored. A MySQL outage or slow connection can make a click take several seconds; use a reliable, low-latency database.

If a purchase was charged but saving fails, the plugin tries to refund it. If the refund also fails, an administrator must reconcile the SEVERE console entry manually.

Cooking progress is saved periodically in the background. Completing a cooking cycle or consuming fuel also triggers a save.

Closing the furnace menu or leaving the server also submits the latest data. For a transfer, the new server loads only after the old server saves. A normal shutdown waits for saving to finish, but force-killing the process can still lose unsaved background progress. The default checkpoint-seconds: 30 is a periodic save interval, not a zero-data-loss guarantee.

On first use of a database type, the plugin downloads and verifies its driver. If the download fails or the file does not match, check the console error.

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.

KaFurnace does not automatically move furnaces or items from an old database to a new one. Back up and plan a manual migration before switching, or the new database will appear to have no player furnaces.

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.