Firebird’s gbak Backup and Restore Utility

Displays the commandline options and switches.

The parentheses shown in the above indicates how much of the switch name you need to use to avoid ambiguity. In this manual we indicate this with square brackets instead. Once you have specified the absolute minimum — the part before the opening ‘(’ — or ‘[’ — 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 between -⁠b and -⁠backup_database will be accepted.

Crypt plugin name.

The -⁠CRYPT option will generally need to be combined with the -⁠KEYHOLDER and -⁠KEYNAME options.

On backup of a non-encrypted database, the -⁠CRYPT option specifies the encryption plugin to use to encrypt the backup file.

When backing up an encrypted database, specifying -⁠CRYPT is not necessary as by default it will use the same plugin and key as the database itself.

On restore of a non-encrypted backup, the -⁠CRYPT option will encrypt the new database using the specified plugin.

It is not possible to backup an encrypted database to an unencrypted backup file, or to restore an encrypted backup file to an unencrypted database.

Direct IO for backup file(s).

When enabled, gbak creates — on backup, or opens — on restore, the backup file in direct IO (or unbuffered) mode. In this mode, the backup file is not cached by the filesystem cache.

Usually, a backup is written — on backup, or read — on restore, just once, and there is no real benefit from caching its content. Performance should not suffer as gbak uses sequential IO with relatively big chunks.

Direct IO mode is silently ignored if the backup file is written to the standard output, or read from the standard input (i.e. if the backup filename is stdout or stdin).

Fetch password from file (or standard input).

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 filename supplied is not in quotes and must be readable by the user running gbak. If the filename is specified as stdin, then the user will be prompted for a password. On POSIX systems, the filename /dev/tty will also result in a prompt for the password.

Name of a keyholder plugin

The -⁠KEYHOLDER option must be specified to backup an encrypted database, to create an encrypted backup of an unencrypted database, to restore an encrypted backup, or to restore an unencrypted backup to an encrypted database.

It is not possible to backup an encrypted database to an unencrypted backup file, or to restore an encrypted backup file to an unencrypted database.

Name of the key to be used for encryption.

The -⁠KEYNAME option can be used to create an encrypted backup of an unencrypted database, to restore an encrypted backup with a non-default key name, or to restore an unencrypted database to an encrypted database.

This option must generally be combined with -⁠KEYHOLDER and -⁠CRYPT.

It is not possible to backup an encrypted database to an unencrypted backup file, or to restore an encrypted backup file to an unencrypted database.

Perform metadata-only backup or restore.

This switch causes your data to be ignored and not backed up or restored. In a backup, only the database metadata (tables, triggers, etc.) are backed up. When used in a restore, only the database metadata are restored, and any data in the backup 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 no data.

Number of parallel workers to use during backup or restore.

The default number of parallel workers is 1 (one), but — for restore — this is not identical to explicitly specifying -⁠PARALLEL 1.

For backup, this option controls the number of connections used to read user-data. Every additional worker creates its own thread and connection to read data in parallel with other workers. All worker connections share the same database snapshot to ensure a consistent data view across all workers. Workers are created and managed by gbak itself. The database metadata is read by a single thread.

For restore, this option controls the number of connections used to write user-data, and to configure the number of parallel workers used for index creation. Every additional worker creates its own thread and connection to write data in parallel with other workers. The database metadata is still created using a single thread — the “main” connection.

This “main” connection uses DPB tag isc_dpb_parallel_workers to pass the value of switch -⁠PARALLEL to the engine — to use the engine’s ability to build indices in parallel. If the -⁠PARALLEL switch is not specified, gbak will write data using a single thread and will not use DPB tag isc_dpb_parallel_workers. In this case, the engine will use the value of ParallelWorkers in firebird.conf when building indices, i.e. this phase could be run in parallel by the engine itself.

To fully avoid parallel operations when restoring a database, use -⁠PARALLEL 1.

Password for authentication.

This need not be supplied if ISC_PASSWORD environment variable exists and has the correct value.

Role name for privileges.

Allows the specification of the role to be used by the connecting user.

Perform backup or restore through service manager.

This switch causes gbak to backup or restore a remote database via the service manager. This causes the backup file to be created or read on the remote server, so the path format and filename must be valid on the remote server. For Firebird 3.0 and earlier, the servicename must always end in service_mgr.

More details on the syntax of service-name can be found in Remote Backups & Restores.

Exclude table data from backup or restore for matching table names.

The backup or restore skips the data for table(s) matching the SQL regular expression argument. Opposite of -⁠INCLUDE[_DATA]. To skip all data, use -⁠M[ETA_DATA].

The metadata of the table is included, only their data is skipped.

The SQL regular expression syntax is documented in the Firebird 5.0 Language Reference.

Includes table data in the backup or restore for matching table names only.

The backup or restore only includes data for table(s) matching the SQL regular expression argument. Opposite of -⁠SKIP_D[ATA].

The metadata of non-matching tables is included, only their data is skipped.

The SQL regular expression syntax is documented in the Firebird 5.0 Language Reference.

Show statistics.

Show statistics, with options one or more of:

For example, -⁠ST TDRW will display all statistics.

The statistics are only displayed when -⁠V[ERIFY] or -⁠VERBI[NT] is specified.

Use Windows trusted authentication (Win_Sspi).

Username for authentication.

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 -⁠c[reate] switch specified), any valid username can be specified. This need not be supplied if ISC_USER environment variable exists and has a correct value for the username.

Databases can only be backed up by SYSDBA, users with the RDB$ADMIN_ROLE, the database owner, or — since Firebird 4.0 — users with the USE_GBAK_UTILITY system privilege. A restore can also be carried out by SYSDBA or the database owner, however, if the -⁠c(reate) switch is used, any authenticated user can create a new database from a backup file. In Firebird 3.0 and higher, non-admin users need the CREATE DATABASE DDL privilege to be able to restore a database.

Display information on the backup or restore.

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 switch.

This option is mutually exclusive with -⁠VERBI[NT]. Using -⁠verify is the same as specifying -⁠verbint 10000.

Verbose information with explicit interval.

The interval controls at how many records written gbak will output information; in other words, it controls the frequency of the output of “…​ records written” messages. The minimum value is 100.

This option is mutually exclusive with -⁠V[ERIFY]. Using -⁠verify is the same as specifying -⁠verbint 10000.

Write -⁠V[ERIFY] output to a log file.

Used in conjunction with the -⁠v[erify] switch to redirect status messages to a file or device, rather than the screen, or to suppress them altogether.

If -⁠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.

Display version information.

This option displays information about the version of gbak being used, and optionally, a database. To obtain the version of gbak only, run the command as follows:

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:

You will note from the above that a valid username and password must be defined on the command line, or by the use of environment variables ISC_USER and ISC_PASSWORD. This version of the command will exit with a error code of zero.

Backup a database.

Convert external tables to normal tables.

This switch causes any external tables to be backed up as if they were normal (non-external) tables. When this backup file is used to restore a database, the tables that were external in the original database will now be normal tables.

Do not apply RLE compression on backup data.

Normally, gbak will compress the output file. This switch prevents that compression from taking place.

This is a very basic RLE compression with a low compression rate, for better compression, use -⁠ZIP.

Blocking factor.

If backing up to a physical tape device, this switch lets you specify the tape’s blocking factor.

Disable garbage collection.

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.

Ignore bad checksums.

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.

Ignore limbo transactions.

If you have a two-phase transaction (e.g. across two different databases) that failed because a server died before the commit or rollback, but after the changes were prepared, 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.

Disable database triggers during backup.

Prevents the database triggers from firing during a backup. Database triggers are a feature of Firebird 2.0 and higher, and are different from table triggers.

Create non-transportable backup.

This switch turns off the -⁠T[RANSPORTABLE] switch (which is on by default) and causes the backup 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 backup file from Linux over to a Windows server, or from a little-endian system to a big-endian system.

Use old backup description format.

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 metadata descriptions.

Create transportable backup.

The default backup file format is transportable. Transportable backup files are written in a format known as external data representation (XDR) format. It is this format which allows a backup taken on a server of one type to be successfully restored on a server of another type.

Backup file is in zip (zlib) compressed format.

This is a backup-only switch; on restore, the compression is detected and decompressed automatically.

Restore to a new database.

This switch creates a new database from the backup file. The database file must not exist or the restore will fail. Either this switch or -⁠rep[lace_database] or -⁠R[ECREATE_DATABASE] [O[VERWRITE]] must be specified.

Restore to a new database, optionally allowing overwriting an existing database.

Create (or replace if o[verwrite] is used) the named database from the backup file. Unless the O[VERWRITE] option is specified, the database filename should not already exist or an error will occur.

This switch 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; in older versions -⁠r was in fact an abbreviation of -⁠REP[LACE_DATABASE] and it did this by first deleting the existing database and then recreating it from the backup.

Using -⁠r[ecreate_database] o[verwrite] is effectively the same as using -⁠rep[lace_database].

Introduced in Firebird 2.0.

Replace database from backup file, overwriting an existing database if it exists.

This switch used to be abbreviated to -⁠r in Firebird 1.5 and older.

Configure the database page buffer (cache size).

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.

Fix malformed UNICODE_FSS data.

This switch forces gbak to fix malformed UNICODE_FSS character data during a restore.

Malformed string data will be attempted to be read using the specified character set charset-name, and then transformed to UNICODE_FSS. Specifying the wrong character set name may result in logical corruption of your data.

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 metadata as appropriate.

Fix malformed UNICODE_FSS metadata.

This switch forces gbak to fix malformed UNICODE_FSS metadata during a restore.

Malformed metadata string will be attempted to be read using the specified character set charset-name, and then transformed to UNICODE_FSS. Specifying the wrong character set name may result in logical corruption of the strings in your metadata.

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 metadata as appropriate.

Do not activate indexes after restore.

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, and as a consequence all primary key, unique key and foreign key constraints as well.

Kill (do not recreate) shadow database.

This switch restores the database but doesn’t recreate any shadow files that existed previously.

Restore database in read-only or read/write mode.

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 backed up.

Do not enable check constraints.

This switch is similar to the -⁠i[nactive] switch above, except, it disables all check constraints in the restored database.

Restore table data with a transaction per table.

This switch restores data one table at a time, using a transaction per table. 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. Using the -⁠o[ne_at_a_time] option uses a transaction for each table and commits after each table has been restored.

Page size of the restored database.

Use this switch to change the default database page size. By default, the database is restored using the same page size as the original database (as recorded in the backup file).

Depending on the version, valid page sizes are 1024, 2048, 4096, 8192, 16384 and 32768. Support for page sizes 1024 and 2048 was removed in Firebird 2.1. Support for page size 32768 was added in Firebird 4.0.

Configures the replica mode of the restored database.

The replica mode of a database is stored in the backup file. On restore, by default, this replica mode is set for the newly created database.

The -⁠REPLICA switch explicitly sets the replica mode, overriding the value inherited from the backup. For example, NONE will make the database a primary (or normal) database, READ_ONLY marks the database as a read-only replica, and READ_WRITE a read/write replica.

After restore, the replica mode of a database can be changed with gfix -⁠replica { NONE | READ_ONLY | READ_WRITE } <database>.

Replication itself is out of the scope of this manual.

Use all space in page.

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.