MariaDB

Deploy and manage MariaDB databases on Dokploy

MariaDB is a MySQL-compatible relational database that provides enhanced features, better performance, and additional storage engines. It’s a drop-in replacement for MySQL created by the original MySQL developers.

Creating a MariaDB Database

1. Navigate to Databases

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

2. Configure Basic Settings

   Provide the basic information:

   • Name: Display name for your database
   • App Name: Internal DNS name (e.g., mariadb-prod)
   • Description: Optional notes
   • Docker Image: MariaDB version (default: mariadb:6)
3. Set Credentials

   MariaDB requires both root and user credentials:

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

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

4. Deploy

   Click Create to deploy. Dokploy will:

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

Connection Information

Internal Connection

Applications in the same environment connect via internal DNS:

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

Connection String Examples:

# MySQL protocol
mysql://appuser:password@mariadb-prod:3306/myapp

# MariaDB client
mariadb -h mariadb-prod -P 3306 -u appuser -p myapp

# MySQL client (compatible)
mysql -h mariadb-prod -P 3306 -u appuser -p myapp

External Connection

Enable external access:

1. Navigate to Settings > External Port
2. Set an external port (e.g., 33061)
3. Click Save to redeploy

Connection String Examples:

# MySQL protocol
mysql://appuser:[e-mail]:33061/myapp

# MariaDB client
mariadb -h your-server.com -P 33061 -u appuser -p myapp

Secure external connections with firewalls and strong passwords.

Root Access

Administrative operations use root credentials:

# Internal root connection
mariadb -h mariadb-prod -P 3306 -u root -p

# External root connection
mariadb -h your-server.com -P 33061 -u root -p

Use root access only for database administration and user management.

Configuration

Environment Variables

Customize MariaDB with environment variables:

# Connection settings
MARIADB_MAX_CONNECTIONS=150
MARIADB_CONNECT_TIMEOUT=10
MARIADB_WAIT_TIMEOUT=28800

# InnoDB configuration
MARIADB_INNODB_BUFFER_POOL_SIZE=512M
MARIADB_INNODB_LOG_FILE_SIZE=128M
MARIADB_INNODB_FLUSH_LOG_AT_TRX_COMMIT=1
MARIADB_INNODB_FLUSH_METHOD=O_DIRECT

# Performance tuning
MARIADB_QUERY_CACHE_SIZE=32M
MARIADB_QUERY_CACHE_TYPE=1
MARIADB_TABLE_OPEN_CACHE=2000
MARIADB_THREAD_CACHE_SIZE=8

# Logging
MARIADB_SLOW_QUERY_LOG=1
MARIADB_LONG_QUERY_TIME=2
MARIADB_LOG_QUERIES_NOT_USING_INDEXES=1

# Character set (UTF-8)
MARIADB_CHARACTER_SET_SERVER=utf8mb4
MARIADB_COLLATION_SERVER=utf8mb4_unicode_ci

# Binary logging
MARIADB_LOG_BIN=mysql-bin
MARIADB_BINLOG_FORMAT=ROW
MARIADB_EXPIRE_LOGS_DAYS=7

# Timezone
TZ=America/New_York

Resource Allocation

Recommended resources by workload:

Workload	Memory Reservation	Memory Limit	CPU Reservation	CPU Limit
Development	128MB	256MB	0.1	0.25
Small Application	256MB	512MB	0.25	0.5
Production	512MB	2GB	0.5	1.0
High Performance	1GB	4GB	1.0	2.0

Docker Image Versions

MariaDB version options:

# Latest major versions
mariadb:6           # Latest MariaDB 6.x (default)
mariadb:11          # MariaDB 11.x (latest stable)
mariadb:10.11       # MariaDB 10.11 LTS
mariadb:10.6        # MariaDB 10.6 LTS

# Specific versions
mariadb:11.2.2
mariadb:10.11.6

# Variants
mariadb:11-jammy    # Ubuntu 22.04 base

MariaDB uses a different versioning scheme than MySQL. Version 10.x is compatible with MySQL 5.x/8.x.

Database Operations

Lifecycle Management

Start/Stop

Control database availability:

Start: Brings database online

• Status changes to done
• Accepts connections
• Loads from persistent volume

Stop: Graceful shutdown

• Status changes to idle
• Closes all connections
• Data persists in volume
• No resource consumption

Reload

Restart MariaDB to apply changes:

1. Click Reload in dashboard
2. MariaDB stops gracefully
3. Container restarts
4. New configuration loads
5. Database comes online

Use reload for:

• Environment variable changes
• Resource limit updates
• Configuration troubleshooting

Rebuild

Completely rebuild the container:

1. Navigate to Settings > Rebuild
2. Confirm rebuild
3. Container destroyed and recreated
4. Data volume preserved
5. Database restarts

Rebuild causes downtime. Plan accordingly.

Volume Management

MariaDB stores data in a Docker volume:

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

Volume contents:

• Database files (.ibd, .frm)
• InnoDB tablespace
• Aria storage engine files
• Binary logs
• Configuration

Backup Configuration

See Database Backups for automated backup setup.

Advanced Configuration

Custom Startup Configuration

Command:

mariadbd

Arguments:

--max-connections=200
--innodb-buffer-pool-size=1G
--innodb-log-file-size=256M
--character-set-server=utf8mb4
--collation-server=utf8mb4_unicode_ci
--binlog-format=ROW

Health Check Setup

Monitor and auto-recover MariaDB:

{
  "test": ["CMD-SHELL", "healthcheck.sh --connect --innodb_initialized"],
  "interval": 30000000000,
  "timeout": 5000000000,
  "retries": 3
}

Restart Policy

Automatic restart configuration:

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

MariaDB-Specific Features

MariaDB includes features not available in MySQL:

Storage Engines

Additional storage engines:

• Aria: Crash-safe MyISAM replacement
• ColumnStore: Columnar storage for analytics
• Spider: Sharding and partitioning
• Connect: Access external data sources

JSON Support

Enhanced JSON capabilities:

-- Native JSON type (MariaDB 10.2+)
CREATE TABLE data (
  id INT PRIMARY KEY,
  info JSON
);

-- JSON functions
SELECT JSON_VALUE(info, '$.name') FROM data;
SELECT JSON_QUERY(info, '$.items') FROM data;

Temporal Tables

Built-in time travel queries:

-- System-versioned table
CREATE TABLE products (
  id INT PRIMARY KEY,
  name VARCHAR(100),
  price DECIMAL(10,2)
) WITH SYSTEM VERSIONING;

-- Query historical data
SELECT * FROM products
  FOR SYSTEM_TIME AS OF '2024-01-01';

Common Use Cases

Web Application

Standard MariaDB for web apps:

Docker Image: mariadb:11
Memory Limit: 512MB
CPU Limit: 0.5

# Environment
MARIADB_MAX_CONNECTIONS=100
MARIADB_INNODB_BUFFER_POOL_SIZE=256M
MARIADB_CHARACTER_SET_SERVER=utf8mb4
MARIADB_COLLATION_SERVER=utf8mb4_unicode_ci

Analytics

Optimized for read-heavy workloads:

Docker Image: mariadb:11
Memory Limit: 4GB
CPU Limit: 2.0

# Environment
MARIADB_INNODB_BUFFER_POOL_SIZE=2G
MARIADB_QUERY_CACHE_SIZE=128M
MARIADB_TABLE_OPEN_CACHE=4000
MARIADB_READ_BUFFER_SIZE=2M

Replication Source

Master database for replication:

Docker Image: mariadb:11
Memory Limit: 2GB
CPU Limit: 1.0

# Environment
MARIADB_LOG_BIN=mysql-bin
MARIADB_BINLOG_FORMAT=ROW
MARIADB_SERVER_ID=1
MARIADB_GTID_STRICT_MODE=1

Monitoring and Logs

View MariaDB logs in real-time:

1. Open your MariaDB service
2. Navigate to Logs tab
3. Monitor activity and errors

Common log messages:

# Successful startup
mariadbd: ready for connections
Version: '11.2.2-MariaDB'  socket: '/run/mysqld/mysqld.sock'  port: 3306

# Connection
Connect: user@172.x.x.x on myapp using TCP/IP

# Slow query
Query_time: 3.456789  Lock_time: 0.000123
SELECT * FROM users WHERE ...

Troubleshooting

Initialization failed

Check logs for initialization errors:

Common issues:

• Invalid password format (special characters)
• Insufficient disk space
• Corrupted existing data directory
• Permission issues on volume

Resolution:

1. Verify password meets requirements
2. Check available disk space
3. Delete and recreate if needed

Cannot connect

Verify connection configuration:

• Host: Use app name internally
• Port: 3306 internal, custom external
• Status: Must be done
• Network: Same environment for internal

Test connectivity:

# Internal test
telnet mariadb-prod 3306

# External test
telnet your-server.com 33061

Performance issues

Optimize MariaDB configuration:

1. Increase memory:

   MARIADB_INNODB_BUFFER_POOL_SIZE=1G
   

2. Enable query cache:

   MARIADB_QUERY_CACHE_SIZE=64M
   MARIADB_QUERY_CACHE_TYPE=1
   

3. Tune table cache:

   MARIADB_TABLE_OPEN_CACHE=4000
   

4. Check slow queries:

   MARIADB_SLOW_QUERY_LOG=1
   MARIADB_LONG_QUERY_TIME=1
   

Out of memory

Reduce memory usage:

1. Increase container memory limit
2. Reduce buffer pool:
   MARIADB_INNODB_BUFFER_POOL_SIZE=256M
   
3. Limit connections:
   MARIADB_MAX_CONNECTIONS=50
   
4. Disable query cache:
   MARIADB_QUERY_CACHE_TYPE=0
   

Migration

From MySQL to MariaDB

MariaDB is generally compatible with MySQL:

1. Backup MySQL data using mysqldump
2. Create MariaDB database in Dokploy
3. Restore data to MariaDB
4. Update connection strings in applications
5. Test thoroughly for compatibility

Compatibility notes:

• Most MySQL features work unchanged
• Authentication differences in newer versions
• Some optimizer behaviors differ
• Extended features available in MariaDB

Version Upgrades

Upgrade MariaDB versions:

1. Backup database (important!)
2. Update Docker image version
3. Redeploy database
4. Verify operation and data integrity
5. Run mysql_upgrade if needed

Always backup before upgrading. Test upgrades in development first.

Next Steps

Setup Backups

Configure automated MariaDB backups

MongoDB

Deploy a MongoDB database