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
Section titled “What an upgrade is”An upgrade is mechanical:
- Pull the new image tag.
- 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
Section titled “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.
Where durable state lives
Section titled “Where durable state lives”DioscHub keeps everything that must survive a restart in exactly two places:
- PostgreSQL — all configuration, Session state, history, Consensus decisions, file records and their status, and the search index of chat files and Knowledge base files. This is the primary source of truth.
- The object/file store — uploaded and generated files, and the text DioscHub extracts from each of
them (stored next to the file, under the
derived-text/prefix). They are held by whichever provider you configure throughSTORAGE_PROVIDER: a local volume (local) or object storage (s3,gcs,azure).
STORAGE_PROVIDER must be exactly one of local, s3, gcs or azure: lowercase, with no
surrounding spaces. Unset or empty means local. Any other value (S3, minio, s3 with a
trailing space) stops the hub at boot with an error that names the value.
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.
Upgrade note: file text moves to the file store
Section titled “Upgrade note: file text moves to the file store”The release that adds file status changes where DioscHub keeps the text it extracts
from files. Earlier releases kept it in a database column, extracted_text, on the chat-file and
knowledge-base file tables. This release keeps it in the file store, next to each file. The upgrade moves
the existing text for you, in the background:
- On boot, the migrations add the status columns and give every existing file a status from its old
state: an indexed file is
ready, an image isready, a file whose text was read but not indexed issearch_unavailable, a file that failed isfailed, and so on. A file indexed under the old text length cap gets atext_truncatedwarning. If no file holds text in the old column (a fresh install), the column is dropped then and there. Otherwise it is kept, and the migration raises a database notice with the number of rows still to move. - Once the hub is up, a background job,
file.text-backfill, moves each file’s text from the column to the file store and clears the column for that file. It works a row at a time under the row’s lock, so a file is never left without its text, and it carries on from where it stopped after a restart. - Each file it moves is re-indexed (files that are
readyorsearch_unavailable, images excepted). The re-index runs in the background under the per-library limit, behind users’ own uploads, and never stops at a storage quota. Until a file’s re-index finishes, search keeps using its existing index, so search works throughout. A re-index that fails leaves the file as it was. - When no file holds text in the column any more, the job drops the column.
Plan for the re-index:
- It costs embedding tokens. Every moved file is embedded again with the deployment’s current embedding model, roughly the cost of indexing your whole file library once, and on a large deployment it takes a while. Make sure the embedding provider is configured and has the headroom before you upgrade. If it isn’t, the re-indexes fail and the files keep their old index; run a bulk Re-index later.
- It moves storage. The extracted text now takes space in the file store instead of the database. Users’ storage usage stays about the same, because extracted text was already counted in it.
- Progress shows on System → Files: as files are re-indexed, they move from the embedding model
noneto your current model. The queued re-indexes arefile.indexjobs in the admin job API (GET /api/admin/jobs?kind=file.index&status=pending). The move itself is thefile.text-backfilljob; when it meets a file that is being indexed at that moment it skips it and runs again a minute later. The move is finished when theextracted_textcolumn is gone.
Rolling back after this upgrade means restoring the pre-upgrade backup, as below. Reverting the migrations
would re-create the extracted_text column empty, not refill it.
Backing up
Section titled “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_PATHvolume if you use local storage.
Restoring and disaster recovery
Section titled “Restoring and disaster recovery”To recover, restore both stores from the same point, then start a matching or newer image:
- Restore the Postgres database from your dump.
- Restore the file store (bucket or volume) from the same point in time.
- 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
Section titled “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.