MySQL Database Expansion

Overview

The MySQL Database Expansion connects multiple EssentialsC server instances through a shared MySQL database, which acts as the authoritative network store. It is distributed as its own JAR (named EssentialsC-MySQLExpansion) and declares a hard dependency on EssentialsC; if EssentialsC is missing or disabled, the expansion refuses to load.

Balance synchronisation is the implemented channel. Online players' balances are diffed and pushed to the network store on a short timer, offline players' balances are mirrored in both directions, and the local EssentialsC economy can be kept in step with the network so /balance and /baltop reflect balances earned on other servers.

Installation

The expansion is a standard Bukkit plugin JAR that depends on EssentialsC being loaded first.

Configuration

All settings live in /plugins/EssentialsC-MySQLExpansion/config.yml. A default file is generated on first run.

mysql:
  host: localhost
  port: 3306
  database: essc_test_01
  username: root
  password: 'minecraft'

  # Table prefix so multiple networks can share one database safely.
  table-prefix: 'essc_test_01'

  pool:
    maximum-pool-size: 10
    minimum-idle: 2
    connection-timeout-ms: 30000
    idle-timeout-ms: 600000
    max-lifetime-ms: 1800000
    properties:
      useSSL: false
      autoReconnect: true
      characterEncoding: UTF-8

# Unique identifier for this server. Blank = generated automatically.
server-id: 'survival-01'

debug: true

sync:
  economy:
    enabled: true
    pull-on-join: true
    push-on-quit: true
    push-interval-seconds: 2
    sync-local: true
    mirror-interval-seconds: 5
    baltop-page-size: 10

Economy Sync

The economy sync engine treats MySQL as the authoritative network store. Two background tasks keep the network and local economies in step.

Push Cycle (default every 2 seconds)

The push task iterates every player currently online on this server and compares their current local balance to the last value pushed to MySQL. If the balance has changed, the new value is written to the network table. EssentialsC does not expose a balance-change event, so changes are detected by diffing on this timer – a small interval means other servers see earnings almost immediately without the player having to join them.

Mirror Cycle (default every 5 seconds)

When sync.economy.sync-local is enabled, the mirror task fetches all network balances and reconciles them with local data for players who are not online on this server. If the local balance diverges from the last known network value, the local economy is updated so EssentialsC's own /balance and /baltop reflect network balances for players who never joined this server.

Join & Quit Handling

When a player joins, the expansion pulls their network balance and applies it locally if one exists, otherwise it keeps the local value. When a player quits, their final local balance is pushed to the network store immediately. On shutdown, every online player's balance is flushed to MySQL before the connection is closed.

Commands

Permissions

Database Schema

The expansion creates a single table, named <table-prefix>network_balances, on first connection. It is created with CREATE TABLE IF NOT EXISTS – no manual schema setup is required. Balance values are stored as DECIMAL(20,2).

CREATE TABLE IF NOT EXISTS `<prefix>network_balances` (
  `uuid`         CHAR(36)      NOT NULL,
  `username`     VARCHAR(64)   NOT NULL,
  `balance`      DECIMAL(20,2) NOT NULL DEFAULT 0.00,
  `server_id`    VARCHAR(64)   NOT NULL,
  `last_updated` BIGINT       NOT NULL,
  PRIMARY KEY (`uuid`)
)

Writes use INSERT ... ON DUPLICATE KEY UPDATE, so each player has exactly one row keyed by their UUID.