Skip to main content
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

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
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
);
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
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

Name databases based on their purpose: economy, stats, auth, etc. This makes management easier.
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
If you don’t need external connections, use localhost for the remote field to improve security.
Some database hosts limit concurrent connections. Monitor your plugins’ connection pool settings.

​
Troubleshooting

  • 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
  • Confirm username and password
  • Check remote field allows your IP
  • Verify database exists on the host
  • Check database host allows external connections
  • Reduce plugin connection pool sizes
  • Enable connection pooling
  • Contact host to increase limit
  • Check for connection leaks in plugins
You’ve hit the maximum databases for your server. Options:
  • Delete unused databases
  • Request limit increase from admin
  • Consolidate data into fewer databases

Build docs developers (and LLMs) love

Get started for freeTalk to us