MySQL

Deploy and manage MySQL databases on Dokploy

MySQL is one of the world’s most popular open-source relational database management systems, trusted for web applications and data-driven solutions.

Creating a MySQL Database

1. Navigate to Databases

   In your Dokploy dashboard, select your environment and click Add Database > MySQL.

2. Configure Basic Settings

   Fill in the required information:

   • Name: Display name for the database
   • App Name: Internal DNS name (e.g., mysql-app)
   • Description: Optional notes
   • Docker Image: MySQL version (default: mysql:8)
3. Set Database Credentials

   MySQL requires both root and application credentials:

   Database Name: myapp
   Database User: appuser
   Database Password: <strong-password>
   Root Password: <strong-root-password>
   

   Passwords cannot contain: $ ! ' " \ / or spaces

   The root password is used for administrative tasks. The database user is for application connections.

4. Deploy

   Click Create to deploy. Dokploy will:

   • Pull the MySQL Docker image
   • Create a volume at /var/lib/mysql
   • Initialize the database with your credentials

Connection Information

Internal Connection

Applications in the same environment use internal DNS:

Host: <app-name>  # e.g., mysql-app
Port: 3306
Database: myapp
Username: appuser
Password: <your-password>

Connection String Example:

mysql://appuser:password@mysql-app:3306/myapp

# Or with MySQL client
mysql -h mysql-app -P 3306 -u appuser -p myapp

External Connection

To enable external access:

1. Go to Settings > External Port
2. Assign a port (e.g., 33060)
3. Click Save and redeploy

Connection String Example:

mysql://appuser:[e-mail]:33060/myapp

# Or with MySQL client
mysql -h your-server.com -P 33060 -u appuser -p myapp

Exposing MySQL externally requires proper firewall configuration and strong passwords.

Root Access

Administrative access uses the root password:

# Internal root connection
mysql -h mysql-app -P 3306 -u root -p

# External root connection (if external port configured)
mysql -h your-server.com -P 33060 -u root -p

Use root access only for database administration, migrations, and user management.

Configuration

Environment Variables

Customize MySQL behavior with environment variables:

# Connection and performance
MYSQL_MAX_CONNECTIONS=150
MYSQL_CONNECT_TIMEOUT=10

# InnoDB settings
MYSQL_INNODB_BUFFER_POOL_SIZE=512M
MYSQL_INNODB_LOG_FILE_SIZE=128M
MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT=1

# Query cache (MySQL 5.7 and earlier)
MYSQL_QUERY_CACHE_SIZE=32M
MYSQL_QUERY_CACHE_TYPE=1

# Logging
MYSQL_LOG_ERROR=/var/log/mysql/error.log
MYSQL_SLOW_QUERY_LOG=1
MYSQL_SLOW_QUERY_LOG_FILE=/var/log/mysql/slow.log
MYSQL_LONG_QUERY_TIME=2

# Character set
MYSQL_CHARACTER_SET_SERVER=utf8mb4
MYSQL_COLLATION_SERVER=utf8mb4_unicode_ci

# Timezone
TZ=America/New_York

Resource Allocation

Workload Type	Memory Reservation	Memory Limit	CPU Reservation	CPU Limit
Development	128MB	256MB	0.1	0.25
Small Production	256MB	512MB	0.25	0.5
Medium Production	512MB	1GB	0.5	1.0
Large Production	1GB	4GB	1.0	2.0

Docker Image Versions

MySQL offers several version options:

# Latest versions
mysql:8           # MySQL 8.x (default)
mysql:8.0         # Latest 8.0.x
mysql:8.0.35      # Specific version

# MySQL 5.7 (older but stable)
mysql:5.7
mysql:5.7.44

# Oracle Linux variants
mysql:8-oracle
mysql:5.7-oracle

Database Operations

Lifecycle Management

Manage your MySQL database through the UI:

Start/Stop

Start: Brings database online (status: done)

# Database starts and accepts connections
# All data persists from previous session

Stop: Gracefully shuts down (status: idle)

# Connections are closed
# Data remains in volume
# No resource usage while stopped

Reload

Restart MySQL to apply configuration changes:

1. Click Reload in the dashboard
2. MySQL stops gracefully
3. Container restarts with new configuration
4. Database comes back online

Use reload when:

• Changing environment variables
• Applying new resource limits
• Troubleshooting connection issues

Rebuild

Completely rebuild the container:

1. Navigate to Settings > Rebuild
2. Confirm rebuild operation
3. Container is destroyed and recreated
4. Data volume remains intact

Rebuild causes downtime. Schedule during maintenance windows.

Move Between Environments

Transfer databases between environments (dev, staging, production):

1. Navigate to database settings
2. Select Move to Environment
3. Choose target environment
4. Confirm the move

Moving updates the environment reference but doesn’t migrate data. Use backups to transfer data.

Volume Management

MySQL data persists in a Docker volume:

Volume Name: {appName}-data
Mount Path: /var/lib/mysql

The volume contains:

• Database files (.ibd, .frm)
• InnoDB tablespace
• Binary logs
• MySQL configuration

Volume Backup

See Database Backups for automated backup configuration.

Advanced Configuration

Custom Startup Options

Override MySQL server startup configuration:

Command:

mysqld

Arguments:

--max-connections=200
--innodb-buffer-pool-size=512M
--innodb-log-file-size=128M
--character-set-server=utf8mb4
--collation-server=utf8mb4_unicode_ci

Health Check Configuration

Ensure MySQL is monitored and auto-recovers:

{
  "test": ["CMD-SHELL", "mysqladmin ping -h localhost"],
  "interval": 30000000000,
  "timeout": 5000000000,
  "retries": 3
}

Restart Policy

Automatic restart on failure:

{
  "condition": "on-failure",
  "delay": 5000000000,
  "maxAttempts": 3
}

Common Use Cases

Web Application

Standard MySQL setup for web apps:

Docker Image: mysql:8
Memory Limit: 512MB
CPU Limit: 0.5

# Environment
MYSQL_MAX_CONNECTIONS=100
MYSQL_INNODB_BUFFER_POOL_SIZE=256M
MYSQL_CHARACTER_SET_SERVER=utf8mb4
MYSQL_COLLATION_SERVER=utf8mb4_unicode_ci

High Performance

Optimized for heavy workloads:

Docker Image: mysql:8
Memory Limit: 4GB
CPU Limit: 2.0

# Environment
MYSQL_MAX_CONNECTIONS=200
MYSQL_INNODB_BUFFER_POOL_SIZE=2G
MYSQL_INNODB_LOG_FILE_SIZE=256M
MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT=2

Development

Minimal resources for testing:

Docker Image: mysql:8
Memory Limit: 256MB
CPU Limit: 0.25

# Basic configuration
# No external access needed
# Use internal DNS for connections

Monitoring and Logs

View MySQL logs in real-time:

1. Navigate to your MySQL service
2. Click Logs tab
3. Monitor database activity

Common log patterns:

# Successful startup
mysqld: ready for connections
Version: '8.0.35'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306

# Connection established
Connection received from 172.x.x.x

# Slow query (if enabled)
Query_time: 2.123456  Lock_time: 0.000123
SELECT * FROM users WHERE ...

Troubleshooting

Database initialization failed

Check container logs for initialization errors:

Common causes:

• Invalid root or database password format
• Insufficient disk space for data directory
• Corrupted volume from previous deployment

Solution:

1. Verify password format (no special characters)
2. Check disk space availability
3. If needed, delete and recreate the database

Connection refused

Verify connection details:

• Host: Use app name for internal, server address for external
• Port: 3306 internal, configured external port
• Status: Ensure database status is done
• Firewall: Check that port is accessible

Test connection:

# Test internal connectivity
telnet mysql-app 3306

# Test external connectivity
telnet your-server.com 33060

Out of memory errors

MySQL exceeding allocated memory:

1. Increase Memory Limit in settings
2. Reduce InnoDB buffer pool:
   MYSQL_INNODB_BUFFER_POOL_SIZE=256M
   
3. Limit connections:
   MYSQL_MAX_CONNECTIONS=50
   
4. Redeploy the database

Slow performance

Optimize MySQL configuration:

1. Increase memory allocation
2. Tune InnoDB settings:
   MYSQL_INNODB_BUFFER_POOL_SIZE=1G
   MYSQL_INNODB_LOG_FILE_SIZE=256M
   MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT=2
   
3. Enable and check slow query log
4. Consider upgrading to SSD storage

Character encoding issues

Set proper character encoding:

MYSQL_CHARACTER_SET_SERVER=utf8mb4
MYSQL_COLLATION_SERVER=utf8mb4_unicode_ci

Redeploy and verify:

SHOW VARIABLES LIKE 'character_set_%';
SHOW VARIABLES LIKE 'collation_%';

Migration from Other Databases

From PostgreSQL

Key differences to consider:

• Auto-increment: Use AUTO_INCREMENT instead of SERIAL
• Boolean: Use TINYINT(1) instead of BOOLEAN
• Schemas: MySQL uses databases instead of schemas
• Case sensitivity: Table names are case-insensitive by default

From MySQL 5.7 to 8.0

Major changes:

• Authentication: MySQL 8 uses caching_sha2_password by default
• Reserved words: New reserved keywords in 8.0
• Performance: Improved query optimizer and indexing
• JSON: Enhanced JSON support and functions

Next Steps

Setup Backups

Configure automated MySQL backups

MariaDB

Learn about MariaDB as MySQL alternative