MariaDB Setup

MariaDB is a MySQL-compatible relational database — open source, fast, and featured. Witchly runs MariaDB 11.8, the current long-term-support branch. If you’ve ever used MySQL, you already know MariaDB.

When to use a dedicated MariaDB server

• You want a database you control end-to-end (backups, tuning, versioning).
• You need a DB shared across multiple Witchly servers (apps, bots, game servers).
• You’re running a Minecraft/Rust plugin or Discord bot that persists data.

Tip: If you only need a database for a single server, use the built-in Databases tab on your game/app server — Witchly provisions one in seconds. A standalone MariaDB server is worthwhile when multiple clients need to share it.

Deploying

1. dash.witchly.host → Deploy → Applications → MariaDB.
2. Storage-heavy workloads benefit from The Daemon or The Orchestrator.
3. Click Deploy.

First-run

The install script initializes the data directory and sets a default root password from the egg. Change it immediately on first login:

1. Open the Console tab and wait for ready for connections.
2. Open the Files tab or SFTP in and note the MARIADB_ROOT_PASSWORD from the initial setup log.
3. Connect via CLI (next section) and run:

ALTER USER 'root'@'%' IDENTIFIED BY 'your-new-strong-password';
FLUSH PRIVILEGES;

Connecting

Get your server’s IP and port from the Overview tab, then:

# From any Linux/macOS machine
mariadb -h your-server-ip.witchly.host -P 12345 -u root -p

Or from an application:

// Node.js — mysql2
import mysql from "mysql2/promise"
const conn = await mysql.createConnection({
  host: "your-server-ip.witchly.host",
  port: 12345,
  user: "your-user",
  password: "your-password",
  database: "your-db",
})

# Python — PyMySQL
import pymysql
conn = pymysql.connect(
    host="your-server-ip.witchly.host",
    port=12345,
    user="your-user",
    password="your-password",
    database="your-db",
)

Creating databases and users

Best practice: never let your app connect as root. Create a dedicated user per app:

CREATE DATABASE myapp_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'myapp'@'%' IDENTIFIED BY 'strong-password-here';
GRANT ALL PRIVILEGES ON myapp_prod.* TO 'myapp'@'%';
FLUSH PRIVILEGES;

The '%' host means the user can log in from anywhere. If you know your app’s source IP, lock it down: 'myapp'@'1.2.3.4'.

Backups

Use mysqldump for logical backups:

mariadb-dump -h your-server-ip.witchly.host -P 12345 \
  -u root -p --single-transaction --routines --triggers \
  --all-databases > backup.sql

Schedule this via a cron on another server, or enable Pterodactyl’s built-in Backups tab — which snapshots the entire data directory.

Tuning

MariaDB config lives in /home/container/my.cnf. Key settings:

[mysqld]
max_connections = 100
innodb_buffer_pool_size = 512M   # Set to ~70% of your plan's RAM
innodb_log_file_size = 128M
character-set-server = utf8mb4

Reinstall or restart after edits.

Troubleshooting

• “Access denied” — double-check the user host pattern. 'user'@'localhost' ≠ 'user'@'%'.
• “Too many connections” — raise max_connections in my.cnf, but verify the bottleneck isn’t elsewhere (long-running queries, missing connection pooling).
• Slow queries — EXPLAIN <query>; add indexes; enable the slow query log.

Next steps

• Redis alongside for caching
• Subusers to give teammates panel access without the root password