gbak - Online in the Cloud

PROGRAM:

NAME

gbak — Backup/restore Firebird database

SYNOPSIS

gbak -b [backup option ...] [common option ...] source target

gbak -c|-r [restore option ...] [common option ...] source target

DESCRIPTION

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.

COMMON OPTIONS

-user username
User name to use when connecting to database. Overrides environment variable. See
ENVIRONMENT.

-ro[le] role_name
SQL role to use when connecting to database. Overrides environment variable. See
ENVIRONMENT.

-pas[sword] password
Password to use when connecting to database. Overrides environment variable. See
ENVIRONMENT.

-se[rvice]
Use services manager when talking to a database.

-v[erify]
Report each action.

Displays verbose information about what metadata is being processed, what table is being
backed up/restores and how many records are processed.

-y path
Redirect status/error messages to the given path.

-z
Report full version number before doing anything else.

BACKUP OPTIONS

-b[ackup_database]
Turn on backup mode.

-co[nvert]
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.

-fa[ctor] num
Blocking factor. Output is written in block of num bytes. Useful when backing up to a
tape.

-g[arbage_collect]
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.

-ig[nore]
Ignore records with bad checksums.

This option should be used only when backing up damaged databases.

-l[imbo]
Ignore transactions in limbo.

This switch causes the backup process to ignore transactions in limbo state.

-m[etadata_only]
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.

-nt
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".

-ol[d_descriptions]
save old-style metadata descriptions

RESTORE OPTIONS

-c[reate_database]
Turn on restore mode.

target database will be created and must not already exist.

-r[ecreate_database] [o[verwrite]]
Like -create_database, but by adding overwrite one can force replacement of the target
database.

-rep[lace_database]
Like -create_database, but the target is overwritten if it exists.

-bu[ffers] num
When creating target database, ignore information about database buffers stored in the
backup and use specified number of buffers.

-e[xpand]
Normally, Firebird uses RLE compression for strings when storing them on disk. This option
turns this compression off.

-i[nactive]
Restore indexes in inactive state. This can be used to restore a backup, containing data
inconsistent with foreign key/unique constraints.

-k[ill]
Do not create shadows when restoring.

Normally and database shadows are created during restore. This option inhibits this.

-mo[de] access
Restore database with given access.

Valid values for access are read_only and read_write. Default is to restore the database
with its original access mode.

-n[o_validity]
Restore database without its validity constraints. This includes foreign key, unique and
check constraints. Useful for restoring a backup, containing inconsistent data.

-o[ne_at_a_time]
Commit restoring transaction after restoring each table.

-p[age_size] num
Override page size stored in the backup. Valid values for num are 1024, 2048, 4096, 8192,
16384 and 32768.

-use_[all_space]
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.

This option is particularly useful when restoring a read-only database, since read-only
databases do not need any additional space for back-versions.

-fix_fss_metadata charset
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

-fix_fss_data charset
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.

NOTE
Note that on a recent OS and filesystem Firebird can use 64-bit file pointers rendering
multi-file databases unnecessary.

ENVIRONMENT

As all other Firebird utilities, gbak accepts following environment variables:

ISC_USER default value for -user option

ISC_ROLE default value for -role option

ISC_PASSWORD
default value for -password option

EXAMPLES

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:

.fdb Firebird database

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

.fdb.2 Second file of multi-file database

.fdb.3 Third file of multi-file database

.fdb.N N-th file of multi-file database

.fbk Firebird backup file

.gbk Legacy extension for backup file

.fbk.gz Gzipped backup file

Backup a database into a compressed format:
gbak -b db-srv:/database.fdb /dev/stdout | gzip > /file.fbk.gz

Restore a database into new filename:
zcat /file.fbk.gz | gbak -c /dev/stdin db-srv:/new-database.fdb

Use gbak online using onworks.net services