Backup & Restore
A backup is a single portable .qbak archive bundling the two kinds of state that together
make a working deployment. It is one file: nothing else has to travel with it.
What is in a backup
| Kind | Contents |
|---|---|
| Database entities | Connections, the namespace tree (nodes, tags, protocol bindings), alarm definitions, user-defined types, users, and the project registry — each dumped as a JSON section |
| File trees | Per-project artifacts: views, scripts, named queries and assets |
| Not in a backup | Where it lives |
|---|---|
| Tag history | QuestDB — back it up with your database procedures |
| The audit journal | The external audit database — deliberately separate |
| Execution and system logs | Diagnostic data, not configuration |
| Live runtime values | Reconstructed on start |
.env | Back it up separately; it holds ENCRYPTION_KEY |
Encryption and secrets
This is the part to get right.
| Backup | Contains connection secrets | Anyone opening it sees |
|---|---|---|
| Passphrase-encrypted | Yes, protected by the encryption | Nothing without the passphrase — an opaque blob |
| Unencrypted | No | Configuration, with credentials blank |
An unencrypted backup deliberately omits secrets so an unprotected archive cannot leak plant access. An encrypted backup is sealed whole — no usernames, no password hashes, no configuration, no secrets are readable without the passphrase.
An unencrypted backup restores with blank credentials — every connection must be re-entered. That is the right trade for an archive you cannot fully protect, and the wrong one for disaster recovery. For DR, use a passphrase and store it in your secrets manager.
Portability
Backups are portable across machines because secrets are re-keyed in transit:
- On export, each connection is decrypted with the source machine's key.
- On restore, it is re-encrypted under the target machine's key.
The archive therefore never carries machine-key-encrypted blobs, which is exactly why copying the configuration database between machines does not work but a backup does.
Which builds can read an archive New in 1.0.4
An archive is forward-compatible and backward-refused: it restores into the build that made it and into every later one, and a build that predates it will refuse rather than read it wrongly.
The refusal is measured from what the archive actually contains, not from the version that produced it. An estate that never touched a newer feature keeps producing archives an older build accepts — gating on the version number would refuse a 1.0.5 backup on a 1.0.4 gateway over a stylesheet fix, and a guard that refuses safe things is a guard people learn to override.
A refusal names the producing build, this build, and the part of the archive responsible:
This backup cannot be imported by this build.
Created by QUBIQ 1.0.5 on 2026-09-08 14:12 UTC
This installation QUBIQ 1.0.4
Importing it would silently drop settings this build does not recognise.
designer views use schema 3; this build understands 2
Today the things that can raise the floor are Designer view schema, pipeline schema, the shape of the database sections, and an account carrying a pending password reset — a build without that column would restore the account and let the old password keep working, silently undoing the reset.
Two things follow:
- An archive with no compatibility envelope is adopted, not refused. Every backup taken before this shipped restores exactly as it did.
- The same rule covers view packs and namespace exports, each measured against its own contents.
Every archive at or below this build's level, indefinitely. There is no lower bound and no expiry.
Taking a backup
Settings → Backup & Restore, which has a tab per scope:
| Tab | Covers |
|---|---|
| Full instance | Everything — connections, the namespace, alarms, users, and every project |
| Project | One project's resources and assets |
| Views | Individual Designer views |
Download backup (.qbak) writes the archive to your device. Give it a passphrase first if the backup is to carry connection secrets.
| Scope | Permission |
|---|---|
| Export or restore a full instance backup | Manage backups |
| Export or restore one project | Manage projects |
| Import a project as a new project | Create projects |
Manage backups is super-admin-only by default: a backup can move an entire configuration off the machine.
Every export and restore is recorded in the audit journal.
When to take one
- Before every upgrade. Schema migrations are not reversible.
- At each commissioning milestone, so there is a known-good point to return to.
- Before any bulk operation — a large namespace import, a UDT sync across many instances, a bulk delete.
- On a schedule, retained off the machine.
Restoring
- Stop what you can safely stop — pipelines, ideally the whole gateway for a full restore.
- Choose the archive, supply its passphrase if it is encrypted, and choose the conflict policy.
- Verify connections: enable each one and check it reaches connected, and re-enter credentials if the backup was unencrypted.
A restore puts things back as they were, including what was switched off: a disabled connection stays disabled, a disabled tag stays disabled, and a suspended user stays suspended. Changed in 1.0.4 Earlier builds turned all three back on. 4. Verify the namespace: check binding statistics for unbound tags. 5. Verify projects: open each and confirm views load. 6. Start pipelines.
The conflict policy
This is the setting to get right. It decides what happens to what is already on the machine.
| Policy | What it does | Use it for |
|---|---|---|
| Overwrite | Replaces existing connections, namespace entries and project files whose identifiers match. | A restore — putting a machine back the way it was. |
| Merge | Keeps what is there and adds only what is new. Existing connections, folders and tags are matched by name or path, so nothing is duplicated. | Bringing one machine's configuration onto another that already has its own. |
| Abort | Refuses unless the instance is empty. | A first restore onto a fresh install, when you want to be told rather than to find out. |
Overwrite is the default, and it is the destructive one. Take a backup of the current state before restoring, even when you are confident — especially then.
The restore report
A restore reports what it actually did: a count per section (connections, projects, namespace nodes, tags, protocol bindings, alarms, UDT definitions, members, instances and overrides), the number of files, and any warnings.
Read the unresolved connections list if there is one. Project resources reference a connection by name, so a project restored onto a machine that has no connection by that name lands with those references dangling — which shows as a broken binding rather than as a failed restore.
Migrating to a new machine
1. Take a passphrase-encrypted backup on the source
2. Install QUBIQ on the target and complete first-run setup
3. Restore the backup
4. Point the historian at its QuestDB store (take ownership if the source is retired)
5. Configure the audit journal's storage connection
6. Check every connection reaches connected
7. Start pipelines, verify screens, then decommission the source
Step 4 matters: the historian records physical ownership inside the QuestDB store, so a restored configuration will refuse to write to a store the old machine still claims. Confirm the source is truly retired before taking ownership.
Project backups
A project backup carries one project's resources and assets, not the instance's connections or namespace. Use it to promote an application between environments.
Settings → Backup & Restore → Project offers three actions:
| Action | Does |
|---|---|
| Export | Writes the chosen project as a .qbak. |
| Restore | Puts a project archive back in place, under its original slug. |
| Import as new | Creates a copy under a name you give it — the way to clone a project, or to bring a second copy of one onto a machine that already has it. |
The prerequisite for all three is that the target already has connections and tags with the same names — project resources reference them by name, not by internal identifier. A restore says so in its report when they are missing.
For the plant model itself, use namespace export/import.
Disaster recovery
A recoverable QUBIQ deployment needs five things, and losing any one leaves you rebuilding:
| Item | Store where |
|---|---|
| Passphrase-encrypted configuration backup | Off-machine backup storage |
.env (or at least ENCRYPTION_KEY) | Secrets manager, separate from the backup |
| The database recovery key | On paper, off the machine |
| QuestDB backup | Your database backup procedures |
| Audit database backup | Its own procedures, under separate administration |
Test the restore. A backup that has never been restored is a hypothesis, not a plan. Restore into a scratch machine at least once per commissioning cycle.