|Firebird Documentation Index → Gbak - Firebird Backup & Restore Utility → Command-line Options|
When running gbak in backup or restore mode, there are a number of options which apply to either mode. These are:
This switch displays the command line options and switches. It
replaces the old method in which you had to supply an invalid switch
-help below) in order to see the list of
Firebird 2.5 onwards.
-FE[TCH_PASSWORD] <password file name> |
stdin | /dev/tty
This switch causes the password for the appropriate user to be
read from a file as opposed to being specified on the command line.
The file name supplied is not in quotes and
must be readable by the user running
gbak. If the file name is specified as
stdin, then the user will be prompted for a
password. On POSIX systems, the file name
/dev/tty will also result in a prompt
for the password.
Firebird 2.5 onwards.
This switch causes your data to be ignored and not backed up or restored. In a backup, only the database meta data are backed up. When used in a restore, any data in the dump file will not be restored. This switch can be used when creating database clones which are required to contain only the tables, indices etc but none of the data.
Supplies the password for the username specified above. This
need not be supplied if
variable exists and has the correct value.
-RO[LE] <SQL role name>
Allows the specification of the role to be used by the connecting user. Not of much practical use and is not normally used in practice.
Allows the username of the SYSDBA or database owner user to be
specified if the database is to be backed up, or, in the case of a
restore (with the
specified), any valid username can be specified. This need not be
ISC_USER environment variable exists and
has a correct value for the username.
Databases can only be backed up by SYSDBA or the database
owner. A restore can also be carried out by SYSDBA or the database
owner, however, if the
-c(reate) switch is
used, any validated username can create a new
database from a backup file.
Normally gbak operates quietly with
no information written to the display. This switch reverses that
situation and causes lots of information to be displayed. The
default is to display the output to the screen, but you can redirect
the output to a log file using the
-Y <filename> or the text
Used in conjunction with the
switch to redirect status messages to a file or device, rather than
the screen, or to suppress them altogether.
-y suppress is used, then no
information will be written to screen regardless of whether
-v[erify] is specified.
If a filename is given and the
-v[erify] switch is specified, the file will
be written to record progress, errors etc.
All known documentation on this switch mentions that the
text should be
"suppress". This is an error in the
documentation as the source code for
gbak shows that the switch must be
The log file must not exist. If it does, the backup or recovery operation will fail:
tux> rm employee.log tux> gbak -backup employee.fdb employee.fbk -y employee.log -v tux> ls -l employee.log -rw-r--r-- 1 firebird firebird 21610 2010-08-04 10:22 employee.log tux> gbak -backup employee.fdb employee.fbk -y employee.log -v gbak:cannot open status and error output file employee.log
This option displays some information about the version of gbak being used, and optionally, a database. To obtain the version of gbak only, run the command as follows:
tux> gbak -z gbak:gbak version LI-V22.214.171.124074 Firebird 2.5 gbak: ERROR:requires both input and output filenames gbak:Exiting before completion due to errors tux> echo $? 1
This displays the current version of gbak, and after displaying a couple of error messages, exits with an error code of 1 as shown above by the echo command. This method does not attempt to backup any databases and does not require a username and password to be defined or supplied.
If you wish to display the version number of the gbak utility and also details of database, you must supply a valid database name and backup filename, as follows:
tux> gbak -z employee employee.fbk -user sysdba -password secret gbak:gbak version LI-V126.96.36.19985 Firebird 2.1 gbak: Version(s) for database employee Firebird/linux (access method),version LI-V188.8.131.5285 Firebird 2.1 Firebird/linux (remote server),version LI-V184.108.40.20685 Firebird 2.1/tcp (tux)/P11 Firebird/linux (remote interface), version LI-V220.127.116.1185 Firebird 2.1/tcp (tux)/P11 on disk structure version 11.1 tux> echo $? 0
You will note from the above that a valid username and
password must be defined on the command line, or by the use of
ISC_PASSWORD. This version of the command will exit
with a error code of zero.
This method of calling gbak will make a backup of the database. If your database is large, this can take some time to complete and the backup file specified will be overwritten if it already exists. Beware.
The output above has been slightly abbreviated to allow it to fit the page width for a pdf.
Help is actually not a valid option, but can be used to display the following screen of information as output from gbak in Firebird 2.0:
gbak:legal switches are: -B[ACKUP_DATABASE] backup database to file -BU[FFERS] override page buffers default -C[REATE_DATABASE] create database from backup file -CO[NVERT] backup external files as tables -E[XPAND] no data compression -FA[CTOR] blocking factor -G[ARBAGE_COLLECT) inhibit garbage collection -I[NACTIVE] deactivate indexes during restore -IG[NORE] ignore bad checksums -K[ILL] restore without creating shadows -L[IMBO] ignore transactions in limbo -M[ETA_DATA] backup metadata only -MO[DE] <access> "read_only" or "read_write" access -N[O_VALIDITY] do not restore database validity conditions -NOD[BTRIGGERS] do not run database triggers -NT Non-Transportable backup file format -O[NE_AT_A_TIME] restore one table at a time -OL[D_DESCRIPTIONS] save old style metadata descriptions -P[AGE_SIZE] override default page size -PAS[SWORD] Firebird password -R[ECREATE_DATABASE] [O[VERWRITE]] create (replace if O[VERWRITE] used) database from backup file -REP[LACE_DATABASE] replace database from backup file -RO[LE] Firebird SQL role -SE[RVICE] use services manager -T[RANSPORTABLE] transportable backup -- data in XDR format -USE_[ALL_SPACE] do not reserve space for record versions -USER Firebird user name -V[ERIFY] report each action taken -Y <path> redirect/suppress status message output -Z print version number
The explanation of the
switch implies that it is useful in a backup situation only. This is
not the case as it can also be used on a restore.
From Firebird 2.5 onwards, there is a new
-? switch to display the list of valid options.
The output has slightly different layout and a couple of new options
have been added:
gbak:legal switches are: -B(ACKUP_DATABASE) backup database to file -C(REATE_DATABASE) create database from backup file (restore) -R(ECREATE_DATABASE) [O(VERWRITE)] create (or replace if OVERWRITE used) database from backup file (restore) -REP(LACE_DATABASE) replace database from backup file (restore) gbak:backup options are: -CO(NVERT) backup external files as tables -E(XPAND) no data compression -FA(CTOR) blocking factor -G(ARBAGE_COLLECT) inhibit garbage collection -IG(NORE) ignore bad checksums -L(IMBO) ignore transactions in limbo -NOD(BTRIGGERS) do not run database triggers -NT Non-Transportable backup file format -OL(D_DESCRIPTIONS) save old style metadata descriptions -T(RANSPORTABLE) transportable backup -- data in XDR format gbak:restore options are: -BU(FFERS) override page buffers default -FIX_FSS_D(ATA) fix malformed UNICODE_FSS data -FIX_FSS_M(ETADATA) fix malformed UNICODE_FSS metadata -I(NACTIVE) deactivate indexes during restore -K(ILL) restore without creating shadows -MO(DE) <access> "read_only" or "read_write" access -N(O_VALIDITY) do not restore database validity conditions -O(NE_AT_A_TIME) restore one table at a time -P(AGE_SIZE) override default page size -USE_(ALL_SPACE) do not reserve space for record versions gbak:general options are: -FE(TCH_PASSWORD) fetch password from file -M(ETA_DATA) backup or restore metadata only -PAS(SWORD) Firebird password -RO(LE) Firebird SQL role -SE(RVICE) use services manager -USER Firebird user name -V(ERIFY) report each action taken -Y <path> redirect/suppress status message output -Z print version number
The parentheses shown in the above indicates how much of the
switch name you need to use in order to avoid ambiguity. Once you have
specified the absolute minimum - the part before the opening '[' - you
can use as much of what follows as you wish. For example, to use the
-b[ackup_database] switch the minimum you must
supply on the command line is
-b but anything
-backup_database will be accepted.
-help switch like this, or any
other invalid switch, will cause gbak to exit
with an error code of 1 on Linux and Windows.
When running gbak, if the first filename is a database name, or database alias then gbak will default to taking a backup of the database in transportable format. The backup file will be named as per the second file name supplied on the command line.
You may, if you wish, send the output to standard output rather than a backup file. In this case, you must specify stdout as the dump file name. This is not really of much use, unless you wish to pipe the dump through a tool to modify it in some way. You can pipe the output directly to a gbak restore operation to clone a database without needing an intermediate dump file. An example is given later in this manual.
When carrying out a backup of a database, the following switches, in addition to the common ones above, will be of use:
This switch is used whenever you wish to take a backup of a database.
This switch causes any tables, defined as external, to be backed up as if they were normal (non-external) tables. When this dump file is used to restore a database, the tables that were external in the original database will no longer be external.
Normally, gbak will compress the output file. This switch prevents that compression from taking place.
-FA[CTOR] <block size>
If backing up to a physical tape device, this switch lets you specify the tape's blocking factor.
The use of this switch prevents Firebird's garbage collection from taking place while gbak is running. Normally gbak connects to the database as any other connection would and garbage collection runs normally. Using this switch prevents garbage collection from running during the course of the backup. This can help speed up the backup.
This switch causes gbak to ignore bad checksums in the database. This can be used to attempt to backup a database that failed due to checksum errors. There is no guarantee that the data will be usable though, so it is best to take other precautions to preserve your data.
If you have a two-phase transaction (across two different
databases) that failed because a server died before the commit, but
after the changes were made, you have a limbo transaction. This
switch forces the backup to ignore data from such broken
transactions. It should not be used for normal backups and only
used, like the
-ig[nore] switch to attempt to
recover from a failure.
This switch turns off the
-t[ransportable] switch (which is on by
default) and causes the dump file to be created using platform
dependent formats. If you use this switch to create a backup then
you can only restore the backup on a similar platform. You cannot,
for example, take a dump file from Linux over to a Windows
This switch is unlikely to be used. It has been deprecated. Its purpose is to force the backup to be made using the older InterBase versions' format of meta data descriptions.
-RO[LE] <role name>
This switch causes gbak to backup a
remote database via the service manager. This causes the backup file
to be created on the remote server, so the path format and filename
must be valid on the remote server. The servicename is currently
always the text
You can use this option to connect to a locally hosted database as well. If you do, taking a backup using this option can run quicker than accessing the database directly. See the section below on speeding up backups.
The default dump file format is transportable. Transportable backup files are written in a format known as external data representation (XDR) format and it is this format which allows a dump taken on a server of one type to be successfully restored on a server of another type.
-Y <full name of log file> or the text
When running a
gbak command, if
the first filename is a database backup file name
then gbak will
default to running a recovery of the database provided that you
specify one of
-r[ecreate_database] in order to make your
intentions clear. The database will be restored to whatever file name
is specified as the second file name on the command line..
You may, if you wish, read the dump data directly from standard input rather than a backup file. In this case, you must specify stdin as the dump file name. You could pipe a gbak dump operation directly to a gbak restore operation to clone a database without needing an intermediate dump file. An example is given later in this manual.
When carrying out a restore or replacement of a database, the following switches, in addition to the common ones above, will be of use:
-BU[FFERS] <number of
This switch sets the default database cache size (in number of database pages) for the database being restored. If a database is being overwritten then this setting will overwrite the previous setting for the cache size.
This switch causes a new database to be created from the
backup file. The database file must not exist or the restore will
fail. Either this switch or
-r[ecreate_database] must be
This switch forces gbak to fix malformed UNICODE_FSS character data during a restore.
This switch, and the following one, should not be required under normal circumstances. However, if a restore operation fails with a "malformed string" error, the message output from gbak will refer the user to one or both of these switches to fix the malformed UNICODE_FSS data or meta data as appropriate.
Firebird 2.5 onwards.
This switch forces gbak to fix malformed UNICODE_FSS metadata during a restore.
This switch, and the preceding one, should not be required under normal circumstances. However, if a restore operation fails with a "malformed string" error, the message output from gbak will refer the user to one or both of these switches to fix the malformed UNICODE_FSS data or meta data as appropriate.
Firebird 2.5 onwards.
This switch can be used to restore a database when a previous restore attempt failed due to index errors. All indexes in the restored database will be inactive.
This switch restores the database but doesn't recreate any shadow files that existed previously.
This switch allows the database being restored to be set to the given access mode when opened. By default, the mode is taken from the database that was dumped.
This switch is similar to the
-i[nactive] switch above, except, it disabled
all check constraints in the restored
New switch from Firebird 2.1 which prevents the database triggers from firing on a restore. Database triggers are a new feature in Firebird 2.0 onwards and are different from table triggers which will continue to fire.
This switch causes the restore to restore one table at a time.
This can be useful when a previous restore failed due to data
errors. Normally, a restore takes place in a single transaction with
a single commit at the end of the restore. If the restore is
interrupted for any reason, an empty database is the end result.
-o[ne_at_a_time] option uses a
transaction for each table and commits after each table has been
-P[AGE_SIZE] <new page
Use this switch to change the default database page size. By default, the database is restored using a page size the same as the one that was in use when the database was dumped.
New from Firebird 2.x. Create (or replace if
o[verwrite] is used) the named database from
the backup file. The database filename should not already exist or
an error will occur. This is not the case if the
o[verwrite] option is also used.
This is a new switch and is deliberately abbreviated to
-r to try to prevent unsuspecting DBAs from
overwriting an existing database thinking that the
-r was abbreviated from
-restore. Now, it takes special effort to
manage this especially as
-restore was never
actually a valid switch;
-r was in fact an
-replace_database and it did
this by first deleting the existing database
file and then recreating it from the
is effectively the same as using
Replace database from backup file. This switch used to be
-r in previous (to Firebird
2.x) versions. This switch will be removed in a version of Firebird
later than 2.1.3 (where it still exists). You are advised to use the
-r[ecreate_database] o[verwrite] switch
Use the services manager on a remote database to restore a
remote database. The servicename is currently always the text
You can use this option to connect to a locally hosted database as well. If you do, restoring a backup using this option can run quicker than accessing the database directly. See the section below on speeding up restores.
This switch forces the restore to use 100% of each database page and thus not leave any room for changes. If you omit this switch, some space will be kept free for subsequent changes. Using this switch is likely to be only of practical use where the database is created and used in read-only mode and no updates to existing data are required.
Once a database has been restored with this option specified, all database pages will be filled to 100% and no free space will be left for updates. Use of this switch set a flag in the database header page to signal that all pages are to be filled to 100% - this applies to any new pages created after the restore.
You can override this setting, using gfix -use full
| reserve database_name where
full uses 100% of each page and
reserve reserves some space for subsequent
updates. See the gfix manual for more
-Y <name of log file>
|Firebird Documentation Index → Gbak - Firebird Backup & Restore Utility → Command-line Options|