www.destructor.de
GBAK is Firebird's command line tool for online backup and restore of a complete database.
GBAK is able to perform a backup while the database is running. There is no need to shut down the database during a GBAK backup. GBAK will create a consistent snapshot of the database at the time it starts running. You will, however, notice a perfomance degradation during the backup, so it is a good idea to backup at night. As GBAK visits all pages of the database, it will also perform a garbage collection on the database.
You can find the official Firebird GBAK documentation here.
GBAK will create a consistent snapshot (or dump) of a database. This snapshot/dump will contain the contents of the database of the point in time when the backup is started. For that, it will create an (one) isolated transaction that is used to read the entire database and write it to the snapshot/dump file (which ususally has the .fbk filename extension).
During the backup, the database can be used regularly. All transactions that run after the backup has started, will be separated from the backup. Depending on the size of the database, the duration of the backup and the number and duration of parallel transactions, this can more or less reduce the performace of the database while the backup is running (remember that Firebird has to handle all the data so that new data is isolated from the currently running backup). But it will work and after the backup is finished (the transaction is committed), the database will come back to its usual performance.
gbak <options> -user <username> -password <password> <source> <destination>
For backups, <source> is the database (= database string) you want to back up, <destination> is the path and file name of the backup file. The usual extension for the backup file is .fbk for Firebird and .gbk for InterBase.
Only SYSDBA or the database owner can perform a backup. For multi-file databases, specify only the name of the first file as the database name.
For restores, <source> is the backup path file name and <destination> is the name of the database (= database string) that is to be built up from the backup file. You will have to specify the -C option for restore.
-nodbtriggers |
Suppresses Database Triggers from running [Firebird 2.1] |
-pas[sword] <password> |
Database password |
-fet[ch_password] <filename> |
Instead of -password: Fetch password from the file so it is not visible in the command line. When <filename> is stdin, the user will be prompted for the password. [Firebird 2.5] |
-m[etadata] |
Only backs up/restores metadata (schema). No table data will be re/stored. |
-role <role> |
Connect as role |
-se[rvice] <hostname[/port]>:service_mgr |
Backup: Creates the backup file on the database server, using the Service Manager. Restore: Creates the database from a backup file on the server, using the Service Manager. The backup file, database file, and log file all must reside on the filesystem of this server. So all path names (for database file, backup file, log file) must be specified as viewed from the server's perspective, even when this is called from a remote machine. |
-u[ser] <username> |
Database user name |
-v[erbose] or -v[erify] |
Verbose output of what GBAK is doing |
-y <filename> |
Create Logfile: Redirect all output messages to <filename> The file must not exist before running GBAK! So you have to delete it before the GBAK call. When you use -se (Service Manager), the logfile will (can only) reside on the server's filesystem. |
-y suppress |
Quiet mode: suppress any output |
-z |
Show GBAK version and server version |
-b[ackup_database] |
Back up. This switch is optional. |
-co[nvert] |
Converts external tables to internal tables |
-e[xpand] |
Creates an uncompressed backup |
-fa[ctor] n |
Blocking factor for tape device |
-g[arbage collect] |
Does not perform garbage collection during backup, so the backup will be faster. When you plan to da a Restore or Sweep anyway after the backup. |
-ig[nore] |
Ignores checksum errors while backing up |
-l[imbo] |
Ignores limbo transactions while backing up |
-m[etadata] |
Only backs up metadata (schema). No table data will be stored. |
-nt |
Non-transportable format (use only when you know you will restore on same platform and database version) |
-t[ransportable] |
Creates a transportable backup (transportable between platforms and server versions). This is the default. |
-bu[ffers] |
Set cache size for restored database |
-c[reate_database] |
Restore to a new database (the target database file MUST NOT exist) |
-fix_fss_d[ata] <charset> |
Repair malformed UNICODE_FSS data during Restore [Firebird 2.5] |
-fix_fss_m[etadata] <charset> |
Repair malformed UNICODE_FSS metadata during Restore [Firebird 2.5] |
-i[nactive] |
All indexes will be restored as INACTIVE |
-k[ill] |
Does not create shadows that are defined in the backup |
-m[etadata] |
Only restores metadata (schema). No table data will be restored. |
-mo[de] read_write |
Restores to a read/write database (This is the default) |
-mo[de] read_only |
Restores to a read-only database |
-n[o_validity] |
Does not restore validity constraints. So you can restore data that does not meet these constraints and could not be restored otherwise. |
-o[ne_at_a_time] |
Usually the restore takes place in one single transaction for the whole database. This switch puts a commit after each table. So you can use this to partially restore databases with corrupt table data. |
-p[age_size] <size> |
Sets page size of new database. <size> can be one of 1024, 2048, 4096, 8192. Default is 1024. |
-r[eplace_database] |
Restores over an existing database. This can only be performed by SYSDBA or the owner of the database that is overwritten. Do NOT restore over a database that is in use! [Firebird 1.0, 1.5] |
-rep[lace_database] |
New abbreviation for the old -replace_database [Firebird 2.0 and later] |
-r[ecreate_database] o[verwrite] |
[Firebird 2.0 and later] Restores over an existing database. This can only be
performed by SYSDBA or the owner of the database that is overwritten. Firebird will
prevent you from restoring over a database that is in use—but be careful anyway!
-r is equivalent to -c. Only the "overwrite" option will restore over an existing database (meaning that "-r o" is equivalent to "-rep"). |
-use_[all_space] |
Normally, on restore, database pages will be filled to about 80 %. With the use_all_space option, database pages will be filled to 100 %. (Useful for read-only databases which will see no more modifications.) |
gbak -v -t -user SYSDBA -password "masterkey"
dbserver:/db/warehouse.fdb c:\backups\warehouse.fbk
del c:\backups\warehouse.log
gbak -v -t -user SYSDBA -password masterkey -y c:\backups\warehouse.log
dbserver:/db/warehouse.fdb c:\backups\warehouse.fbk
gbak -c -v -user SYSDBA -password masterkey
c:\backups\warehouse.fbk dbserver:/db/warehouse2.fdb
gbak -c -r -v -user SYSDBA -password masterkey
c:\backups\warehouse.fbk dbserver:/db/warehouse.fdb
gbak -r o -v -user SYSDBA -password masterkey
c:\backups\warehouse.fbk dbserver:/db/warehouse.fdb
gbak -c -v -mode read_only -use_all_space -user SYSDBA
-password masterkey c:\backups\warehouse.fbk c:\files\warehousedb.fdb
gbak [options] <database> <target file 1> <size 1>
<target file 2> <size 2> ... <target file n>
NOTE: Do not specify a size for the last file. It will always be filled to take up what is left over, no matter how large.
Size can be given in bytes (8192), kilobytes (1024k), megabytes (5m), or gigabytes (2g)
gbak -c [options] <source file 1> <source file 2> ...
<source file n> <database>
gbak -c [options] <source file> <db file 1> <size 1>
<db file 2> <size 2> ... <db file n>
NOTE: Do not specify a size for the last database file. It can always grow unlimited to take up the rest.
Size can be given in bytes (8192), kilobytes (1024k), megabytes (5m), or gigabytes (2g)
gbak -c [options] <source file 1> <source file 2>
... <source file n> <db file 1> <size 1>
<db file 2> <size 2> ... <db file n>
Use this when you want to test the physical and logical health of your database or to copy a database to another location using a proper Backup-&-Restore cycle.
Note that stdin and stdout get special treatment from gbak here, so don't use "/dev/stdin" or "/dev/stdout".
gbak -c [options] <source database> stdout | gbak -r [options] stdin <target database>
You can perform a regular backup of the security database. The security database resides in the Firebird directory. It is named
Firebird 2.x does not allow regular database access to the security database. Its name is now security2.fdb
The only way to access the security database is via the Service Manager. As GBAK can also use the Service Manager (Option -se), you can run a backup using this option. However, the backup file will also be written to the server machine.
General Syntax:
gbak <options> -user <username> -password <password> -service <servername>:service_mgr <sec-db-name> <backup-filename>
Example:
gbak -v -t -user sysdba -password masterkey -service dbserver:service_mgr c:\Programme\Firebird2\security2.fdb C:\Backups\Security2.fbk
(in this case, Security2.fbk will be written to the C:\Backups folder of dbserver!)
When your database server listens on a non-default port:
gbak -v -t -user sysdba -password masterkey -se dbserver/3051:service_mgr c:\Programme\Firebird2\security2.fdb C:\Backups\Security2.fbk
In Firebird 2.1 there is a new option -no_dbtriggers that suppresses database triggers from running during backup/restore. So you can suppress any unwanted behaviour for the connection that GBAK needs to establish for the database.
It is not possible to restore the security database while Firebird is running. In case your security database gets destroyed, this is what you can do:
There is a special chapter "Dealing with the New Security Database" about this in the Firebird 2.0 Release Notes, which get installed to the doc subdirectory of your Firebird directory. You should also take a look at the misc\upgrade\security\security_database.txt file, which explains in detail how to do it.
Stefan Heymann, last edit 2013-09-10
2013-08-11: Thanks to Vítězslav Švejdar (CZ) for some valuable hints to improve this page
This documentation is licensed under (choose your favorite): GPL, LGPL, CC, IDPL, GFDL, BSD, (did I forget one?)