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.

linked_accounts

Stores the Minecraft ↔ Discord account mappings.

Column	Type	Description
uuid	VARCHAR(36)	Minecraft player UUID
minecraft_username	VARCHAR(16)	Minecraft player name
discord_id	VARCHAR(20)	Discord user snowflake ID
discord_username	VARCHAR(64)	Discord username at time of link
server_name	VARCHAR(64)	Server where the link occurred
linked_at	TIMESTAMP	When the link was created

verification_codes

Temporary codes for the linking flow.

Column	Type	Description
uuid	VARCHAR(36)	Minecraft player UUID
code	VARCHAR(6)	6-digit verification code
expires_at	TIMESTAMP	Expiry time

boost_cooldowns

Tracks when each player last claimed their boost reward.

Column	Type	Description
uuid	VARCHAR(36)	Minecraft player UUID
server_name	VARCHAR(64)	Server (for per-server mode)
last_claim	TIMESTAMP	Last claim time

level_data

Stores Discord XP and level information.

Column	Type	Description
discord_id	VARCHAR(20)	Discord user ID
text_xp	INT	Total text XP earned
voice_xp	INT	Total voice XP earned
text_level	INT	Current text level
voice_level	INT	Current voice level
claimed_rewards	TEXT	JSON list of claimed level rewards

Audit Tables

link_events, boost_claims, rank_syncs, chat_logs, and join_leave_logs 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.