Database Management

Creating and managing MySQL/MariaDB databases for your server

Pterodactyl allows you to create and manage MySQL/MariaDB databases directly from the panel. Each server can have multiple databases depending on the configured limit.

Creating a Database

Create a new database for your server:

Create Database

POST /api/client/servers/{server}/databases
Content-Type: application/json

{
  "database": "minecraft",
  "remote": "%"
}

Response

{
  "object": "server_database",
  "attributes": {
    "id": "s1_minecraft",
    "name": "s1_minecraft",
    "username": "u1_xK9pL2mQ",
    "remote": "%",
    "max_connections": 0,
    "created_at": "2025-01-15T10:30:00+00:00",
    "relationships": {
      "password": {
        "object": "database_password",
        "attributes": {
          "password": "aB3$kL9mP2qR5vX8"
        }
      }
    }
  }
}

1. Navigate to Databases

   Go to your server’s Databases tab in the panel.

2. Enter Database Name

   Provide a name for your database (e.g., “minecraft”, “stats”, “economy”).

3. Set Remote Access

   Configure the remote connection host:

   • % - Allow connections from anywhere
   • 192.168.1.% - Allow from specific subnet
   • localhost - Local connections only
4. Create Database

   Click Create. The database, user, and password are generated automatically.

Database Naming

Database names are automatically prefixed with your server identifier:

• You specify: minecraft
• Actual database: s1_minecraft
• Username: u1_xK9pL2mQ (random)

This prevents conflicts between servers on shared database hosts.

Listing Databases

View all databases for a server:

List Databases

GET /api/client/servers/{server}/databases

Response

{
  "object": "list",
  "data": [
    {
      "object": "server_database",
      "attributes": {
        "id": "s1_minecraft",
        "name": "s1_minecraft",
        "username": "u1_xK9pL2mQ",
        "remote": "%",
        "max_connections": 0,
        "host": {
          "address": "mysql.example.com",
          "port": 3306
        },
        "created_at": "2025-01-15T10:30:00+00:00"
      }
    }
  ]
}

The password is not included in list responses for security. It’s only returned when creating a database or rotating the password.

Database Connection Details

Use these details to connect from your game server:

Example Plugin Config

database:
  host: mysql.example.com
  port: 3306
  database: s1_minecraft
  username: u1_xK9pL2mQ
  password: aB3$kL9mP2qR5vX8

JDBC Connection String

For Java applications:

jdbc:mysql://mysql.example.com:3306/s1_minecraft?user=u1_xK9pL2mQ&password=aB3$kL9mP2qR5vX8

PHP PDO

$pdo = new PDO(
    'mysql:host=mysql.example.com;port=3306;dbname=s1_minecraft',
    'u1_xK9pL2mQ',
    'aB3$kL9mP2qR5vX8'
);

Rotating Passwords

Change the database password for security:

Rotate Password

POST /api/client/servers/{server}/databases/{database}/rotate-password

Response

{
  "object": "server_database",
  "attributes": {
    "id": "s1_minecraft",
    "name": "s1_minecraft",
    "username": "u1_xK9pL2mQ",
    "relationships": {
      "password": {
        "object": "database_password",
        "attributes": {
          "password": "nE7$wQ4tY2pL9vB3"
        }
      }
    }
  }
}

Rotating the password immediately invalidates the old password. Update your server configuration before rotating to avoid downtime.

1. Prepare New Configuration

   Have your config file ready to update with the new password.

2. Rotate Password

   Click the “Rotate Password” button in the panel or use the API.

3. Copy New Password

   The new password is displayed once. Copy it immediately.

4. Update Configuration

   Update your server’s database configuration with the new password and restart the server.

Deleting a Database

Remove a database permanently:

Delete Database

DELETE /api/client/servers/{server}/databases/{database}

Success

HTTP/1.1 204 No Content

Deleting a database permanently removes all data and cannot be undone. Ensure you have backups before deleting.

Database Limits

Servers have a maximum number of databases they can create:

Check Limit

GET /api/client/servers/{server}

Response

{
  "attributes": {
    "feature_limits": {
      "databases": 5
    },
    "relationships": {
      "databases": {
        "data": [
          // Current databases (2 out of 5)
        ]
      }
    }
  }
}

If you try to create more databases than allowed:

Error Response

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "code": "TooManyDatabasesException",
      "status": "400",
      "detail": "This server has reached its database limit."
    }
  ]
}

Contact your server administrator to increase the database limit if needed.

Remote Access Configuration

The remote field controls which hosts can connect:

Allow All (Default)

{
  "remote": "%"
}

Permits connections from any IP address. Use this for most applications.

Specific IP

{
  "remote": "192.168.1.100"
}

Only allows connections from 192.168.1.100.

IP Range/Subnet

{
  "remote": "10.0.%.%"
}

Allows entire 10.0.0.0/16 subnet.

Localhost Only

{
  "remote": "localhost"
}

Restricts connections to the local server only.

Some database hosts may restrict remote access regardless of this setting. Check with your host provider.

Common Use Cases

Minecraft Plugin Storage

Many Minecraft plugins require MySQL for data storage:

LuckPerms:

storage-method: MySQL
data:
address: mysql.example.com:3306
database: s1_minecraft
username: u1_xK9pL2mQ
password: aB3$kL9mP2qR5vX8

CoreProtect:

table-prefix: co_
mysql:
enable: true
host: mysql.example.com
port: 3306
database: s1_minecraft
username: u1_xK9pL2mQ
password: aB3$kL9mP2qR5vX8

Game Statistics & Leaderboards

Store player stats, rankings, and leaderboards:

CREATE TABLE player_stats (
  player_uuid VARCHAR(36) PRIMARY KEY,
  kills INT DEFAULT 0,
  deaths INT DEFAULT 0,
  playtime INT DEFAULT 0,
  last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Website Integration

Connect your server to a website or forum:

• Sync player ranks between game and site
• Display online players on website
• Integrated donation systems
• Ban lists and appeal systems

Multi-Server Synchronization

Share data across multiple game servers:

• Cross-server chat
• Global economy
• Network-wide bans
• Synchronized player data

Create a shared database and configure all servers to use it.

Accessing via Command Line

Connect to your database using the MySQL client:

mysql -h mysql.example.com -P 3306 -u u1_xK9pL2mQ -p s1_minecraft
Enter password: aB3$kL9mP2qR5vX8

Or with a one-liner:

mysql -h mysql.example.com -P 3306 -u u1_xK9pL2mQ -paB3$kL9mP2qR5vX8 s1_minecraft

Avoid using the password in the command line on shared systems as it may be visible in process lists.

Activity Logging

Database operations are logged:

Example Logs

{
  "event": "server:database.create",
  "properties": {
    "name": "s1_minecraft"
  }
}

{
  "event": "server:database.rotate-password",
  "properties": {
    "name": "s1_minecraft"
  }
}

{
  "event": "server:database.delete",
  "properties": {
    "name": "s1_minecraft"
  }
}

Best Practices

Use Descriptive Names

Name databases based on their purpose: economy, stats, auth, etc. This makes management easier.

Regular Backups

Database backups are separate from server file backups. Use mysqldump or your host’s backup tools:

mysqldump -h mysql.example.com -u u1_xK9pL2mQ -p s1_minecraft > backup.sql

Limit Remote Access

If you don’t need external connections, use localhost for the remote field to improve security.

Monitor Connection Usage

Some database hosts limit concurrent connections. Monitor your plugins’ connection pool settings.

Troubleshooting

Cannot Connect to Database

• Verify host and port are correct
• Check remote access configuration
• Ensure password is correct (try rotating)
• Verify firewall allows MySQL port (3306)
• Check database host is online

Access Denied Errors

• Confirm username and password
• Check remote field allows your IP
• Verify database exists on the host
• Check database host allows external connections

Too Many Connections

• Reduce plugin connection pool sizes
• Enable connection pooling
• Contact host to increase limit
• Check for connection leaks in plugins

Database Limit Reached

You’ve hit the maximum databases for your server. Options:

• Delete unused databases
• Request limit increase from admin
• Consolidate data into fewer databases