Backups and restore

In short. Administration → Agora → Backups exports and restores Agora's database (members, forum, applications, settings, license). You make a backup in two clicks, then you download the file off the server. MDT records are not in it: they live in your game server database, to be backed up with it.

On a panel, the server backup does not replace Agora's. The panel's file copy (server backup, folder archive, SFTP) copies Agora's database while it is writing: the result is inconsistent, often unusable on restore. It also contains the database password. First make an Agora backup (an .sql file) and download it off the server. <!-- À CONFIRMER : œuf tout-en-un (claude/pg-integre), BASE-INTEGREE §4 -->

Before you start #

• Be an administrator of your Hub. To restore or import, you must be the installation's owner (the Owner badge in Administration → Members).
• A little disk space on the server: the backup is written there before you download it.
• The words (database, dump, .sql, SFTP) are in the glossary. If you hesitate between Agora's database and your game server's, read The two Agora databases.

Steps #

Make a backup #

1. Open Administration → Agora → Backups (administrators only).

   <!-- CAPTURE C-082 -->

2. Choose:

   • Download a dump now: a .sql file arrives in your browser, nothing is kept on the server;
   • Create a backup: writes a .sql into the server's backup folder, with the name you give in Name (optional) (a timestamp otherwise). The backup shows up in the Backups kept in Agora list.

3. Keep a copy off the server. A backup that stays on the machine disappears with it. With Download a dump now, it is already done; for a backup kept in Agora, fetch the file:

   • panel: in the file manager or over SFTP, app/.data/backups folder;
   • Node.js server: data/backups folder;
   • Docker: docker cp agora:/app/.data/backups ./agora-backups.

Restore #

1. Open Administration → Agora → Backups.

2. Either Import a file (a .sql from your computer), or Restore on a backup in the Backups kept in Agora list.

   <!-- CAPTURE C-084 -->

3. Tick the confirmation box ("I understand that Agora's entire database will be replaced by…"), then click the final red button: Import and overwrite or Restore.

   <!-- CAPTURE C-083 -->

⚠ Restoring completely overwrites the current database. Nothing is merged. Only import a file whose origin you trust.

You know it worked when… #

• The backup appears in the Backups kept in Agora list, and you have a copy off the server.
• After a restore, the site comes back with the backup's data. If the backup comes from an older version, Agora restarts by itself and brings the database up to date (step Bringing the database up to date after a restore… in Administration → Agora): the site is back in about a minute.

If it does not work #

<!-- CAPTURE C-085 -->

Going further #

What to back up #

The backup in detail #

Each dump is complete or absent: an interrupted dump is discarded. The tools (pg_dump, psql 17) ship with Agora, nothing to install. The backup is written as a stream into a .partiel file, renamed only once the dump is complete: it no longer loads the whole database into memory, which matters on a 512 MB panel. A backup's name cannot start with pre-update-, which is reserved for the automatic backups taken before an update.

Agora's backups (the pre-update one, the pre-migration one, db:export) contain no session tokens: a stolen copy cannot be used to pose as a signed-in administrator.

The restore in detail #

Restoring and importing are reserved to the installation owner: they rewrite the whole database, groups and owner included. Another administrator sees the message "reserved to the owner of this installation" and nothing is changed.

Before overwriting anything, Agora saves the database as it is into avant-restauration-…sql (the exact name is repeated in the confirmation message). A restore started by mistake can be undone by restoring that file. If it cannot be written, the restore is cancelled. Agora keeps the 5 most recent of these avant-restauration- files and of the import- copies; older ones are deleted.

A restore is refused while an Agora update is running ("wait for it to finish before restoring"): nothing is overwritten.

A streamed restore: big databases go through #

The .sql is never loaded whole into memory: Agora reads it in 1 MB pieces, cleans it line by line (privileges removed, transaction_timeout header made portable, meta-commands cut) and sends it to psql at the pace it consumes it. A database of several hundred MB therefore restores with a few MB of memory, even on a 512 MB panel.

• A truncated dump is refused before anything starts: it needs the pg_dump header and its end line. If reading fails midway (disk), psql is stopped dead and its transaction rolled back: the database is never replaced by half the file.
• Importing from the browser stays limited to 12 MB (the limit of an upload from a web page). For a larger dump, drop the .sql into the server's backup folder (.data/backups, through the panel's SFTP or docker cp): it shows up in the Backups kept in Agora list, then Restore.
• A line over 256 MB without a line break is refused: it is not an Agora backup.

An older backup: automatic catch-up #

A backup taken on an older version also brings back the database structure of its time. Right after the restore, Agora compares the database migrations with those of the running version. If some are missing, it restarts by itself and brings the database up to date through the same pass as an update on the same version: backup of the restored database, migrations, restart, health check. You can follow it in Administration → Agora, step Bringing the database up to date after a restore…; the site is back in about a minute. It never goes back to older code.

• Without a supervisor (manual installation), the message tells you to restart Agora yourself.
• A backup of the same version: no restart.
• After this catch-up, only the running version is kept on disk (the previous one is deleted from disk). A crash within the next three minutes restarts the same version, never an older one on the database that was just migrated.

From the command line (Docker with install.sh) #

# Back up
docker exec agora-db pg_dump -U agora --clean --if-exists --no-owner --no-privileges agora > agora-$(date +%F).sql

# Restore (stop Agora first)
docker stop agora
docker exec -i agora-db psql -U agora -v ON_ERROR_STOP=1 --single-transaction agora < agora-2026-09-24.sql
docker start agora

# Fetch the backups made by Agora
docker cp agora:/app/.data/backups ./agora-backups

<!-- CAPTURE C-087 -->

On a panel or a Node.js server #

Agora's database is inside the server (by default): you have no database tool to install, everything goes through Agora's admin area. Back up from Administration → Agora → Backups, then download the .sql files (app/.data/backups on a panel, data/backups on Node.js) with the file manager or SFTP. If you brought your own external PostgreSQL database, also back it up with its host's tools.

The game database #

Back up your whole game server database, as you already do for characters and vehicles. Booking photos are stored there: an active server can get heavy.

With the Pro tier, Server → Database also offers a Backups screen: Export the game database (a full dump kept in Agora) and restoring or importing a .sql. Stop the FiveM server first (txAdmin or panel): Agora no longer stops it itself.

How it works:

• An export is complete or absent: it is written into a .partiel file, renamed at the end; an interrupted export never shows up in the list. The "live" download moves at your browser's pace, accumulating nothing in memory, and closing the page stops it.
• Import and restore are read as a stream, statement by statement: a database of several hundred MB goes through with a few MB of memory. Before an import, Agora checks that there is enough free disk space; otherwise it refuses before touching anything.
• A safety backup (avant-import-jeu_…sql) is taken right before each import or restore, and the import cancels itself if it fails. The 5 most recent are kept after a successful import, older ones are deleted; a backup that you named is never deleted.
• If the import is interrupted (restart, memory) or if the automatic recovery fails, the page shows a red banner, even afterwards, naming the safety backup to restore to get back to the previous state. It disappears at the next import.
• Leftovers of a cut export or import (.partiel, .part) are erased by themselves after an hour.

<!-- CAPTURE C-086 -->

Suggested rhythm #

• Before each update: Agora does it on its own. Copy the file off the machine.
• Before a risky operation: a named backup ("before-cleanup").
• Every week: both databases, kept somewhere other than the machine.