> ## Documentation Index
> Fetch the complete documentation index at: https://mythicframework.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Connections

> Configure MongoDB and MySQL database connections for Mythic Framework

Mythic Framework uses a dual-database architecture: **two MongoDB databases** (Auth and Game) plus **MySQL** via oxmysql.

## Database Requirements

<CardGroup cols={2}>
  <Card title="MongoDB" icon="leaf">
    **Version:** 3.6.6 or higher
    **Purpose:** Primary database — two separate databases for auth and game data
    **Required:** YES
  </Card>

  <Card title="MySQL" icon="database">
    **Version:** 5.7 or higher (MariaDB 10.2+)
    **Purpose:** Inventory persistence, compatibility layer
    **Required:** YES
  </Card>
</CardGroup>

## MongoDB Configuration

Mythic requires **4 separate convars** for two MongoDB databases:

| Convar                  | Purpose                   | Example Value                   |
| ----------------------- | ------------------------- | ------------------------------- |
| `mongodb_auth_url`      | Auth DB connection string | `mongodb://localhost:27017/...` |
| `mongodb_auth_database` | Auth DB name              | `auth`                          |
| `mongodb_game_url`      | Game DB connection string | `mongodb://localhost:27017/...` |
| `mongodb_game_database` | Game DB name              | `fivem`                         |

<Warning>
  **Two separate MongoDB databases are required.** The `auth` database stores accounts and bans. The `fivem` database stores characters, vehicles, inventory, properties, and all game data.
</Warning>

### Basic Connection (Development)

```bash theme={null}
# server.cfg — MongoDB Auth Database
set mongodb_auth_url "mongodb://localhost:27017/?readPreference=primary&ssl=false"
set mongodb_auth_database "auth"

# server.cfg — MongoDB Game Database
set mongodb_game_url "mongodb://localhost:27017/?readPreference=primary&ssl=false"
set mongodb_game_database "fivem"
```

### Authenticated Connection (Production)

```bash theme={null}
# server.cfg — MongoDB Auth Database
set mongodb_auth_url "mongodb://mythic_user:SecurePassword123@localhost:27017/?authSource=admin&readPreference=primary"
set mongodb_auth_database "auth"

# server.cfg — MongoDB Game Database
set mongodb_game_url "mongodb://mythic_user:SecurePassword123@localhost:27017/?authSource=admin&readPreference=primary"
set mongodb_game_database "fivem"
```

<Note>
  Both databases can share the same MongoDB server and credentials — they are just different database names within the same MongoDB instance.
</Note>

<AccordionGroup>
  <Accordion title="Connection String Parameters" icon="gear">
    | 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)            |
    | `authSource`     | Authentication database | `admin`                      |
    | `readPreference` | Read preference         | `primary`                    |
    | `ssl`            | Enable SSL/TLS          | `true` or `false`            |
  </Accordion>

  <Accordion title="Remote & Cloud MongoDB" icon="cloud">
    **Remote Server:**

    ```bash theme={null}
    set mongodb_auth_url "mongodb://mythic_user:password@192.168.1.100:27017/?authSource=admin"
    set mongodb_game_url "mongodb://mythic_user:password@192.168.1.100:27017/?authSource=admin"
    ```

    **MongoDB Atlas (Cloud):**

    ```bash theme={null}
    set mongodb_auth_url "mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority"
    set mongodb_game_url "mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority"
    ```

    Atlas uses `mongodb+srv://` protocol for automatic DNS resolution. The database name is set separately via the `mongodb_auth_database` and `mongodb_game_database` convars.
  </Accordion>
</AccordionGroup>

### What Each Database Stores

<Tabs>
  <Tab title="Auth Database">
    Database name: `auth`

    | Collection | Data                                |
    | ---------- | ----------------------------------- |
    | `accounts` | Player accounts, identifiers, roles |
    | `bans`     | Ban records                         |
  </Tab>

  <Tab title="Game Database">
    Database name: `fivem`

    | Collection      | Data                                    |
    | --------------- | --------------------------------------- |
    | `characters`    | Character data (name, appearance, etc.) |
    | `vehicles`      | Owned vehicles                          |
    | `properties`    | Housing/properties                      |
    | `bank_accounts` | Bank account balances                   |
    | `mdt_reports`   | Police MDT reports                      |
    | `phone_*`       | Phone data (contacts, messages, etc.)   |
  </Tab>
</Tabs>

### Creating MongoDB User

<Steps>
  <Step title="Connect to MongoDB">
    ```bash theme={null}
    mongo
    ```
  </Step>

  <Step title="Switch to Admin Database">
    ```javascript theme={null}
    use admin
    ```
  </Step>

  <Step title="Create User with Access to Both Databases">
    ```javascript theme={null}
    db.createUser({
      user: "mythic_user",
      pwd: "SecurePassword123",
      roles: [
        { role: "readWrite", db: "auth" },
        { role: "dbAdmin", db: "auth" },
        { role: "readWrite", db: "fivem" },
        { role: "dbAdmin", db: "fivem" }
      ]
    })
    ```
  </Step>

  <Step title="Verify Connection">
    ```bash theme={null}
    mongo "mongodb://mythic_user:SecurePassword123@localhost:27017/?authSource=admin"
    ```
  </Step>
</Steps>

### MongoDB Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused" icon="xmark">
    **Error:** `MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017`

    **Solutions:**

    ```bash theme={null}
    # Check if MongoDB is running (Linux)
    sudo systemctl status mongod
    sudo systemctl start mongod

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

    # Verify port is listening
    netstat -an | grep 27017
    ```
  </Accordion>

  <Accordion title="Authentication Failed" icon="key">
    **Error:** `MongoError: Authentication failed`

    **Solutions:**

    * Verify credentials are correct
    * Ensure `authSource=admin` is in the connection string
    * Verify user has roles for both `auth` and `fivem` databases:

    ```javascript theme={null}
    use admin
    db.getUser("mythic_user")
    ```
  </Accordion>

  <Accordion title="Database Not Found" icon="database">
    MongoDB creates databases automatically on first write. The `auth` and `fivem` databases will be created when the framework first starts and inserts data.
  </Accordion>
</AccordionGroup>

## MySQL Configuration

### Connection String

Mythic uses oxmysql with a standard MySQL connection string:

```bash theme={null}
# server.cfg
set mysql_connection_string "mysql://root@localhost/MythicFramework?charset=utf8mb4"
set mysql_slow_query_warning 300
```

<Note>
  The default database name is `MythicFramework`. Always use `charset=utf8mb4` for proper character support.
</Note>

### Connection String Components

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

| Component  | Description                                   | Example                      |
| ---------- | --------------------------------------------- | ---------------------------- |
| `username` | MySQL user                                    | `root`, `mythic_user`        |
| `password` | MySQL password (optional for root\@localhost) | `SecurePassword123`          |
| `host`     | MySQL server                                  | `localhost`, `192.168.1.100` |
| `port`     | MySQL port (default 3306, can be omitted)     | `3306`                       |
| `database` | Database name                                 | `MythicFramework`            |

### Common Configurations

```bash theme={null}
# Local development (root, no password)
set mysql_connection_string "mysql://root@localhost/MythicFramework?charset=utf8mb4"

# Local with password
set mysql_connection_string "mysql://mythic_user:password@localhost/MythicFramework?charset=utf8mb4"

# Remote server
set mysql_connection_string "mysql://mythic_user:password@192.168.1.100:3306/MythicFramework?charset=utf8mb4"
```

### Slow Query Warning

oxmysql can warn you about slow queries:

```bash theme={null}
# Warn for queries taking longer than 300ms
set mysql_slow_query_warning 300
```

### Creating MySQL Database and User

<Tabs>
  <Tab title="Command Line">
    ```sql theme={null}
    -- Login to MySQL
    -- mysql -u root -p

    -- Create database
    CREATE DATABASE MythicFramework CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    -- Create user (production)
    CREATE USER 'mythic_user'@'localhost' IDENTIFIED BY 'SecurePassword123';

    -- Grant permissions
    GRANT ALL PRIVILEGES ON MythicFramework.* TO 'mythic_user'@'localhost';

    -- Apply changes
    FLUSH PRIVILEGES;
    ```
  </Tab>

  <Tab title="phpMyAdmin">
    <Steps>
      <Step title="Create Database">
        1. Click "Databases" tab
        2. Enter database name: `MythicFramework`
        3. Select collation: `utf8mb4_unicode_ci`
        4. Click "Create"
      </Step>

      <Step title="Create User">
        1. Click "User accounts" tab
        2. Click "Add user account"
        3. Enter username and password
        4. Under "Database for user account": select "Grant all privileges on database MythicFramework"
        5. Click "Go"
      </Step>
    </Steps>
  </Tab>
</Tabs>

### MySQL Troubleshooting

<AccordionGroup>
  <Accordion title="Access Denied" icon="ban">
    **Error:** `Access denied for user 'username'@'host'`

    * Verify username and password
    * Check user exists: `SELECT User, Host FROM mysql.user;`
    * URL-encode special characters in passwords:

    ```bash theme={null}
    # Password: My$ecure@Pass → My%24ecure%40Pass
    mysql://user:My%24ecure%40Pass@localhost/MythicFramework
    ```
  </Accordion>

  <Accordion title="Unknown Database" icon="circle-question">
    **Error:** `Unknown database 'MythicFramework'`

    Create it:

    ```sql theme={null}
    CREATE DATABASE MythicFramework CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    ```
  </Accordion>

  <Accordion title="Too Many Connections" icon="users-slash">
    Increase MySQL max connections:

    ```sql theme={null}
    SET GLOBAL max_connections = 200;
    ```

    Or reduce oxmysql connection limit in the connection string:

    ```bash theme={null}
    ?charset=utf8mb4&connectionLimit=5
    ```
  </Accordion>
</AccordionGroup>

## Complete server.cfg Example

```bash theme={null}
# === MONGODB (Auth Database — accounts, bans) ===
set mongodb_auth_url "mongodb://localhost:27017/?readPreference=primary&ssl=false"
set mongodb_auth_database "auth"

# === MONGODB (Game Database — characters, vehicles, inventory, etc.) ===
set mongodb_game_url "mongodb://localhost:27017/?readPreference=primary&ssl=false"
set mongodb_game_database "fivem"

# === MYSQL (oxmysql — inventory persistence) ===
set mysql_connection_string "mysql://root@localhost/MythicFramework?charset=utf8mb4"
set mysql_slow_query_warning 300
```

## Production Checklist

<Steps>
  <Step title="MongoDB">
    * Authentication enabled with strong password
    * User has readWrite + dbAdmin roles on both `auth` and `fivem`
    * Connection strings include `authSource=admin`
    * Firewall configured (port 27017)
    * Regular backups configured
  </Step>

  <Step title="MySQL">
    * Strong password set (not root with no password)
    * User limited to `MythicFramework` database
    * `utf8mb4` charset used
    * Firewall configured (port 3306)
    * Regular backups configured
  </Step>

  <Step title="server.cfg">
    * All 4 MongoDB convars set
    * MySQL connection string configured
    * Credentials not committed to git
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Server Configuration" icon="server" href="/configuration/server-cfg">
    Complete server.cfg settings guide
  </Card>

  <Card title="Database Architecture" icon="diagram-project" href="/concepts/database-architecture">
    Learn how Mythic uses databases internally
  </Card>

  <Card title="Resource Management" icon="boxes-stacked" href="/configuration/resource-management">
    Configure resource load order
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/installation/troubleshooting">
    Common setup issues and fixes
  </Card>
</CardGroup>