MariaDB

​

Creating a MariaDB Database

1. Navigate to your project
2. Select the environment
3. Click “Add Service” and select “MariaDB”
4. Configure the database settings

​

Basic Configuration

• Name - A friendly name for your database
• App Name - The Docker service name (used for internal DNS)
• Description - Optional description
• Docker Image - Default: mariadb:latest (recommended: mariadb:11 or mariadb:10.11)

​

Database Credentials

• Database Name - Name of the database to create
• Database User - Username for database access
• Database Password - Password for the user
• Root Password - Password for the root user

​

Advanced Settings

• External Port - Optional port to expose MariaDB externally (default internal port: 3306)
• Command - Override the default container command
• Args - Additional arguments to pass to MariaDB
• Environment Variables - Additional custom environment variables

​

Connection Strings

​

Internal Connection (from other services)

mysql://[user]:[password]@[appName]:3306/[database]

mysql://myuser:mypassword@my-mariadb:3306/myapp

​

External Connection

mysql://[user]:[password]@[host]:[externalPort]/[database]

​

Connection String Formats

mysql://username:password@hostname:3306/database

mariadb -h hostname -P 3306 -u username -p database
# or use mysql command (compatible)
mysql -h hostname -P 3306 -u username -p database

const mysql = require('mysql2');

const connection = mysql.createConnection({
  host: 'my-mariadb',
  port: 3306,
  user: 'myuser',
  password: 'mypassword',
  database: 'myapp'
});

import mysql.connector

conn = mysql.connector.connect(
    host="my-mariadb",
    port=3306,
    user="myuser",
    password="mypassword",
    database="myapp"
)

<?php
$conn = new mysqli(
    "my-mariadb",
    "myuser",
    "mypassword",
    "myapp",
    3306
);
?>

​

Environment Variables

​

Data Persistence

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

​

Resource Configuration

Memory Limit: 2GB        # Maximum memory
Memory Reservation: 1GB   # Guaranteed memory
CPU Limit: 2.0           # Maximum CPU cores
CPU Reservation: 0.5     # Guaranteed CPU cores

​

Operations

​

Starting the Database

POST /api/mariadb/start
{
  "mariadbId": "your-mariadb-id"
}

​

Stopping the Database

POST /api/mariadb/stop
{
  "mariadbId": "your-mariadb-id"
}

​

Reloading the Database

POST /api/mariadb/reload
{
  "mariadbId": "your-mariadb-id"
}

​

Rebuilding the Database

POST /api/mariadb/rebuild
{
  "mariadbId": "your-mariadb-id"
}

​

Accessing MariaDB CLI

docker exec -it $(docker ps -qf "name=my-mariadb") mariadb -u myuser -p myapp

docker exec -it $(docker ps -qf "name=my-mariadb") mysql -u myuser -p myapp

​

Common MariaDB Commands

-- List all databases
SHOW DATABASES;

-- Select database
USE database_name;

-- List all tables
SHOW TABLES;

-- Describe table structure
DESCRIBE table_name;

-- Show current user
SELECT USER();

-- Show current database
SELECT DATABASE();

-- Show MariaDB version
SELECT VERSION();

-- Create database
CREATE DATABASE new_database;

-- Create user
CREATE USER 'new_user'@'%' IDENTIFIED BY 'password';

-- Grant privileges
GRANT ALL PRIVILEGES ON myapp.* TO 'myuser'@'%';
FLUSH PRIVILEGES;

​

MariaDB-Specific Features

​

1. Better Performance

• Improved query optimizer
• Faster replication
• Better thread pool implementation

​

2. Additional Storage Engines

• Aria - Crash-safe MyISAM replacement
• ColumnStore - Columnar storage for analytics
• Spider - Sharding and partitioning

​

3. Enhanced JSON Support

-- Create table with JSON column
CREATE TABLE users (
  id INT PRIMARY KEY,
  metadata JSON
);

-- Query JSON data
SELECT JSON_VALUE(metadata, '$.name') FROM users;

​

4. Temporal Tables

CREATE TABLE employees (
  id INT PRIMARY KEY,
  name VARCHAR(100),
  salary DECIMAL(10,2)
) WITH SYSTEM VERSIONING;

​

Backups

mariadb-dump -u username -p database > backup.sql

​

Troubleshooting

​

Connection Refused

• Verify the service is running in Dokploy UI
• Check the service name matches your appName
• Ensure your application is in the same Docker network

​

Authentication Failed

• Verify credentials in the database settings
• Check user has proper host permissions (% or specific IP)
• Verify MARIADB_ environment variables are set correctly

​

Migration from MySQL

1. Test thoroughly before production migration
2. Check for MySQL-specific features not in MariaDB
3. Review version compatibility (e.g., MariaDB 10.6 ≈ MySQL 8.0)
4. Use mariadb-upgrade after migration

​

Best Practices

1. Use Specific Versions - Pin to specific MariaDB versions (e.g., mariadb:10.11.6) instead of latest
2. Strong Passwords - Use strong, randomly generated passwords for production
3. Regular Backups - Configure automated backups and test restoration
4. Monitor Resources - Watch memory and CPU usage, adjust limits as needed
5. Security - Don’t expose MariaDB externally unless necessary
6. Upgrade Path - Plan upgrades carefully; test in staging first
7. Connection Pooling - Use connection pooling in your applications

​

Performance Tuning

# InnoDB buffer pool (50-70% of memory)
innodb_buffer_pool_size=1G

# Thread pool (MariaDB feature)
thread_handling=pool-of-threads
thread_pool_size=8

# Max connections
max_connections=150

# Query cache (deprecated in recent versions)
query_cache_type=0

# Aria storage engine settings
aria_pagecache_buffer_size=128M

​

MariaDB vs MySQL

​

Next Steps