Database

Database Setup

uxmDiscordSync supports five database backends. The type is set in config.yml under the database section.

---

Supported Backends

Type	Use Case
flatfile	Default. No setup. Stores data as JSON files.
sqlite	Lightweight single-file SQL. Good for small servers.
mysql	Production-ready. Supports multiple servers sharing data.
mariadb	Drop-in MySQL replacement with better performance.
postgresql	Enterprise-grade. Best for high-traffic deployments.

---

Flatfile (Default)

No configuration needed. Data is stored as JSON files inside the plugin data folder. Suitable for testing and small servers that do not need shared data across multiple server instances.

database:
  type: flatfile

---

SQLite

A single .db file is created in the plugin folder. Better than flatfile for structured queries.

database:
  type: sqlite
  sqlite:
    file: "uxmdiscordsync.db"

---

MySQL / MariaDB

Recommended for production servers and multi-server setups.

database:
  type: mysql        # or "mariadb"
  mysql:
    host: "localhost"
    port: 3306
    database: "uxmdiscordsync"
    username: "root"
    password: "yourpassword"
    ssl: false
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000    # ms
      idle-timeout: 600000         # ms
      max-lifetime: 1800000        # ms
      keepalive-time: 60000        # ms

Creating the Database

CREATE DATABASE uxmdiscordsync CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'uxmds'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON uxmdiscordsync.* TO 'uxmds'@'localhost';
FLUSH PRIVILEGES;

---

PostgreSQL

database:
  type: postgresql
  postgresql:
    host: "localhost"
    port: 5432
    database: "uxmdiscordsync"
    username: "postgres"
    password: "yourpassword"
    ssl: false
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

Creating the Database

CREATE DATABASE uxmdiscordsync;
CREATE USER uxmds WITH PASSWORD 'yourpassword';
GRANT ALL PRIVILEGES ON DATABASE uxmdiscordsync TO uxmds;

---

Database Schema

The plugin creates and manages these tables automatically on first start.

uxm_linked_accounts

Stores the Minecraft ↔ Discord account mappings.

Column	Type	Description
minecraft_uuid	TEXT	Minecraft player UUID (primary key)
minecraft_username	TEXT	Minecraft player name
discord_id	TEXT	Discord user snowflake ID (unique)
discord_username	TEXT	Discord username at time of link
server	TEXT	Server where the link occurred
linked_at	INTEGER	When the link was created (epoch ms)

uxm_verification_codes

Temporary codes for the linking flow.

Column	Type	Description
code	TEXT	6-digit verification code (primary key)
minecraft_uuid	TEXT	Minecraft player UUID
expires_at	INTEGER	Expiry time (epoch ms)

uxm_boost_cooldowns

Tracks boost reward expiry per player.

Column	Type	Description
minecraft_uuid	TEXT	Minecraft player UUID
server	TEXT	Server (for per-server mode)
expires_at	INTEGER	Cooldown expiry time (epoch ms)

uxm_level_data

Stores Discord XP and level information.

Column	Type	Description
discord_id	TEXT	Discord user ID (primary key)
text_xp	INTEGER	Total text XP earned
voice_xp	INTEGER	Total voice XP earned
text_level	INTEGER	Current text level
voice_level	INTEGER	Current voice level
claimed_text_rewards	TEXT	JSON list of claimed text level rewards
claimed_voice_rewards	TEXT	JSON list of claimed voice level rewards

Audit Tables

uxm_link_events, uxm_boost_claims, and uxm_rank_sync store historical records for each major event. These are append-only and used for the logging system.

---

Multi-Server Shared Database

When running multiple Paper servers, point all of them at the same MySQL/PostgreSQL database. This enables:

• A player linked on Server A is automatically linked on Server B
• Shared boost cooldowns (if cooldown-mode is set to global)
• Shared level data

See Multi-Server Support for the full guide.

---

Connection Pooling (HikariCP)

MySQL, MariaDB, and PostgreSQL use HikariCP for connection pooling. Tuning guidelines:

Setting	Default	Notes
maximum-pool-size	10	Increase for servers with 100+ concurrent players
minimum-idle	2	Keep at least 2 connections warm
connection-timeout	30000 ms	Time to wait for a free connection
idle-timeout	600000 ms	Close idle connections after this
max-lifetime	1800000 ms	Maximum connection lifetime before refresh
keepalive-time	60000 ms	Ping idle connections to keep them alive

Tip: For most servers, the defaults are fine. Only tune maximum-pool-size if you see connection-wait warnings in the logs.