Backups Firebird

Scheduled gbak and nbackup, for one database or for all databases in a folder. For gbak, you can turn on a test restore after each backup. A database is updated from a backup automatically, and no failure in the middle leaves it in an unknown state.

  • 6 backup job types
  • nbackup levels 0…4
  • zip · gz · zstd with archive check
  • S3 without an intermediate file
  • test restore

Two tools

gbak or nbackup

HQbird supports both Firebird backup types, and you can use both for one database. gbak makes a logical copy: it is smaller than the database, and a restore checks it. nbackup copies database pages: it is fast, and increments take little space.

gbak (verified backup)nbackup (incremental)
What it copiesData and metadata. Garbage and old record versions do not go into the copy.Pages of the database file. Level 0 is full; levels 1…N contain only changed pages.
SizeUsually much smaller than the database; compresses well.Level 0 is the size of the database; increments are small.
RestoreCreates a new database and builds the indexes again. For large databases this takes a long time.Merges the chain of levels. Fast.
CheckTest restore after each backup, if it is on in the job.Chain check by GUID. No level 0 — the agent makes it at once.
Use it forA reliable copy, moving between versions and servers, Backup-Restore-Replace.Frequent restore points during the day without load on the server.

If gbak and nbackup of one database must start in the same minute, gbak moves 15 minutes later. While nbackup uses the database, gbak waits (up to 60 minutes by default) and does not fail.

Job types

Individual and group jobs

An individual job covers one database and has its own settings. Use it for the main company database: its own schedule, its own folder, its own retention.

A group job covers folders with databases. One set of settings for all databases of the group. In each cycle, the agent scans the folders by masks again, so a new database gets into the backup automatically, without a change to the settings.

One databaseAll databases in folders
gbak with checkvbackupgrpvbackup
nbackup with levelsnbackupgrpnbackup
nbackup dumpnbackup_dumpgrpnbackup_dump

What a group job takes and what it skips

The agent walks through the folders and checks each file against include and exclude masks. Optionally, it also checks the minimum size and the start of the file. Backup files (.fbk, .nbk, .delta, archives) never go into the backup.

A database that has its own individual job is excluded from the group automatically, even if that job is off. A gbak group does not take databases of individual gbak jobs. An nbackup group does not take databases of nbackup and dump jobs.

System databases (names that start with security and examples) are always skipped. The scan preview shows the reason for each skip.

D:\data\ · mask *.fdb

  1. sales.fdbin group
  2. stock.fdbin group
  3. branch_new.fdb
    new database: starts with level 0
    in group
  4. erp.fdb
    has its own individual job
    skip
  5. security5.fdb
    system database
    skip
  6. bck_sales_20261107.fbk
    backup file
    skip
  7. orders.fdb.delta
    nbackup delta file
    skip
  • Database removed from the folderIt becomes “orphaned”. Its backups are kept by a rule: N days or always. Or they go to the _orphaned folder at once and are deleted after 7 days.
  • Database renamedThe new name starts a new chain from level 0. Old backups are kept by the rule for orphaned databases.
  • Repeated failuresAfter 5 failures in a row, the database is paused for 6 hours and then tried again.
  • An error in one database does not stop the groupThe group continues with the next database. This is the setting “Continue with the next databases after an error”; it is on by default for gbak, nbackup, dump and sweep groups.
  • Group outcome in the job row“Found N databases · succeeded M · errors X · total time”. The details have a table of databases with an error: name, path and the start of the error text.
  • Time budgetA cycle does not start new databases when the time is over. For nbackup groups, you can turn on continuation from the next database in the next cycle.
  • ParallelismHow many databases of the group to process at the same time. A common limit for long tasks on the server: by default, no more than two run at the same time.
  • One operation per databaseIndividual and group jobs, gbak and nbackup see each other's locks.
  • Folder tree as in the sourceThe “Repeat the source folder tree” check box: the backup of the database x/y/EMPLOYEE.FDB goes to <backup folder>/x/y/EMPLOYEE.FDB/. Databases with the same name from different folders do not get in the way of each other.
Jobs in HQ Monitor. Six backup types and the inventory. Restore jobs are in a separate group: you must allow them explicitly, because they change databases.

vbackup · grpvbackup

gbak: backup with check

Before each step, the agent checks free space: for the backup, for the test restore, for the archive. If there is not enough space for the restore, the agent skips it with the reason no_space, and the backup stays. gbak writes to a temporary file. The file gets the .fbk name only if the size and the gbak log are correct. So an incomplete backup with a normal name never appears in the folder.

  1. 1Space checkfor the backup; again before restore and compression
  2. 2gbakto a temporary .gbaktmp; on Firebird 5 — on N cores
  3. 3Checksize and log; then the .fbk name
  4. 4Test restoreif on; a separate file, not the production database
  5. 5Compressionarchive unpacked and compared by SHA-256
  6. 6✓ Storagecopy to another folder; old copies are deleted
gbak job form. Schedule with a time zone hint, backup folder and name, gbak options in one line, timeouts and space calculation factors.
  • Clear namesbck_sales_20261107_02-00.fbk: the start of the database name and the time. Two databases in one folder do not write the same names.
  • Overlap warningIf two jobs write files with the same name start to one folder, the agent and the editor show a warning.
  • Test restore resultok, failed, skipped with a reason, or not_run. You see it in the last job outcome and in the inventory. In the editor, each restore shows both commands: backup and restore.
  • Old test databaseA new job starts the test restore with -rep: gbak overwrites the copy from the previous run. The agent first disconnects the clients of this copy. If the test database path is the same as the production database or the database of another job, the restore is skipped.
  • gbak logs and commandsThe last error lines are visible in the console; you can download the log. Logs are deleted together with their backup. The agent keeps a history of run commands: up to 50 for each job step, passwords hidden.
  • Switches that break the check-Y sends the gbak output to a file, but the agent checks the backup by this output. So -Y is not allowed. A streaming job does not accept -SE in the restore line either. The editor marks these switches.
  • TimeoutsSoft: a warning. Hard: gbak is stopped.
  • gbak time by stepThe agent itself adds the -ST TDRW switch to each backup and restore and takes the gbak time from the output. You do not need your own -ST in the job options: the editor does not accept it.
  • The agent sets the loginThe switches -user, -password, -fetch_password and -trusted are not allowed in the options. The test restore runs as the database owner, if the owner is recorded in the database access settings. The restore row shows which user name it ran as.
  • Clear messagesSpace and time in familiar units: “8.1 GiB free, 11.8 GiB needed”, “timed out after 60 s”.

nbackup · grpnbackup

nbackup: levels and restore points

Level 0 copies the whole database. Level 1 copies pages changed after the last level 0. Level 2 copies changes after the last level 1. To restore the database to the moment you need, three files are enough.

Example schedule: level 0 once a week, level 1 every night, level 2 four times a day. This gives 36 restore points per week: 1 + 7 + 28. It keeps 5 copies of level 0, 7 of level 1 and 24 of level 2.

nbackup week: level 0 on Sunday, level 1 every night, level 2 four times a day; a restore takes one file of each level
level 0 level 1 level 2 files for restore
  • Chain without gapsNo level 0 — the agent makes it at once. For other levels, this is the “Immediately create missing low levels” setting. Without it, the run is skipped while the lower level is missing.
  • Check by GUIDEach level is bound to its lower level; a foreign file does not get into the chain.
  • Three schedule modesSimple — by days and hours. Advanced — cron for each level, up to level 4. Plan — rules with a level, days and time.
  • nbackup dumpA full copy of the database file outside the level chain, on its own schedule.
  • Database in delta stateIf the database stays locked after an interrupted nbackup, the agent tries to merge the delta.

Plan mode

A plan is a set of rules: level, days and time. Days can be every day, days of the week or days of the month. If two rules match in the same minute, the lower level runs. The plan can make a level 0 by itself when the last level 0 is older than a set number of days. It runs a lower level earlier than scheduled when the increments grow above a set share of the database size. In a group job, each database builds its own level chain.

The editor shows the plan in a calendar several weeks ahead: which level runs and when. One button converts a simple or advanced schedule into a plan, and you can undo this before you save.

  • Retention by cyclesA cycle is a level 0 with all its increments. The agent keeps or deletes a whole cycle: by the number of cycles, by days or by total size. The newest full cycle is never deleted. The editor shows in advance how much space the backups will take.
  • Plan statusThe last copy of each level, the space used and what the next cleanup will delete. The agent updates the status after each plan run.

Compression · S3 · storage

Where backups are stored

A backup can go directly to S3: gbak or nbackup writes to a stream, and the stream goes to the bucket. There is no intermediate file on the server disk, so you do not need space for the backup on the server.

zip, gz or zstd compression works for both local and streaming backups. For a local backup, the agent unpacks the finished archive and compares it with the source by size and SHA-256. Only after that is the source file deleted. If the check fails, nothing is deleted.

  • Retention by countgbak: how many files to keep. nbackup: how many copies of each level.
  • Copies to other placesA copy to a second folder or a network path. Upload to S3, FTP or FTPS — with a separate file_sync job.
  • Your own script after the backupFor gbak. It gets the paths to the backup, the test database and the gbak logs.
  • Archive encryptionA gbak job can encrypt the zip archive (AES-256) with a password from the agent keys, on disk and in the S3 stream. 7-Zip opens the archive. A restore finds the correct key by itself.
  • Restore from an archiveThe format is detected from the file content, locally and from S3.
  • Restore from S3A restore job reads the backup directly from the bucket.
  • AntivirusExclude the backup and restore folders from real-time scanning.
  • You choose the compressionA new job is created without compression. zstd is first in the list of formats. You can set your own file extension for an archive of any format.
  • Amazon S3 guideStep-by-step setup of the bucket, the keys and the job. Available in English and Portuguese.

Amazon S3 · compatible storage

Backups to S3

The agent sends backups to a bucket in Amazon S3 or in compatible storage. This works for gbak and nbackup jobs. You do not need another program for this.

The setup has three parts: prepare a bucket and an access key, create an s3 target in the agent settings, turn on upload in the backup job. Each job uses one of two modes.

File copyStream to S3
File on the server diskYes. The backup is written to disk, then sent.No. The backup goes directly to the bucket.
Disk space for the backupNeeded.Not needed.
Where toS3, FTP, FTPSS3 only
Deletion of old copies in the bucketNo. Use a bucket lifecycle rule.Yes, by the retention rule of the job.
Upload failureThe local backup stays valid.No backup: no object stays in the bucket.
  • How to chooseFile copy: when you need both a local copy and a copy in S3. Stream: when the server disk is small or S3 is the only place for backups.
  • Restore from S3A restore job reads a streamed backup directly from the bucket: the newest object or the one you name. The agent checks the size and SHA-256 of each object.
  • EncryptionBucket encryption protects the object on the storage side. Archive encryption in the job protects the file with a password before it leaves the server.
  • BucketKeep public access blocked. Add a rule that deletes unfinished multipart uploads after one day.
  • A key only for backupsCreate a separate user. Give it only the rights it needs: write, read and delete objects, abort an upload and list the unfinished uploads of the bucket. If the bucket is encrypted with a KMS key, it also needs rights on this key. On an Amazon EC2 server, you can work without a key: the agent uses the IAM role of the server.
  • CheckStart the job with the Run now button, look at the result and do a test restore before you rely on the backup.

Common errors

ErrorCauseWhat to do
AccessDeniedA right is missing, or the path in the rights is different.Check the user rights.
SignatureDoesNotMatchWrong key, or spaces in its value.Copy the key again.
PermanentRedirectThe region in the settings does not match the bucket region.Fix the region.
NoSuchBucketWrong bucket name.Fix the name.
RequestTimeTooSkewedThe server clock is wrong.Sync the clock with NTP.

restore.replace_cycle

Backup-Restore-Replace

The cycle rebuilds the production database. The agent makes a gbak backup, restores it to a new file and puts the new file in place of the old one. The new database has no garbage, its indexes are fresh, and it is usually much smaller. The production database is disconnected and renamed safely: the agent first puts it into shutdown full, all connections close, and only then the file gets a new name.

By default, the cycle runs on Saturday at 02:00; you can change the schedule. Run now starts the cycle at once, but first asks you to type the database file name. The database can be set by a path or by an alias from databases.conf.

    Clients

    connect sales.fdb

    Files on disk

    From shutdown to replace, clients get “database not found” or “database shutdown”. Schedule the cycle for a time when the database can be unavailable for a backup plus a restore. In pipe mode, the backup and the restore run at the same time, and no backup file is written.

    The cycle does not start if

    • “Allow replace” (allow_replace) is not on in the job;
    • the database is in shutdown, encrypted or a replica;
    • the database is a security DB, its own or for other databases;
    • files of an unfinished cycle are next to it;
    • there is not enough disk space.

    Space is calculated in advance: the backup file and the restored copy are on disk at the same time, each about the size of the database. The original is renamed, not copied, so it takes no space. If space is low, the cycle stops before shutdown: the database is not touched, and clients keep working.

    What stays on disk

    Originals. The last originals in shutdown full are kept next to the database, from 1 to 10, 1 by default. Extra ones are deleted at the start of the next cycle, so the database in its state before the last cycle is always there.

    The backup file is deleted after the replace. If the restore failed, the file is kept as .restore-failed.fbk for analysis.

    To go back to the original: stop the production database, rename the files and run gfix -online for the original.

    When the cycle is interrupted

    Someone can stop the agent, the server can reboot, power can fail. On a normal service stop before the replace, the agent lets gbak finish and rolls back the cycle. For the case of a failure, before each step the agent writes what it does to an intent file. At start and then every minute, the agent reads these files and brings the cycle to a known state.

    Before the rename

    The database returns to online

    The agent puts the database online and restores the shutdown delay.

    Before the replace

    Rollback

    The intermediate copy and the incomplete backup are deleted, the original gets its old name and goes online.

    After the replace

    Completion

    The new database stays in production, the original is kept in shutdown. The “after” script did not run: run it yourself if it is important.

    If the files on disk do not match any known state, the agent changes nothing, and the job outcome starts with “operator needed”. The intent file lists the names of all cycle files. Put the correct database at its path, and the agent finishes the recovery by itself.

    Your own scripts before and after

    The “before backup” script runs before shutdown. If it ends with an error, the cycle stops and the database is not touched. The “after restore” script runs after the replace. Example: copy the backup file to an archive before the agent deletes it.

    VariableBefore backupAfter restore
    FBAGENT_HOOK_PHASEprepost
    FBAGENT_JOB_IDjob id
    FBAGENT_DB_NAMEname in the job: alias or path
    FBAGENT_DB_PATHdatabase file: original, onlinesame path: new database, online
    FBAGENT_ORIG_PATHemptypath to the original
    FBAGENT_FBK_PATHfuture backup file; empty in pipe modebackup file, deleted after the script; empty in pipe mode

    Inventory · health report

    Control: which database has no backup

    The inventory shows all backup files on the server, also those made by other programs. The agent updates it after each backup and fully every 2 hours. Next to it is a table of restores: test and production, for 14 days.

    Each backup has a Verified column: the test restore passed, failed or did not run. Next to it are the size of the restored database and the gbak time. The restore table shows the database size and the duration.

    The server health report marks a database without registered backups and says why: the job failed, still runs, is postponed, or there is no file in the folders. A button next to the finding opens the form for a new job at once.

    Inventory. The test restore of each copy fails, and you see it at once. Files without their own job are marked ORPHANED.
    Findings in the report. “No backups for the database”: add an nbackup or gbak job with one button.

    ← Back to the HQbird 2027 overview