Administration

Administration and maintenance

Wiki home · Player commands · Get help

Monitor readiness, maintain consistent backups, and investigate storage or payment incidents.

This wiki documents Civilizations 1.0.1. Numbers are bundled defaults; in-game menus and previews show your server’s current values.

On this page: Readiness and database failures · Useful operator checks · Back up the whole game state · Upgrade and rollback · Interrupted payments and plot-tax incidents · Ongoing checks

Readiness and database failures

MySQL is authoritative. The plugin uses an in-memory snapshot for quick claim and membership lookups, applies normal mutations transactionally, and refreshes the cache after changes and periodically.

On startup, unknown territory is protected until the database has connected, migrations have succeeded, and the cache is loaded. State-changing commands are refused during that period. After a later database outage, the last successfully loaded snapshot remains available to protect known claims, while mutations are locked until recovery. Read-only information may be stale.

The default database retry interval is 30 seconds. Restore connectivity and wait for readiness. Disabling Civilizations or allowing unknown territory as wilderness removes the protection boundary rather than fixing storage.

Useful operator checks

/civ admin migrate
/civ admin invariants
/civ admin inspect civ River Kingdom
/civ admin inspect claim
/civ admin inspect player Alex
/civ admin help
/civ admin audit action=admin. page=1 size=50

Use /civ admin help for the exact available admin syntax. Schema reports and invariant scans are read-only. Inspections compare persisted and cached state. The audit filters support civilization, actor, action prefix, target, date range, page, and page size.

Review previews before force-claiming, changing roles, granting resources, or overriding campaigns. Repairs require the additional permissions in the administrator command table. They are recorded in the audit log; bypass nodes are explicit permissions, not ordinary leader abilities.

Back up the whole game state

For a consistent restore point, stop the server cleanly and back up:

1. The Civilizations MySQL schema.
2. All Minecraft worlds, including world UUID files and player data. Player data contains physical items, the /wild cooldown, and pending first placement.
3. The complete plugins/Civilizations/ directory, including religion.yml, customized catalogs, and catalog upgrade backups.
4. The Vault economy provider's data/database and any other gameplay-critical plugin data.
5. The exact plugin JAR, server version, and configuration used with the backup.

An example InnoDB dump, run from a private backup directory, is:

mysqldump \
  --host=127.0.0.1 \
  --user=civilizations \
  --password \
  --single-transaction \
  --quick \
  --hex-blob \
  --no-tablespaces \
  --set-gtid-purged=OFF \
  civilizations > civilizations-YYYYMMDD-HHMMSS.sql

Use an actual timestamp in the output name. --password prompts without including the password in the command itself. Binary UUID columns need lossless backup handling; --hex-blob provides it. Consult the MySQL dump reference for your database/server configuration.

Keep backups outside the public repository and copy them to separate storage. Regularly restore a backup into an isolated test environment to verify it. A mismatched world, economy balance store, and civilization database can produce incorrect ownership or payment state even when each individual backup file is readable.

Upgrade and rollback

1. Read CHANGELOG.md and check your current schema/invariants.
2. Stop the Minecraft server and take a matching backup of all state above.
3. Replace the plugin JAR and review any documented configuration/catalog changes.
4. Start in maintenance mode. Startup applies missing ordered migrations and checks existing checksums.
5. Wait for cache readiness, then run /civ admin migrate and /civ admin invariants.
6. Inspect customized catalogs after any automatic version upgrade and complete a gameplay smoke test before reopening.

Migrations are forward-only. Never edit an already-applied migration or change schema_history to silence a checksum error. Returning to an older JAR may require restoring its matching database, plugin files, worlds, and economy data. Prefer restoring into a separate empty schema/environment while investigating a failed update.

For 1.0.1, the expected schema version is 8. V7 adds persistent deity favor; V8 caps older favor levels above 3. Existing sacrifice cooldowns remain intact. The religion catalog upgrade changes Demeter's wheat offering to bread while retaining other customized settings and saving a backup. Follow the 1.0.1 upgrade checks.

The detailed operations runbook contains database provisioning, monitoring, restoration, cache recovery, economy reconciliation, and war-cleanup procedures.

Interrupted payments and plot-tax incidents

Ordinary payment operations are recorded in economy_operations. Tax billing additionally uses civ_plot_taxes, plot_tax_accounts, and plot_tax_bills from migration V6.

Recovery automatically retries operations whose persisted state proves retrying is safe. WITHDRAWAL_IN_FLIGHT, DELIVERY_IN_FLIGHT, and REFUND_IN_FLIGHT mean an external call may have happened without a conclusive recorded result. Vault has no portable transaction lookup/idempotency mechanism to settle that ambiguity automatically.

For an unresolved operation, inspect the audit/ledger records and the economy provider's history before any manual reconciliation. Do not reset it to pending, repeat a charge, or mark it completed just to remove a warning. Tax operations are handled by the tax worker, not the generic recovery worker; ambiguous tax calls preserve ownership while unresolved. Follow the tax operations procedure.

Ongoing checks

Keep clocks synchronized and monitor database/cache failures, stale economy operations, invariant warnings, and campaign transition/temporary-block cleanup errors. Run manual invariants after a restore, an administrator repair, or a payment incident. Maintain regular backups and verify free disk space for world generation, database logs, and backup retention.

---

Continue reading: Administrator command reference · Operations runbook · Server troubleshooting