Database Mode

Overview

VaultLeaderboards operates in two modes: Local Mode (default) and Database Mode. Local mode works out-of-the-box with no configuration. Database mode adds MySQL support for cross-server sync and balance history tracking.

Local Mode

Local mode is the default. No database configuration is required — the plugin reads balances from all online and offline players on the single server using Vault.

Leaderboard data is kept in memory and refreshed on the configured interval (default 60 seconds). The plugin queries Economy.getBalance(OfflinePlayer) for offline players.

Database Mode

When database mode is enabled, VaultLeaderboards connects to a MySQL database and syncs all player balances. This enables:

Cross-server synchronized leaderboards across multiple servers, balance history tracking for time-based "top earner" queries, and persistent data that survives plugin restarts.

The plugin uses HikariCP for efficient connection pooling. Two tables are created: vl_balances for current balances and vl_balance_history for historical changes.

Balance History

When database mode is enabled, VaultLeaderboards automatically records balance changes in the vl_balance_history table. Each record tracks:

The player UUID, old balance, new balance, change amount, and timestamp. This data powers the topearner PlaceholderAPI placeholders.

Records older than 30 days are automatically purged to keep the database lean.

Cross-Server Sync

In database mode, balances are synced to MySQL on a configurable interval (default 30 seconds). When a player joins, their current Vault balance is immediately synced.

Use /vl sync to force a manual synchronization at any time.

Configuration