Database Connections

Configure MongoDB and MySQL database connections for Mythic Framework

Mythic Framework uses a dual-database architecture with MongoDB as the primary database and MySQL for compatibility with legacy resources and relational data needs.

Database Requirements

MongoDB

Version: 3.6.6 or higher Purpose: Primary database for auth, characters, inventory, game data Required: YES

MySQL

Version: 5.7 or higher (MariaDB 10.2+) Purpose: Persistent data, compatibility layer Required: Highly Recommended

MongoDB Configuration

Connection String Format

MongoDB uses a URI connection string format:

mongodb://[username:password@]host[:port]/database[?options]

Basic Connection

No Authentication (Development Only):

# server.cfg
set mongodb_url "mongodb://localhost:27017/mythic"
set mongodb_database "mythic"

Never use no-auth in production! Always enable authentication for security.

Authenticated Connection

With Username/Password (Production):

# server.cfg
set mongodb_url "mongodb://mythic_user:SecurePassword123@localhost:27017/mythic?authSource=admin"
set mongodb_database "mythic"

Connection String Parameters

Parameter	Description	Example
username	Database username	mythic_user
password	Database password	SecurePassword123
host	MongoDB server address	localhost, 192.168.1.100
port	MongoDB port	27017 (default)
database	Database name	mythic
authSource	Authentication database	admin

Common Options

authSource: Where user credentials are stored

?authSource=admin

replicaSet: Replica set name (for clusters)

?replicaSet=myReplica

ssl: Enable SSL/TLS encryption

?ssl=true

retryWrites: Automatic retry for write operations

?retryWrites=true

Multiple options: Separate with &

?authSource=admin&retryWrites=true&ssl=true

Remote MongoDB

Connecting to Remote Server:

set mongodb_url "mongodb://mythic_user:password@192.168.1.100:27017/mythic?authSource=admin"

MongoDB Atlas (Cloud):

set mongodb_url "mongodb+srv://username:[e-mail]/mythic?retryWrites=true&w=majority"

Note: Atlas uses mongodb+srv:// protocol for automatic DNS resolution.

Creating MongoDB User

1. Connect to MongoDB

   mongo
   
2. Switch to Admin Database

   use admin
   
3. Create User

   db.createUser({
     user: "mythic_user",
     pwd: "SecurePassword123",
     roles: [
       { role: "readWrite", db: "mythic" },
       { role: "dbAdmin", db: "mythic" }
     ]
   })
   
4. Verify Connection

   mongo mongodb://mythic_user:SecurePassword123@localhost:27017/mythic?authSource=admin
   

MongoDB Connection Troubleshooting

Connection Refused

Error: MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

Causes:

• MongoDB service not running
• Wrong host/port
• Firewall blocking connection

Solutions:

# Check if MongoDB is running (Linux)
sudo systemctl status mongod

# Start MongoDB (Linux)
sudo systemctl start mongod

# Check if MongoDB is running (Windows)
Get-Service MongoDB

# Verify port is listening
netstat -an | grep 27017

Authentication Failed

Error: MongoError: Authentication failed

Causes:

• Wrong username/password
• User doesn’t exist
• Wrong authSource

Solutions:

• Verify credentials are correct
• Check user exists: db.getUsers() in mongo shell
• Ensure authSource=admin is specified
• Verify user has correct roles:

use admin
db.getUser("mythic_user")

Database Not Found

Error: Database doesn’t exist

Solution: MongoDB creates databases automatically on first write. The database will be created when the framework first inserts data.

Manual Creation (Optional):

use mythic
db.createCollection("init")

Connection Timeout

Error: MongoNetworkError: connection timeout

Causes:

• Firewall blocking port
• MongoDB not bound to correct interface
• Network issues

Solutions:

• Check MongoDB bind address in /etc/mongod.conf:

net:
  bindIp: 0.0.0.0  # Listen on all interfaces
  port: 27017

• Check firewall:

# Allow MongoDB port (Linux)
sudo ufw allow 27017/tcp

MySQL Configuration

Connection String Format

Mythic Framework uses oxmysql which supports standard MySQL connection strings:

mysql://username:password@host:port/database?options

Basic Configuration

Local MySQL Server:

# server.cfg
set mysql_connection_string "mysql://root:password@localhost:3306/mythic?charset=utf8mb4"

Important: Always use charset=utf8mb4 for proper emoji and character support.

Connection String Components

Protocol

mysql:// - Standard MySQL protocol

Always use mysql:// (not mysqli:// or others)

Credentials

username:password@ - Authentication

Example: root:MyPassword123@

Host & Port

host:port - Server address

Default port: 3306

Examples:

• localhost:3306
• 192.168.1.100:3306
• db.example.com:3306

Database & Options

/database?options - Database name and settings

Example: /mythic?charset=utf8mb4

Common Connection Options

# Basic with charset
mysql://user:pass@localhost/mythic?charset=utf8mb4

# With connection pooling
mysql://user:pass@localhost/mythic?charset=utf8mb4&connectionLimit=10

# With timeout settings
mysql://user:pass@localhost/mythic?charset=utf8mb4&connectTimeout=10000

# Complete example with all options
mysql://user:pass@localhost/mythic?charset=utf8mb4&connectionLimit=10&connectTimeout=10000&acquireTimeout=10000&debug=false

Connection Options Explained

Option	Description	Default	Recommended
charset	Character encoding	utf8	utf8mb4
connectionLimit	Max concurrent connections	10	10-20
connectTimeout	Connection timeout (ms)	10000	10000
acquireTimeout	Query timeout (ms)	10000	10000
waitForConnections	Wait if pool is full	true	true
queueLimit	Max queued connections	0	0 (unlimited)
debug	Debug SQL queries	false	false (prod)

Creating MySQL Database and User

Command Line

# Login to MySQL
mysql -u root -p

# Create database
CREATE DATABASE mythic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Create user
CREATE USER 'mythic_user'@'localhost' IDENTIFIED BY 'SecurePassword123';

# Grant permissions
GRANT ALL PRIVILEGES ON mythic.* TO 'mythic_user'@'localhost';

# Apply changes
FLUSH PRIVILEGES;

# Verify
SHOW GRANTS FOR 'mythic_user'@'localhost';

phpMyAdmin

1. Create Database

   1. Click “Databases” tab
   2. Enter database name: mythic
   3. Select collation: utf8mb4_unicode_ci
   4. Click “Create”
2. Create User

   1. Click “User accounts” tab
   2. Click “Add user account”
   3. Enter username: mythic_user
   4. Select host: localhost
   5. Enter password
   6. Under “Database for user account”:
      • Select “Grant all privileges on database mythic”
   7. Click “Go”

Remote MySQL Connection

Connecting to Remote Server:

# server.cfg
set mysql_connection_string "mysql://mythic_user:password@192.168.1.100:3306/mythic?charset=utf8mb4"

Allow Remote Connections (MySQL Server):

# Edit MySQL config (Linux: /etc/mysql/mysql.conf.d/mysqld.cnf)
[mysqld]
bind-address = 0.0.0.0  # Listen on all interfaces

# Restart MySQL
sudo systemctl restart mysql

# Create user for remote access
mysql -u root -p
CREATE USER 'mythic_user'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON mythic.* TO 'mythic_user'@'%';
FLUSH PRIVILEGES;

# Allow port through firewall
sudo ufw allow 3306/tcp

Security Warning: Exposing MySQL to the internet is risky. Use:

• Strong passwords
• SSH tunneling for remote access
• VPN connections
• Whitelist specific IPs only

MySQL Connection Troubleshooting

Access Denied

Error: Access denied for user 'username'@'host'

Solutions:

• Verify username and password are correct
• Check user exists and has correct permissions:

SELECT User, Host FROM mysql.user WHERE User='mythic_user';
SHOW GRANTS FOR 'mythic_user'@'localhost';

• Ensure password special characters are URL-encoded:

# Password: My$ecure@Pass
# Encoded: My%24ecure%40Pass
mysql://user:My%24ecure%40Pass@localhost/mythic

Unknown Database

Error: Unknown database 'mythic'

Solution:

• Database doesn’t exist, create it:

CREATE DATABASE mythic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

• Verify database name matches connection string exactly

Connection Timeout

Error: Connection timeout

Causes:

• MySQL not running
• Wrong host/port
• Firewall blocking
• Network issues

Solutions:

# Check MySQL is running (Linux)
sudo systemctl status mysql

# Check port is open
netstat -tulpn | grep 3306

# Test connection
mysql -h localhost -u mythic_user -p

# Increase timeout in connection string
?connectTimeout=30000

Too Many Connections

Error: Too many connections

Solution:

• Increase MySQL max connections:

SET GLOBAL max_connections = 200;

• Or edit /etc/mysql/mysql.conf.d/mysqld.cnf:

[mysqld]
max_connections = 200

• Reduce connectionLimit in oxmysql:

?connectionLimit=5

Testing Database Connections

Test MongoDB Connection

Linux/Mac

mongo "mongodb://mythic_user:password@localhost:27017/mythic?authSource=admin"

Test MySQL Connection

Command Line

mysql -h localhost -u mythic_user -p mythic

Connection String Security

Never commit database credentials to version control!

Best Practices

1. Use Environment Variables

   # .env file (add to .gitignore)
   MONGODB_URL=mongodb://user:pass@localhost:27017/mythic?authSource=admin
   MYSQL_URL=mysql://user:pass@localhost:3306/mythic?charset=utf8mb4
   

   # server.cfg references variables
   set mongodb_url "${MONGODB_URL}"
   set mysql_connection_string "${MYSQL_URL}"
   
2. Use Strong Passwords

   • Minimum 16 characters
   • Mix of uppercase, lowercase, numbers, symbols
   • No dictionary words
   • Use password manager to generate
3. Limit Access

   • Create separate database users for different environments
   • Grant minimum required privileges
   • Use localhost when possible instead of %
   • Enable MySQL bind-address restrictions
4. Enable Encryption

   MongoDB SSL/TLS:

   mongodb://user:pass@host/db?ssl=true&authSource=admin
   

   MySQL SSL:

   mysql://user:pass@host/db?ssl={"rejectUnauthorized":true}
   

Production Checklist

1. MongoDB

   ✅ Authentication enabled ✅ Strong password set ✅ User has minimum required permissions ✅ Connection string includes authSource ✅ Database firewall rules configured ✅ SSL/TLS enabled (if remote) ✅ Regular backups configured

2. MySQL

   ✅ Root login disabled for remote connections ✅ Strong password set ✅ User limited to specific database ✅ utf8mb4 charset used ✅ Connection pooling configured ✅ Firewall rules in place ✅ Regular backups configured

3. server.cfg

   ✅ Connection strings not committed to git ✅ Credentials stored securely ✅ Connection timeouts configured ✅ Debug mode disabled in production ✅ Connection limits appropriate for server load

Next Steps

Server Configuration

Complete server.cfg settings guide

Database Architecture

Learn how Mythic uses databases

Resource Management

Configure resource load order

Troubleshooting

Common database issues and fixes