Set up a MySQL database for your plugins (LuckPerms example)

Some plugins and mods can keep their data in a MySQL database instead of files in their own folder. Every Torchlite server can have one database (two on the Max plan), created on the Databases page in the panel.

This guide explains when it is worth using, how to create it, where to find the connection details, and how to connect a plugin, using LuckPerms on a Paper server as the example.

Do you need a database?

Often you do not. Most plugins that support MySQL also work out of the box with a local file. LuckPerms, for example, uses a built-in H2 database file by default, and for a single server that is perfectly fine.

A MySQL database is worth setting up when:

• a plugin tells you to use one for large amounts of data. Logging plugins such as CoreProtect recommend MySQL once a world gets busy;
• you want several servers, or a website or bot, to read the same data;
• you want the data kept apart from the server's files.

If none of that applies, you can skip this guide and come back when a plugin asks for a database.

Create the database

1. Open your server in the panel and go to Databases.
2. Click New Database.
3. In the Create new database window, enter a Database name, for example luckperms. Use letters, numbers and underscores.
4. Leave Connection From empty. Empty means connections are allowed from anywhere, which includes your game server.
5. Click Create Database.

The page now says "1 of 1 databases have been allocated to this server" ("1 of 2" on the Max plan). The name you typed gets a prefix with your server's number, so luckperms becomes something like s12_luckperms. Always use the full name with the prefix.

One database is enough for several plugins. They each create their own tables with their own prefix, so LuckPerms and CoreProtect can share the same database without stepping on each other.

Find the connection details

Click Database Details on the database's row. The Database connection details window shows:

Click a value to copy it. Split the Endpoint at the colon: mysql.torchlite.host is the host and 3306 the port.

Do not use localhost or 127.0.0.1 as the host, even if a plugin's config suggests it. The database does not run inside your game server; it lives on the database host, and only the address in Endpoint reaches it.

The password is generated for you and can contain symbols. If it ever leaks, Rotate Password in the same window makes a new one, and you then update it in every plugin that uses the database.

Worked example: LuckPerms on Paper

LuckPerms is the most common reason players set up a database. The same steps work on Purpur and Spigot.

1. Install LuckPerms with the Plugin Manager, or upload the jar to the plugins folder.
2. Start the server once so LuckPerms creates its folder and config, then stop it.
3. In Files, open plugins/LuckPerms/config.yml.
4. Find storage-method and the data section below it, and change them like this, using your own values:

storage-method: mysql

data:
  address: mysql.torchlite.host:3306
  database: s12_luckperms
  username: u12_AbCdEfGhIj
  password: 'paste-the-password-here'

1. Leave the other settings, such as the table prefix, as they are.
2. Save the file and start the server.

Keep the single quotes around the password. They stop YAML from misreading symbols such as # or : inside it.

Watch the console as the server starts. LuckPerms prints which storage it is loading, and it should name MySQL. You can also run lp info in the console to see the storage type in use.

Keep your existing ranks

Switching the storage does not copy anything across: LuckPerms starts with an empty database. If you already set up groups and permissions, move them over:

1. Before you edit the config, run lp export ranks in the console. LuckPerms writes the file into its own folder.
2. Switch to MySQL as above and restart.
3. Run lp import ranks.

On Fabric, LuckPerms keeps its config in config/luckperms/luckperms.conf. The settings have the same names, written in that file's format.

Other plugins

Every plugin names the fields a little differently, but they always map to the same five values from Database Details:

• host or address: mysql.torchlite.host;
• port: 3306;
• database or name: the full name with the s prefix;
• user or username: the u username;
• password: the password.

CoreProtect, for example, has use-mysql, mysql-host, mysql-port, mysql-database, mysql-username and mysql-password in plugins/CoreProtect/config.yml. Set use-mysql to true and fill in the rest. A plugin that asks for a single JDBC URL instead takes the JDBC Connection String.

Keep the data safe

The Backups page copies your server's files, not the database. A restore therefore does not roll the database back, and a panel backup does not protect it.

The database is also deleted together with the server, for example after 5 days without activity. For data you care about, use the plugin's own export from time to time. With LuckPerms that is lp export, and you can then download the file over SFTP. The backups guide covers keeping copies of everything else.

Common problems

"Communications link failure" or "Connection refused"

The plugin cannot reach the database. Check the host and port against Endpoint, and make sure you did not leave localhost or 127.0.0.1 in the config.

"Access denied for user"

The username or password is wrong. Copy both again from Database Details; if you rotated the password, the old one stops working at once. A value in Connections from other than % can also block your server.

"Unknown database"

The database name is missing its prefix. Use the full name, such as s12_luckperms, not just luckperms.

There is no New Database button

Your server already has all the databases its plan allows (one, or two on Max), and the page shows them in the list. If the page says "Databases cannot be created for this server", ask on our Discord with your server ID.

LuckPerms still uses H2

Check that storage-method says mysql and that the YAML indentation is right. Edit the config while the server is stopped, then start it.