MySQL / MariaDB

When one server outgrows SQLite, or several servers need the same data, point the storage backend at MySQL or MariaDB. Both speak the MySQL wire protocol, so type = "mysql" drives either.

Why MySQL / MariaDB?

Recommended for: busy servers, heavy economies, and any cross-server network.

Requirements

• MySQL 8.0 or newer, or MariaDB 10.5 or newer.
• A database and a user the plugin can connect with.

Step 1: Create the Database

Connect to your database server and run:

CREATE DATABASE uxmessentials CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'uxmessentials'@'%' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON uxmessentials.* TO 'uxmessentials'@'%';
FLUSH PRIVILEGES;

Replace your_secure_password with a strong password. Use 'localhost' instead of '%' if the database runs on the same machine as the server and you do not need remote access.

Step 2: Configure the Plugin

Edit the storage block in plugins/uxmEssentials/config.conf:

storage {
  type = "mysql"                    # sqlite | mysql | postgres  (MariaDB uses "mysql")
  host = "localhost"
  port = 3306                       # default 3306 for MySQL / MariaDB
  database = "uxmessentials"
  username = "uxmessentials"
  password = "your_secure_password"
  pool-size = 8                     # size of the read-connection pool
  connection-timeout-ms = 5000      # how long to wait for a connection before failing
}

uxmEssentials builds the JDBC connection for you from host, port and database: there is no raw URL to paste. For a remote database, point host at that machine and make sure its port (default 3306) is reachable through your firewall and allowed for the user you created.

Connection Pool Sizing

Connections are pooled by HikariCP. On a network backend there is no single-writer pin: the database's own row-level locking keeps things safe, so reads and writes run in parallel.

• pool-size = 8 is a sensible default for most servers. Raising it helps a read-heavy server (frequent balance/home/warp lookups); there is little point pushing it far past the number of cores your database can actually serve.
• Keep connection-timeout-ms at 5000 unless you see timeout warnings on a slow or remote link: a higher value hides a saturated pool rather than fixing it.

Migrations Are Automatic

You never create tables by hand. On enable, Flyway applies any pending schema migrations to the database and records what it has run, so upgrades are safe and repeatable. A disabled module runs none of its migrations. Once the server is up, confirm the connection with:

/uxmess doctor

It reports the active backend and whether the database is healthy.

Migrating from SQLite

Set type = "mysql" (or "mariadb") and copy-from-file = true in the same storage block, and restart once. The plugin builds the schema on the new database, brings the SQLite file up to date, and copies every table of it into the empty tables in one transaction. The log says how many rows came across. Set copy-from-file back to false afterwards; left on, it copies nothing twice, because the tables are no longer empty.

If any table on the new database already holds rows, nothing is copied and the log says which table. Empty that database, or point the block at a fresh one, and restart again.

Troubleshooting

Related: PostgreSQL Setup, Cross-Server, config.conf (Globals), Economy