Backups & Restore

udServer can take and restore a full backup of its own database from the Backups page in the Admin console, without going near pg_dump or needing shell access to the host. It requires the Backups global permission, which is separate from every other administrative permission precisely because a backup file is a copy of everything.

Only one backup or restore runs at a time.

What a Backup Contains

A backup is a snapshot of the entire database:

  • All users, including password hashes
  • Organisations, projects, scenes and their edit history
  • Sessions, licences and licence allocations
  • Software packages, including the embedded file data
  • Webhooks, OAuth provider secrets, per-project storage credentials and the server's own keys
A backup file is a complete set of credentials for this server and everything it connects to. Treat it as the most sensitive artefact your deployment produces: encrypt it at rest, restrict who can fetch it, and do not leave it in a shared download folder.

Files in external project storage are not included. Anything in S3, Azure Blob Storage or a local/network file share belongs to the project's storage rather than the database, and must be backed up separately. What the backup holds is the configuration pointing at that storage, not its contents.

Creating a Backup

Create backup starts the job and reports progress as it runs — the table being read, then the compression pass. When it finishes you are told the compressed and uncompressed sizes, and Download backup fetches the .udbackup file.

Two things to know:

  • The backup is held in memory and is released roughly 15 minutes after it completes if it has not been downloaded. It is not written to the server's disk.
  • It can only be downloaded once. Downloading takes it. Save the file somewhere durable rather than treating the server as the place it lives.

Restoring

Restoring replaces every row in the database with the contents of the backup file. It is the most destructive action available in the admin console, and the confirmation dialog requires you to type the confirmation phrase rather than just clicking through.

What happens when you restore:

  1. The server enters maintenance mode. Every API request except the backup endpoints is rejected for the duration, so nothing can write while the database is being replaced.
  2. The data is restored, then migrated to the current database version if the backup came from an older build. Restoring an older backup into a newer server is supported and expected.
  3. Every session is invalidated, including yours. You are logged out and have to sign in again.

A restore either completes or leaves the server exactly as it was — a failure rolls the whole thing back rather than leaving a half-replaced database, and the error is reported on the page.

A server restart is recommended after a successful restore.

Restore uploads through the web interface are limited to 128 MB. A larger backup has to be restored by another route.

Do not close the page while a restore is running. It is the page polling for progress, and it is what prompts you to sign back in when the restore completes.

When to Take One

At minimum, before any upgrade. The database is migrated in place on first start of a new build, and a migration is not reversible — the backup is what makes the upgrade reversible. The release notes name the database version each release migrates to.

Egress

Generic Installation