Database Setup

SkinsRestorer can store skin data in MySQL instead of local files. MySQL lets multiple servers share the same skin data.

When to use database storage

Use MySQL when you:

• Run a proxy network (BungeeCord/Velocity) with multiple backend servers
• Want skin data shared across multiple servers
• Need the backend API to work on servers behind a proxy
• Have many players

Use local files when you:

• Run a single standalone server
• Do not need to share skin data between servers
• Want a simpler setup

Database configuration

Add this configuration to config.yml:

database:
  enabled: true
  host: localhost
  port: 3306
  database: skinsrestorer
  username: sr_user
  password: your_secure_password
  maxPoolSize: 10
  tablePrefix: sr_
  connectionOptions: "sslMode=trust&serverTimezone=UTC"

Configuration options

Setup guide

CREATE DATABASE skinsrestorer;

CREATE USER 'sr_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON skinsrestorer.* TO 'sr_user'@'localhost';
FLUSH PRIVILEGES;

Proxy network setup

On a proxy network, use the same database on the proxy and every backend server.

Example setup

1. Set database.enabled: true on the proxy.
2. Add the same database credentials to each backend server.
3. Make sure that the proxy and every backend server can connect to MySQL.

SSL/TLS configuration

The connectionOptions value controls the SSL connection:

For production environments with SSL certificates:

connectionOptions: "sslMode=verify-ca&serverTimezone=UTC"

Migrating from file storage

SkinsRestorer does not copy local file data to MySQL. When you enable MySQL, the database starts empty.

To restore custom skins:

1. Record each custom skin that you created with /sr createcustom.
2. Enable MySQL storage.
3. Create the custom skins again with the same commands.

After players rejoin, they can select their skins again.

Troubleshooting

Connection refused

• Make sure that MySQL accepts connections.
• Make sure that the host and port are correct.
• Allow MySQL traffic on port 3306 through the firewall.

Access denied

• Make sure that the username and password are correct.
• Grant the MySQL user access to the database.
• For a remote connection, permit the Minecraft server's IP address.

SSL errors

• For a temporary test, use sslMode=trust or sslMode=disable.
• For production, configure trusted SSL certificates.

Timezone errors

• Add serverTimezone=UTC to connectionOptions.
• To use a specific timezone, set a value such as serverTimezone=America/New_York.

Performance tuning

Connection pool size

The maxPoolSize option sets the maximum number of database connections.

• Small servers (< 100 players): 5-10 connections
• Medium servers (100-500 players): 10-20 connections
• Large networks (500+ players): 20-50 connections

Table prefix

If multiple SkinsRestorer installations share one database, give each installation a different tablePrefix.