QBit Backups
QQQ QBit: logical backup, restore and verification of QQQ data to S3-compatible storage.
Status: design: QRun-IO/qqq#1091; implementation in progress. Nothing is published yet.
Requirements
- Java 21.
- QQQ 4.1 (targets
4.1.0-RC.6, not yet released).
Install
Not yet published. Once released, add com.kingsrook.qbits:qbit-backups and produce the qbit into your QInstance:
new BackupsQBitProducer()
.withQBitConfig(new BackupsQBitConfig().withBackendName("rdbms"))
.produce(qInstance);
Setup
This qbit ships no DDL and seeds nothing from a changelog: its one setup value, the storage bucket alias, belongs to your application. On a fresh install open Backups, read the Setup card, and run Create default plan on Backup plans (it asks only for the alias of a bucket your storage resolver provides). It creates the insert-only "Nightly full" plan: whole instance, data and audit tables, JSONL and gzip, 02:00 UTC, verified Sundays 04:00 UTC. Edit any setting afterwards. Help for every table, including how its rows get created, ships in help/qbit-backups.yaml.
Naming
Tables are backups_<name> (lowercase snake_case, backend name equal to the table name). Permissions are backups.<action>.
Adopting in another app
Follow the QQQ adoption checklist once the first release is published.
Build
./mvnw verify
Before RC.6 is released, verify against the locally installed core build only:
./mvnw -B verify -Dqqq.snapshot.version=4.1.0-ARCHRC6-SNAPSHOT
The POM stays on RC.6. See the RC.6 migration notes for fingerprint compatibility, paging guarantees and restore permissions.
Always use the Maven wrapper (Maven 3.9.11); Maven 3.10 cannot read the parent POM.
License
Apache License 2.0. See LICENSE and NOTICE.
Alerts integration
Backups binds directly to core QAlerts in QQQ 4.1.0-RC.5 and declares its nine
alert types on each instance. Hosts install an AlertSinkInterface through
AlertsInstanceMetaData.withSink(QCodeReference). Without a configured sink,
backup alert calls remain no-ops (they do not use core's logging fallback).
Custom BackupAlertSink bindings are preserved. Core handles dispatch failures;
adapter failures are caught and logged once, so alerting cannot fail a backup.
Raise and resolve follow core's transaction-aware dispatch; heartbeats run immediately.
The backup SLA checker still owns expected intervals and grace periods.
RC.5 requires hyphenated alert names: backups.run.missing-in-storage and
backups.plan.owner-invalid replace the former underscore spellings, including
their deduplication keys. Update host routing rules that used those spellings.