Databases for game servers in Pterodactyl (database host)

Plugins such as LuckPerms or CoreProtect store their data in a MySQL database. We'll set up MariaDB as a Pterodactyl database host so users can create a database for their server with one click in the Panel.

How it works#

When a user clicks New Database in their server's Databases tab, the Panel connects to the database host and creates a database s<server ID>_<name> and a user u<server ID>_<random characters> with a random password. The game server then connects to this database from its container.

The key word is container. Inside a container, the address 127.0.0.1 means the container itself, not the VPS. So the game server won't find MariaDB at 127.0.0.1. On the same VPS, however, containers can reach the server itself at 172.18.0.1 (the pterodactyl0 interface created by Wings). That's the address we'll use for the database host:

Check that the interface exists (Wings must have run at least once):

ip -4 addr show pterodactyl0

• ip -4 addr show pterodactyl0 – prints the IPv4 address of the pterodactyl0 interface.

The output contains the line inet 172.18.0.1/16. If the command says Device "pterodactyl0" does not exist, Wings hasn't run yet; finish installing it first.

An account for the Panel#

The Panel needs a MariaDB account that can create databases and users and grant them privileges. Don't use the pterodactyl account from the Panel installation; it only has privileges on the panel database.

1. Generate a strong password using only letters and digits (password generator).

2. Log in to MariaDB:

   mariadb

3. Create the account. Replace <DB_HOST_PASSWORD> with the password from step 1:

   CREATE USER 'pterodactyluser'@'172.18.0.1' IDENTIFIED BY '<DB_HOST_PASSWORD>';
   GRANT ALL PRIVILEGES ON *.* TO 'pterodactyluser'@'172.18.0.1' WITH GRANT OPTION;
   exit

Making MariaDB listen on the network#

After installation, MariaDB only listens on 127.0.0.1 (the bind-address setting in /etc/mysql/mariadb.conf.d/50-server.cnf). Containers can't reach it there. You change this with your own file that is loaded after the default one and overrides it. That way the default file stays untouched, even after package updates.

1. Create the file:

   nano /etc/mysql/mariadb.conf.d/60-pterodactyl.cnf

2. Paste the content, save and close the editor:

   [mysqld]
   bind-address = 0.0.0.0

3. Restart MariaDB and check where it listens:

   systemctl restart mariadb
   ss -tlnp | grep 3306

   • ss -tlnp – lists listening TCP ports and programs; grep 3306 picks the MariaDB line.

   You'll see 0.0.0.0:3306 and the process name mariadbd.

Firewall#

MariaDB now also listens on the VPS's public IP address. Port 3306 must stay closed to the internet. Game server database users are allowed to connect from anywhere (%) by default, so they could be logged into from outside.

Firewall in the customer area (guide):

• Block everything except allowed mode: don't add any rule for port 3306. It's closed.
• Allow everything mode: add the rule Inbound · Drop · TCP · port 3306.

Connections from containers to the VPS stay inside the server, and the customer area firewall doesn't affect them.

UFW on the VPS: if you have it enabled, it blocks connections from containers too. Allow port 3306 only from the Docker interface:

ufw allow in on pterodactyl0 to any port 3306 proto tcp

• allow in on pterodactyl0 – allows incoming traffic only from the pterodactyl0 interface (from game server containers).
• to any port 3306 proto tcp – only to TCP port 3306.

The database host in the Panel#

1. In the Panel's admin area, click Databases on the left and then Create New.
2. Fill in the form:

3. Click Create. The Panel tries to connect to the host right away. If that fails, it shows an error and doesn't save the host (see Troubleshooting).

The server's database limit#

A user can only create as many databases as you allow. The default limit is 0, in which case the Databases tab says Databases cannot be created for this server.

1. In the admin area, open Servers and click the server.
2. Go to the Build Configuration tab.
3. In Application Feature Limits, set Database Limit, for example 2.
4. Click Update Build Configuration.

Creating a database from the server#

This part is done by the server's user:

1. In the Panel, open the server and its Databases tab.
2. Click New Database.
3. Fill in Database Name, for example luckperms. The resulting name will be s<ID>_luckperms. Letters, digits, - and _ are allowed, 3–⁠48 characters long.
4. The Connections From field sets where the database user may connect from. A safe value for game servers on this node is 172.18.0.% (all containers). An empty field means %, i.e. from anywhere.
5. Click Create Database.
6. Click the eye icon next to the new database. It shows the Endpoint (172.18.0.1:3306), Connections from, Username, Password and JDBC Connection String.

Enter these details in the plugin's configuration. Most plugins want the address, database name, user and password separately. For example, LuckPerms in plugins/LuckPerms/config.yml:

storage-method: MariaDB
data:
  address: 172.18.0.1:3306
  database: s1_luckperms
  username: u1_AbCdEfGhIj
  password: '<PASSWORD_FROM_PANEL>'

• storage-method – the storage type; MariaDB or MySQL.
• address – the Endpoint from the Panel (address and port).
• database, username – the exact values from the Panel (made up in this example).
• password – the password from the Panel, in single quotes because of special characters.

Plugins that want a single string (JDBC URL) get the value from the JDBC Connection String field in the form jdbc:mysql://user:password@172.18.0.1:3306/database. More on databases for Minecraft plugins: MySQL for plugins.

Verification#

From the VPS, check that the server's user can connect via the address the containers use:

mariadb -h 172.18.0.1 -u <DB_USER> -p <DB_NAME> -e "SELECT 1;"

• -h 172.18.0.1 – connects over TCP to the Docker interface.
• -u <DB_USER> – the user from the Panel (for example u1_AbCdEfGhIj).
• -p – asks for the password.
• <DB_NAME> – the database from the Panel (for example s1_luckperms).
• -e "SELECT 1;" – runs a simple query and exits.

You'll see a table with the number 1. If you entered 172.18.0.% in Connections From, this test from the VPS passes, because a connection to 172.18.0.1 has the source address 172.18.0.1.

Finally, restart the game server and check its console to make sure the plugin connected to the database without errors.

Advanced: the database on another server#

If MariaDB runs on a different VPS than the Panel and Wings:

• Create the Panel account with the IP address of the VPS running the Panel ('pterodactyluser'@'203.0.113.10').
• In the Host field, enter the IP address of the database server. Both the Panel and the containers on the nodes must be able to reach it.
• In the database server's firewall, allow port 3306 only from the IP addresses of the Panel and the nodes (a rule with Source IP / range filled in).
• Set Connections From for server database users to the node's IP address.

Troubleshooting#

The Panel reports Access denied for user 'pterodactyluser'@'172.18.0.1' when creating the host#

The password is wrong, or the user doesn't have host 172.18.0.1. Check the accounts:

SELECT User, Host FROM mysql.user WHERE User = 'pterodactyluser';

If the host is different, delete the account (DROP USER 'pterodactyluser'@'<OLD_HOST>';) and create it again as described in An account for the Panel.

Connection refused or Can't connect to … server on '172.18.0.1'#

MariaDB isn't listening on this address. Check ss -tlnp | grep 3306 (it must show 0.0.0.0:3306) and the 60-pterodactyl.cnf file. Restart MariaDB after any change.

The plugin reports Communications link failure or a connection timeout#

The plugin couldn't reach the database. Most often the plugin configuration says localhost or 127.0.0.1 instead of 172.18.0.1, or UFW blocks the connection from the container (see Firewall).

The plugin reports Access denied for user 'u1_…'@'172.18.0.x'#

Connections From contains an address the container doesn't connect from. Delete the database and create it again with 172.18.0.%, or generate a new password for the database in the Panel if you entered it incorrectly.

The user doesn't see the New Database button#

The server has a Database Limit of 0, or the limit is used up. Change it as described in The server's database limit.

Further reading#

• Pterodactyl: Setting up MySQL (opens in a new window)
• MariaDB: Remote connection guide (opens in a new window)
• LuckPerms: Storage types (opens in a new window)