Upgrades, backup & disaster recovery

Upgrading DioscHub is pulling a new image and restarting. Protecting it is backing up two stores — the database and the file store — with your own tooling. This page covers both, and is honest about what DioscHub does not do for you: it takes no backups, and its migrations do not roll back.

What an upgrade is

An upgrade is mechanical:

1. Pull the new image tag.
2. Restart the container with the same environment and the same database.

On boot, the new image applies its own schema. The migrations are bundled into the image and run automatically — there is no separate migrate command to run inside the container, and no step you can forget. When the container reports healthy, the upgrade is done.

Why it is safe on an existing database

DioscHub owns its schema through migrations, not through automatic synchronization. On a fresh database the migrations create everything; on a database that already has data they adopt it in place — the baseline migration detects an existing schema and skips its creation statements while still recording itself as applied, and later migrations add columns conditionally (IF NOT EXISTS, nullable or defaulted) so they backfill a populated table without disturbing it. Re-running an already-applied migration is a no-op.

Danger

Never set DIOSC_DEV_MODE in production. It switches the database into automatic schema-sync mode, which can alter or drop columns to match the code and has caused data loss. Production applies migrations only; that is the safe path, and it is the default.

Where durable state lives

DioscHub keeps everything that must survive a restart in exactly two places:

• PostgreSQL — all configuration, Session state, history, Consensus decisions, and the Knowledge base index. This is the primary source of truth.
• The object/file store — uploaded and generated files, held by whichever provider you configure through STORAGE_PROVIDER: a local volume (local) or object storage (s3, gcs, azure).

In a cluster, Redis is also present, but it holds only coordination state — bindings, counters, delivery. It is ephemeral and is not a source of truth, so it is not something you back up.

Backing up

DioscHub does not back itself up. There is no scheduler, no built-in dump, no point-in-time recovery. Backups are yours to run with the database’s and object store’s own tooling.

A complete backup is both stores captured together:

• The Postgres database — a full dump (all tables, including Session state and the Knowledge base index). Your managed Postgres snapshots, or pg_dump, cover this.
• The file store — a copy of the object storage bucket, or of the LOCAL_STORAGE_PATH volume if you use local storage.

Caution

A database dump alone is not a full backup. Files live in the object store, not in Postgres. Back up both, ideally at the same point in time.

Restoring and disaster recovery

To recover, restore both stores from the same point, then start a matching or newer image:

1. Restore the Postgres database from your dump.
2. Restore the file store (bucket or volume) from the same point in time.
3. Start the image. It re-applies any migrations the restored schema is missing and comes up on the restored state.

Point the restored deployment at the same secrets it had before — in particular the credential master keys. Stored MCP and LLM credentials are encrypted at rest with those keys; restoring the database without the original master keys leaves that data unreadable.

Roll back by restoring, not by reverting migrations

Migrations move the schema forward. They are not written to be reversed — the baseline migration explicitly refuses to run its down step. So there is no “downgrade the schema” path.

To go back to a prior version, do not try to revert migrations. Instead, restore the database from a backup taken before the upgrade, and run the prior image against it. This is why a pre-upgrade backup matters: it is your only rollback.