HQbird Backups
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 copies | Data 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. |
| Size | Usually much smaller than the database; compresses well. | Level 0 is the size of the database; increments are small. |
| Restore | Creates a new database and builds the indexes again. For large databases this takes a long time. | Merges the chain of levels. Fast. |
| Check | Test 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 for | A 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 database | All databases in folders | |
|---|---|---|
| gbak with check | vbackup | grpvbackup |
| nbackup with levels | nbackup | grpnbackup |
| nbackup dump | nbackup_dump | grpnbackup_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
- sales.fdbin group
- stock.fdbin group
- branch_new.fdb
new database: starts with level 0in group - erp.fdb
has its own individual jobskip - security5.fdb
system databaseskip - bck_sales_20261107.fbk
backup fileskip - orders.fdb.delta
nbackup delta fileskip
- Database removed from the folderIt becomes “orphaned”. Its backups are kept by a rule: N days or always. Or they go to the
_orphanedfolder 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.FDBgoes to<backup folder>/x/y/EMPLOYEE.FDB/. Databases with the same name from different folders do not get in the way of each other.
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.
- 1Space checkfor the backup; again before restore and compression
- 2gbakto a temporary
.gbaktmp; on Firebird 5 — on N cores - 3Checksize and log; then the
.fbkname - 4Test restoreif on; a separate file, not the production database
- 5Compressionarchive unpacked and compared by SHA-256
- 6✓ Storagecopy to another folder; old copies are deleted
- Clear names
bck_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
-Ysends the gbak output to a file, but the agent checks the backup by this output. So-Yis not allowed. A streaming job does not accept-SEin 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 TDRWswitch to each backup and restore and takes the gbak time from the output. You do not need your own-STin the job options: the editor does not accept it. - The agent sets the loginThe switches
-user,-password,-fetch_passwordand-trustedare 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.
- 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 copy | Stream to S3 | |
|---|---|---|
| File on the server disk | Yes. The backup is written to disk, then sent. | No. The backup goes directly to the bucket. |
| Disk space for the backup | Needed. | Not needed. |
| Where to | S3, FTP, FTPS | S3 only |
| Deletion of old copies in the bucket | No. Use a bucket lifecycle rule. | Yes, by the retention rule of the job. |
| Upload failure | The 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
| Error | Cause | What to do |
|---|---|---|
AccessDenied | A right is missing, or the path in the rights is different. | Check the user rights. |
SignatureDoesNotMatch | Wrong key, or spaces in its value. | Copy the key again. |
PermanentRedirect | The region in the settings does not match the bucket region. | Fix the region. |
NoSuchBucket | Wrong bucket name. | Fix the name. |
RequestTimeTooSkewed | The 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
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.
The database returns to online
The agent puts the database online and restores the shutdown delay.
Rollback
The intermediate copy and the incomplete backup are deleted, the original gets its old name and goes online.
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.
| Variable | Before backup | After restore |
|---|---|---|
FBAGENT_HOOK_PHASE | pre | post |
FBAGENT_JOB_ID | job id | |
FBAGENT_DB_NAME | name in the job: alias or path | |
FBAGENT_DB_PATH | database file: original, online | same path: new database, online |
FBAGENT_ORIG_PATH | empty | path to the original |
FBAGENT_FBK_PATH | future backup file; empty in pipe mode | backup 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.