Installation

1. Prerequisites

Before dropping the JAR, make sure these are in place:

AstralCore installed and configured on every server (plugin.yml depend). AstralCore supplies configuration loading, commands, placeholders, the RabbitMQ connection, and the database plumbing AstralEconomy runs on.
AstralHud installed on every server (plugin.yml depend). AstralEconomy wraps its action-bar balance-change notification in an AstralHud background before sending it — see Overview: Action-bar notifications.
A reachable MariaDB / MySQL instance. This is the sole money-safety authority for every balance — see Overview.

2. Drop the JAR

Copy AstralEconomy-<version>.jar into plugins/ on every server that should read or write balances, and start the server once.

On first start the plugin generates:

plugins/AstralEconomy/
├── config.yml          ← cache and ledger-cleanup tuning
├── currencies.yml      ← currency definitions
├── messages.yml        ← player-facing strings
└── database.properties ← JDBC config (copied from the JAR)

3. Configure `database.properties`

Key	Description
`jdbcUrl`	JDBC connection string, e.g. `jdbc:mariadb://host:3306/economy?useSSL=false`.
`driverClassName`	`org.mariadb.jdbc.Driver`.
`dataSource.user`/`dataSource.password`	Database credentials.
`poolName`	HikariCP pool name shown in logs; ships as `AstralEconomy`.

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

The shipped file also carries prepared-statement caching and MariaDB-specific performance flags (dataSource.cachePrepStmts, dataSource.rewriteBatchedStatements, …) — leave these as-is unless you have a specific reason to change them.

4. Schema

The schema is created automatically from schema.sql the first time AstralEconomy connects — there is no manual SQL to run. Both statements are CREATE TABLE IF NOT EXISTS, so this is safe to run again on every boot and across every server sharing the database.

Table	Engine	Purpose
`accounts`	InnoDB	One row per `(id, currency)` — the player or town's balance for that currency. Primary key `(id, currency)`.
`transactions`	InnoDB	Append-only ledger: one row per applied mutation (`delta`, `balance_after`, acting `server_id`). Indexed on `(account_id, currency, created_at)` and `created_at`.

See Overview: Ledger & history for how the ledger is written and pruned.

5. Size the connection pool

database.properties ships with:

maximumPoolSize=16
minimumIdle=8
connectionTimeout=5000
idleTimeout=600000
keepaliveTime=300000
maxLifetime=1800000

Balance reads are served from the in-memory cache — only writes hold a connection, and only for a few milliseconds — so 16 connections comfortably absorbs bursts (e.g. an admin payout hitting every online player at once) without exhausting the pool. minimumIdle (8) is kept below maximumPoolSize so a quiet server holds a small baseline and only grows to 16 under load.

6. Multi-server setup

Point every server's database.properties at the same database — this is what makes balances consistent network-wide. AstralEconomy does not ship its own RabbitMQ configuration: cross-server cache invalidation (economy.balance) and action-bar notification hints (economy.notify) ride on the RabbitMQ connection AstralCore is already configured with on that server (AstralPaperAPI.credentialsProvider()), so there is nothing extra to set up as long as AstralCore's own messaging is configured. See Overview: Cross-server model.

7. Define a default currency

/pay, /balance with no argument, and every no-currency SPI/API call resolve to whichever currency in currencies.yml is marked default: true. The shipped currencies.yml already marks default as the default currency — if you replace it, make sure exactly one currency keeps default: true, or those commands will report that no default currency is configured. See Currencies.

8. Verify

Reload the configuration and confirm the plugin can read a balance:

/eco reload
/balance

/eco reload requires economy.command (the command's base permission) plus economy.command.reload. /balance has no permission requirement by default. A successful /balance reply confirms the database connection, the default currency, and the cache are all working end to end.

Where to go next

Configuration — config.yml cache and ledger-cleanup tuning.
Currencies — the full currencies.yml shape.
Commands — /eco, /pay, /balance in full, with every permission node.

Last modified: 25 July 2026