Section: User Commands (1)
gbak -b [backup option ...] [common option ...] source target
gbak is the tool for managing Firebird database backup and restore.
In backup mode source is an existing database path (may include server name) and target is backup file name. It could be also a special device name like /dev/stdout (to redirect backup data to STDOUT) or /dev/st to put the backup on tape.
In restore mode source is existing backup file (or special device like /dev/stdin for STDIN or /dev/st to get the backup from tape) and target is path to firebird database and may include server name.
All options can be abbreviated. Below both full versions of options and the shortest possible versions are given.
Report each action.
Convert external tables into tables.
Normally external tables are ignored during backup and restore. With -convert option external tables are included in the backup as any other regular table. When such a backup is restored, these previously external tables are created as regular tables.
Inhibit garbage collection.
Normally Firebird runs a garbage collector when reading through the tables. Since the backup process reads all the tables, this forces garbage collection of the whole database. In case you make the backup just to restore it over the existing database this garbage collection is unnecessary. Another reason to use this options is if a garbage collection is engaged by other means - either by using gfix or the automatic sweep. Using this switch speeds up the backup process and also can help in some cases of backing up damaged databases.
Ignore records with bad checksums.
Ignore transactions in limbo.
Backup metadata only.
With this option only the metadata is written to the backup. This includes all tables/views/triggers/indexes/stored procedures/domains/generators etc. No table data is included in backup. Such a backup is useful for creating an "empty" copy of a database.
Use non-transportable backup format.
By default a "transportable" backup format is used. This means you can backup a database on little-endian machine and restore it on big-endian machine and vice versa. By using -nt the backup is only useful on machines with the same "endianness".
Turn on restore mode.
Do not create shadows when restoring.
Restore database with given access.
Normally, Fireburd reserves some space on each data page for further use. This reserved space is used for newly inserted data and for keeping older versions of the data. Having space reserved for this purpose "near" to the data speeds up modifications. If the database will used mainly for read operations, specifying -use_all_space will save some space.
When restoring metadata, in case it is not valid UTF8, try to convert from the specified character set. Useful when table descriptions are given in some national non-UTF8 encoding, which was possible with Firebird before version 2.5
When restoring table data, in case a column defined with UNICODE_FSS character set contains no valid UTF8 (which was possible with versions of Firebird prior to 2.5), try to convert the data from the specified character set.
RESTORING TO MULTIPLE-FILE DATABASE
Previously, Firebird was not able to work with 64-bit file pointers thus limiting databases to (about) 2GB of size per database.
Since 2GB is not much of data since years, there is a mechanism for spreading the database into multiple files. This way you can have multiple 2GB files, containing all your data.
When restoring to multiple-file database the target argument is of form: file_1 pages_1 file_2 pages_2 ... file_N-1 pages_N-1 file_N
Each pages_n specifies at most how many pages to put in file_n. Last in the list is a filename without page limit - it will contain all the pages not fit in file_N-1. Note that pages_n is measured in pages, not bytes so the maximum possible number depends on page size.
Imagine you have a filesystem (or an ancient OS) which only supports 32-bit file pointers. To play safe, you decide to split your database on 2GB files. If the page size for the database is 8192, then each file can have up to 2*1024*1024*1024/8192 = 262144 pages.
As all other Firebird utilities, gbak accepts following environment variables:
- default value for -user option:
- default value for -role option:
- default value for -password option:
In all examples -user, -role and -password options are omitted for clarity. In a real world situation they (or their corresponding enviromnemt variables) should be used.
Note that filename extensions used here are just recommended. Using unified extensions scheme helps guess file type just by looking at its extension.
Here are some commonly used extensions:
- Firebird database:
- Firebird database, legacy extension from the days when Firebird was Interbase. gdb actually comes from Grotton database, named after the company that created the software back in 1984.:
- Second file of multi-file database:
- Third file of multi-file database:
- N-th file of multi-file database:
- Firebird backup file:
- Legacy extension for backup file:
- Gzipped backup file:
Backup a database into a compressed format:
Restore a database into new filename:
This manpage was written by Damyan Ivanov <[email protected]> for Debian GNU/Linux but may be used by others. Permission is granted to use this document, with or without modifications, provided that this notice is retained. If we meet some day, and you think this stuff is worth it, you can buy me a beer in return.
© 2004,2007 Damyan Ivanov