Database Configuration

Pterodactyl Panel requires a MySQL (8.0+) or MariaDB (10.2+) database to store panel data.

Basic Configuration

Database Connection

.env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl
DB_PASSWORD=your_secure_password

DB_CONNECTION

string

default:"mysql"

Database driver to use. Options: mysql, mariadb

Both drivers work with MySQL and MariaDB. The mariadb driver enables MariaDB-specific optimizations.

DB_HOST

string

default:"127.0.0.1"

Database server hostname or IP address.

DB_PORT

integer

default:"3306"

Database server port.

DB_DATABASE

string

default:"panel"

Name of the database to use.

DB_USERNAME

string

default:"pterodactyl"

Database user with access to the panel database.

DB_PASSWORD

string

required

Database user password.

Use a strong, randomly generated password for production environments.

Advanced Configuration

Unix Socket Connection

For local databases, Unix sockets provide better performance than TCP:

.env

DB_HOST=localhost
DB_SOCKET=/var/run/mysqld/mysqld.sock

DB_SOCKET

string

Path to MySQL/MariaDB Unix socket file. When set, this takes precedence over DB_HOST and DB_PORT.

Database URL

Alternatively, use a database URL for configuration:

.env

DB_URL=mysql://pterodactyl:[email protected]:3306/panel

DB_URL

string

Full database connection URL. Overrides individual connection parameters.

Character Set & Collation

.env

DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

DB_CHARSET

string

default:"utf8mb4"

Character set for database connections.

Do not change this unless you know what you’re doing. utf8mb4 is required for full Unicode support.

DB_COLLATION

string

default:"utf8mb4_unicode_ci"

Collation for character comparisons and sorting.

Table Prefix

.env

DB_PREFIX=ptdl_

DB_PREFIX

string

Prefix for all database tables. Useful when sharing a database with other applications.

Timezone Configuration

.env

DB_TIMEZONE=+00:00

DB_TIMEZONE

string

MySQL timezone offset. Automatically calculated from APP_TIMEZONE if not set.

The Panel automatically converts APP_TIMEZONE to a MySQL-compatible offset.

Strict Mode

.env

DB_STRICT_MODE=false

DB_STRICT_MODE

boolean

default:"false"

Enable MySQL strict mode for stricter SQL validation.

Currently defaults to false for compatibility. Future versions may default to true.

SSL/TLS Configuration

Secure your database connection with SSL/TLS encryption.

Basic SSL

.env

DB_SSLMODE=require

DB_SSLMODE

string

default:"prefer"

SSL connection mode. Options:

prefer - Use SSL if available, otherwise unencrypted
require - Require SSL connection
verify-ca - Require SSL and verify CA certificate
verify-full - Require SSL and verify certificate identity

Advanced SSL Configuration

For certificate-based authentication:

.env

DB_SSLMODE=verify-ca
MYSQL_ATTR_SSL_CA=/path/to/ca-cert.pem
MYSQL_ATTR_SSL_CERT=/path/to/client-cert.pem
MYSQL_ATTR_SSL_KEY=/path/to/client-key.pem
MYSQL_ATTR_SSL_VERIFY_SERVER_CERT=true

MYSQL_ATTR_SSL_CA

string

Path to Certificate Authority (CA) certificate file.

MYSQL_ATTR_SSL_CERT

string

Path to client certificate file.

MYSQL_ATTR_SSL_KEY

string

Path to client private key file.

MYSQL_ATTR_SSL_VERIFY_SERVER_CERT

boolean

default:"true"

Verify the server’s SSL certificate.

Only disable for testing with self-signed certificates. Always enable in production.

Database Setup

Creating the Database

Log into MySQL/MariaDB:
```
mysql -u root -p
```

Create the database and user:

CREATE DATABASE panel;
CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;

Running Migrations

After configuring the database connection, run migrations:

php artisan migrate --seed --force

The --seed flag populates the database with default data, and --force is required in production.

Remote Database Configuration

Connecting to Remote MySQL/MariaDB

.env

DB_HOST=db.example.com
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl
DB_PASSWORD=your_secure_password
DB_SSLMODE=require

Always use SSL/TLS when connecting to remote databases to encrypt traffic.

Firewall Configuration

Ensure your database server allows connections from the Panel server:

# On the database server (Ubuntu/Debian)
ufw allow from PANEL_IP to any port 3306

MySQL User Permissions

For remote connections, create the user with the Panel server’s IP:

CREATE USER 'pterodactyl'@'PANEL_IP' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'PANEL_IP';
FLUSH PRIVILEGES;

Performance Optimization

Connection Pooling

Laravel automatically manages connection pooling. No additional configuration needed.

Query Optimization

Enable query logging during development to identify slow queries:

php artisan db:monitor --max=100

Testing the Connection

Verify your database connection:

php artisan migrate:status

This command will fail if the database connection is misconfigured.

Connection Test Script

php artisan tinker

DB::connection()->getPdo();
// Should return: PDO object

DB::select('SELECT VERSION()');
// Should return: MySQL/MariaDB version

Troubleshooting

Connection Refused

Possible causes:

MySQL/MariaDB service is not running
Incorrect DB_HOST or DB_PORT
Firewall blocking connections

Solutions:

# Check if MySQL is running
systemctl status mysql

# Verify port is listening
netstat -tlnp | grep 3306

# Test connection
mysql -h 127.0.0.1 -u pterodactyl -p

Access Denied for User

Possible causes:

Incorrect username or password
User doesn’t have permissions for the database
User host restriction mismatch

Solutions:

-- Check user exists
SELECT User, Host FROM mysql.user WHERE User = 'pterodactyl';

-- Grant permissions
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
FLUSH PRIVILEGES;

SSL Connection Error

Possible causes:

MySQL not configured for SSL
Invalid certificate paths
Certificate verification failures

Solutions:

# Check MySQL SSL status
mysql -u root -p -e "SHOW VARIABLES LIKE '%ssl%';"

# Verify certificate files exist and are readable
ls -l /path/to/ssl/certs/

# Test SSL connection manually
mysql -h db.example.com -u pterodactyl -p --ssl-mode=REQUIRED

Character Set Issues

Symptoms:

Emoji or special characters not displaying correctly
Database errors related to character encoding

Solution:

-- Check database charset
SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME 
FROM information_schema.SCHEMATA 
WHERE SCHEMA_NAME = 'panel';

-- Convert database to utf8mb4
ALTER DATABASE panel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Security Best Practices

Strong Passwords

Use randomly generated passwords with at least 32 characters for database users.

Restrict User Access

Grant database users only the permissions they need, and restrict by host.

Use SSL/TLS

Enable SSL/TLS for all database connections, especially for remote databases.

Regular Backups

Implement automated database backups with point-in-time recovery capabilities.

Supported Database Versions

Minimum Requirements:

MySQL 8.0 or higher
MariaDB 10.2 or higher

Recommended:

MySQL 8.0.34+
MariaDB 10.11+ (LTS)

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

Basic Configuration

Database Connection

Advanced Configuration

Unix Socket Connection

Database URL

Character Set & Collation

Table Prefix

Timezone Configuration

Strict Mode

SSL/TLS Configuration

Basic SSL

Advanced SSL Configuration

Database Setup

Creating the Database

Running Migrations

Remote Database Configuration

Connecting to Remote MySQL/MariaDB

Firewall Configuration

MySQL User Permissions

Performance Optimization

Connection Pooling

Query Optimization

Testing the Connection

Connection Test Script

Troubleshooting

Security Best Practices

Strong Passwords

Restrict User Access

Use SSL/TLS

Regular Backups

Supported Database Versions

Build docs developers (and LLMs) love

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Basic Configuration

​Database Connection

​Advanced Configuration

​Unix Socket Connection

​Database URL

​Character Set & Collation

​Table Prefix

​Timezone Configuration

​Strict Mode

​SSL/TLS Configuration

​Basic SSL

​Advanced SSL Configuration

​Database Setup

​Creating the Database

​Running Migrations

​Remote Database Configuration

​Connecting to Remote MySQL/MariaDB

​Firewall Configuration

​MySQL User Permissions

​Performance Optimization

​Connection Pooling

​Query Optimization

​Testing the Connection

​Connection Test Script

​Troubleshooting

​Security Best Practices

Strong Passwords

Restrict User Access

Use SSL/TLS

Regular Backups

​Supported Database Versions

Build docs developers (and LLMs) love

Basic Configuration

Database Connection

Advanced Configuration

Unix Socket Connection

Database URL

Character Set & Collation

Table Prefix

Timezone Configuration

Strict Mode

SSL/TLS Configuration

Basic SSL

Advanced SSL Configuration

Database Setup

Creating the Database

Running Migrations

Remote Database Configuration

Connecting to Remote MySQL/MariaDB

Firewall Configuration

MySQL User Permissions

Performance Optimization

Connection Pooling

Query Optimization

Testing the Connection

Connection Test Script

Troubleshooting

Security Best Practices

Supported Database Versions