Database & storage#

VonixGuardian stores its audit log in a relational database. SQLite is the default and needs no setup; MySQL, MariaDB, and PostgreSQL are supported for larger servers.

Choosing a backend#

Rough guidance: if /vg status shows a rising queue depth with a healthy backend, storage is your bottleneck and a remote database will help. If the queue is flat and drops are zero, SQLite is already sufficient regardless of player count.

The bundled SQLite driver ships nested inside the jar on every loader, so a SQLite install needs nothing beyond the jar. MySQL and PostgreSQL drivers are also nested — no separate library install is required.

Where the data lives#

Also on disk, beside the database:

<server root>/
├── vonixguardian.db                       audit data (SQLite)
├── config/vonixguardian/config.json       configuration
├── config/vonixguardian/worlds/           per-world overrides
├── config/vonixguardian/queue-quarantine.bin  durable quarantine outbox
├── logs/vonixguardian/audit-YYYY-MM-DD.log.jsonl  rolling log file
└── blacklist.txt                          optional suppression rules

Schema#

Current schema version: 9. Migrations are additive and idempotent — they run at boot, detect the existing version, and apply only what is missing.

Tables#

vg_actions#

The core table. Each row is one event.

Indexing is on (world, x, z, y, time) for spatial queries plus a composite (ts, id) index added in v9 for keyset pagination.

Backup and restore#

SQLite#

Stop the server, then copy the file. SQLite in WAL mode leaves -wal and -shm sidecars, so copying a live database without the sidecars captures an inconsistent snapshot.

# Server stopped
cp vonixguardian.db vonixguardian.db.backup-$(date +%F)

For a live backup without stopping, use SQLite's own tooling:

sqlite3 vonixguardian.db ".backup '/backup/vg-$(date +%F).db'"

Restore by putting the file back with the server stopped and the sidecars removed:

rm -f vonixguardian.db-wal vonixguardian.db-shm
cp vonixguardian.db.backup-2026-11-01 vonixguardian.db

MySQL / MariaDB#

mysqldump --single-transaction --quick vonixguardian > vg-$(date +%F).sql
mysql vonixguardian < vg-2026-11-01.sql

--single-transaction gives a consistent snapshot without locking the tables.

PostgreSQL#

pg_dump -Fc vonixguardian > vg-$(date +%F).dump
pg_restore -d vonixguardian --clean vg-2026-11-01.dump

Direct SQL#

Read-only queries against the audit log are useful for reporting and for verifying that a rollback did what it claimed.

-- Row counts by action type, last 7 days
SELECT a.type, COUNT(*) AS n
FROM vg_actions a
WHERE a.ts > (EXTRACT(EPOCH FROM now()) * 1000 - 604800000)
GROUP BY a.type
ORDER BY n DESC;

-- The 20 most recent block breaks in the overworld
SELECT u.name, a.x, a.y, a.z, a.target, a.ts
FROM vg_actions a
JOIN vg_users u  ON u.id = a.user_id
JOIN vg_worlds w ON w.id = a.world_id
WHERE w.world_key = 'minecraft:overworld'
  AND a.type = 2
ORDER BY a.ts DESC
LIMIT 20;

-- Database size by table (PostgreSQL)
SELECT relname, pg_size_pretty(pg_total_relation_size(oid))
FROM pg_class
WHERE relname LIKE 'vg_%'
ORDER BY pg_total_relation_size(oid) DESC;

Action type ids are stable: 1 place, 2 break, 3 container deposit, 4 container withdraw, and so on. The full list is on Action types.

Quarantine and drops#

When the writer cannot keep up, events are not silently lost. The admission path tries, in order:

1. Enqueue normally.
2. Journal to the durable quarantine outbox (vg_sink_outbox plus queue-quarantine.bin) if the queue is full and the quarantine has capacity.
3. Count and log the drop at ERROR with the action type, id, world, and coordinates if the quarantine is also full.

/vg status exposes the counters:

A non-zero dropped with zero quarantined means the durable path is disabled or full — check qOverflow and qWriteFail. Rows recovered from quarantine are replayed; rows in qOverflow are loss records, not replayable.

For a rejected explosion handoff, the journal records entries=<n> at the blast centre only. The per-block list is not retained, so that row is a loss record and not a rollback source.

Repair-required rows#

When a mutation cannot be applied and cannot be compensated, the row is recorded in vg_repair_required with the batch id and a reason. This is the engine refusing to guess.

/vg status lists them:

§ Rollback recovery
  open batches 1 — inspect with /vg lookup before re-running rollback or restore
  batch 17 mode=ROLLBACK affected=318
  repair required 2
  repair action 4412 batch=17 reason=target block entity type mismatch

Inspect the referenced rows with /vg lookup and #verbose, then decide whether to re-run the rollback for that region. There is no automatic repair — a wrong assumption is worse than an outstanding record.

Cache and maintenance#

Each backend benefits from its own maintenance, and /vg purge ... #optimize runs the right one:

The optimize step is capped at five minutes and its failure never fails the purge. Run it after a large deletion, not routinely — VACUUM on a multi-gigabyte SQLite file rewrites the whole database.

Migrating to another backend#

/vg migrate-db copies the catalog and is described in full on Backend migration. The short version: configure database.migrationTarget, run /vg migrate-db <type> CONFIRM from the console, then change database.type and restart.