Configuration

plugins/AstralEconomy/ holds three files: config.yml (cache tuning and ledger pruning), currencies.yml (the currency catalogue — see Currencies), and database.properties (the JDBC/HikariCP connection pool). All three are loaded on startup and re-read by /eco reload. messages.yml (the message-key catalogue) is also reloaded at the same time — see Messages.

Both config.yml and currencies.yml are parsed with Configurate: a camelCase Java field maps to a kebab-case YAML key (readTtl → read-ttl, maxSize → max-size), and Duration fields accept shorthand like 5s, 6h, or 14d.

`config.yml`

cache:
  # How long a balance read is cached in memory before re-reading the database. A balance changed on
  # another server becomes visible here within this window (a fanout hint usually refreshes sooner).
  read-ttl: 5s
  # Maximum number of cached account entries. Online players are pinned in the cache, so this must stay
  # comfortably above peak (online players × currencies) — otherwise size pressure from offline lookups
  # could evict a pinned entry and make a cached balance read fall back to zero for an online player.
  max-size: 500000

cleanup:
  # Periodically delete transaction (ledger) history older than `retention`. This prunes only the audit
  # trail — account balances are never affected. Set `enabled: false` to keep history forever.
  enabled: true
  # How long to keep a transaction before it is eligible for pruning.
  retention: 14d
  # How often the prune runs. The delete executes off the main thread.
  interval: 6h

`cache`

Field	Type	Default	Description
`read-ttl`	Duration	`5s`	How long an unpinned (offline-lookup) balance read stays cached before the next read re-queries the database.
`max-size`	int	`500000`	Ceiling on cached account entries. Online players (and, for `EconomyAPI`, registered towns) are pinned — they carry cache weight `0` and never TTL-expire or count against this ceiling — so `max-size` bounds only the transient offline-lookup population. It must stay comfortably above peak `online players × currencies`; a non-positive or absent value falls back to the built-in default.

See Reads: an in-memory cache, DB on miss for how pinning and eviction interact at runtime. If the entire cache section is omitted, both fields fall back to their built-in defaults — same mechanism as cleanup below.

`cleanup`

Field	Type	Default	Description
`enabled`	boolean	`true`	Turns the periodic ledger prune on or off. `false` keeps every transaction row forever.
`retention`	Duration	`14d`	Transactions older than this, relative to the moment the task runs, become eligible for deletion.
`interval`	Duration	`6h`	How often the prune task runs, scheduled on the async scheduler. The delete itself executes off the main thread via `TransactionCleanupTask`, so it never blocks the server.

This only prunes rows in transactions (the audit ledger) — accounts balances are never touched. The first run fires one minute after boot (to skip the startup rush), then every interval after that. A failed run is logged and simply retried on the next interval rather than throwing.

Defaults when the section is absent. If cleanup is missing from config.yml entirely (e.g. a config predating this feature), AstralEconomy applies the same built-in defaults shown above — enabled: true, 14-day retention pruned every 6 hours — so existing deployments start getting history pruning without any config edit. To disable pruning you must add the section explicitly with enabled: false; there is no key that means "absent = disabled."

See Ledger & history for what gets written to transactions in the first place.

`currencies.yml`

The currency catalogue — display name, symbol, starting balance, transferable flag, and the default currency flag. It is loaded alongside config.yml on startup and on every /eco reload. See Currencies for the full key reference and the shipped defaults.

`database.properties`

A standard HikariCP/JDBC properties file, copied from the JAR the first time the plugin starts (an existing file on disk is never overwritten). AstralEconomy's shipped file is tuned for a shared MariaDB instance:

jdbcUrl=jdbc:mariadb://localhost:3306/economy?useSSL=false
driverClassName=org.mariadb.jdbc.Driver
dataSource.user=testuser
dataSource.password=test623
poolName=AstralEconomy

# Connection pool settings
maximumPoolSize=16
minimumIdle=8
connectionTimeout=5000
idleTimeout=600000
keepaliveTime=300000
maxLifetime=1800000

# Performance tuning
dataSource.cachePrepStmts=true
dataSource.prepStmtCacheSize=250
dataSource.prepStmtCacheSqlLimit=2048
dataSource.useServerPrepStmts=true
dataSource.useLocalSessionState=true
dataSource.rewriteBatchedStatements=true
dataSource.cacheResultSetMetadata=true
dataSource.cacheServerConfiguration=true
dataSource.elideSetAutoCommits=true
dataSource.maintainTimeStats=false

For the base connection keys (jdbcUrl, driverClassName, dataSource.user/password, poolName) and the lifecycle keys (connectionTimeout, idleTimeout, maxLifetime), see the AstralCore database docs — AstralEconomy reuses the same DatabaseService. Two settings not covered there:

Key	Default	Description
`keepaliveTime`	`300000` (5 min)	How often HikariCP pings an idle connection to keep it alive through firewalls/proxies that drop long-idle TCP connections.
`maximumPoolSize`/`minimumIdle`	`16`/`8`	Balance reads almost never touch the database (they're served from the cache described above); only writes hold a connection, briefly. `16` absorbs a fan-out burst (e.g. an admin payout to every online player at once) without exhausting the pool. `minimumIdle` is kept below `maximumPoolSize` so a quiet server holds a small baseline (`8`) and only grows to `16` under load.

Shared-database sizing note. Every server in the fleet opens its own pool against the same MariaDB instance, so total connections are roughly maximumPoolSize × server count, plus whatever other plugins use. Keep the database's max_connections comfortably above that sum — MariaDB's default of 151 fits 16 × 8 servers with headroom, but a larger fleet must raise it.

Performance flags. DatabaseService applies the dataSource.* performance flags shown above (prepared statement caching, rewriteBatchedStatements, server-side prepared statements, etc.) as defaults whenever a key is not present in database.properties — AstralEconomy's shipped file simply sets them explicitly at those same defaults. Overriding any of them (e.g. setting dataSource.rewriteBatchedStatements=false) takes effect on the next full restart, since the pool is only rebuilt on onEnable/onDisable, not on /eco reload.

Reloading

/eco reload (economy.command.reload) calls the same loadConfiguration() used on startup, which re-reads config.yml, currencies.yml, and messages.yml in that order and replaces the in-memory configuration objects. database.properties is not part of this — the connection pool is only built once, in onEnable, so pool/JDBC changes require a full restart. See Commands for the command surface and Messages for the reloading/reload-success/reload-failure feedback strings.

Last modified: 25 July 2026