=head1 NAME

gbak - Backup and restore Firebird databases

=head1 SYNOPSIS

gbak -b [I<backup option>...] I<source> I<target>

gbak -c [I<restore option>...] I<source> I<target>

gbak -r [I<restore option>...] I<source> I<target>

=head1 DESCRIPTION

B<gbak> is the tool for managing Firebird database backup and restore.

In backup mode I<source> is an existing database path (may include server name)
and I<target> is backup file name. It could be also a special name like
C<stdout> (to redirect backup data to the standard output) or /dev/st to put
the backup on tape.

In restore mode I<source> is existing backup file (or special name like
C<stdin> for the standard input or /dev/st to get the backup from tape, etc.)
and I<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.

=head2 COMMON OPTIONS

=over

=item B<-user> I<username>

User name to use when connecting to database. Overrides the setting in the
C<ISC_USER> environment variable.

=item B<-ro[le]> I<role_name>

SQL role to use when connecting to database. Overrides the C<ISC_ROLE>
environment variable.

=item B<-pas[sword]> I<password>

Password to use when connecting to database. Overrides the C<ISC_PASSWORD>
environment variable.

=item B<-se[rvice]>

Use the services manager when talking to a database.

=item B<-st[atistics]> I<T|D|R|W>

Show some statistics. Each flag enables a function:

=over

=item B<T>

Time from start

=item B<D>

Delta time

=item B<R>

Page reads

=item B<W>

Page writes

=back

=item B<-v[erify]>

Report each action.

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

=item B<-y> I<path>

Redirect status/error messages to the given path.

=item B<-z>
Report full version number before doing anything else.

=back

=head2 BACKUP OPTIONS

=over

=item B<-b[ackup_database]>

Turn on backup mode

=item B<-co[nvert]>

Convert external tables into ordinary (internal) tables. Normally external
tables are ignored during backup and restore. With the B<-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.

=item B<-fa[ctor]> I<num>


Blocking factor. Output is written in blocks of I<num> bytes. Useful when
backing up to a tape.

=item B<-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.

=item B<-ig[nore]>

Ignore records with bad checksums.

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

=item B<-l[imbo]>

Ignore transactions in limbo.

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

=item B<-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 the backup. Such a backup is useful for creating an
"empty" copy of the database.

=item B<-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 the B<-nt> option the backup is only useful on machines with
the same "endianness".

=item B<-ol[d_descriptions]>

Ssave old-style metadata descriptions.

=back

=head2 RESTORE OPTIONS

=over

=item B<-c[reate_database]>

Turn on restore mode.

The I<target> database will be created and must not already exist.

=item B<-rep[lace_database]>

Like the B<-create_database> option, but the target is overwritten if it
exists.

=item B<-r[ecreate_database]> B<o[verwrite]]>

Like the B<-create_database> option, but by adding C<overwrite> one can force
replacement of the target database.

=item B<-bu[ffers]> I<num>

When creating target database, ignore information about database buffers stored
in the backup and use specified number of buffers.

=item B<-e[xpand]>

Normally, Firebird uses RLE compression for strings when storing them
on disk. This option turns this compression off.

=item B<-i[nactive]>

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

=item B<-k[ill]>

Do not create shadows when restoring.

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

=item B<-mo[de]> I<access>

Restore database with given I<access> mode.

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

=item B<-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.

=item B<-o[ne_at_a_time]>

Commit restoring transaction after each table.

=item B<-p[age_size]> I<num>

Override page size stored in the backup. Valid values for I<num> are 1024,
2048, 4096, 8192, 16384 and 32768.

=item B<-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 B<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.

B<-fix_fss_metadata> I<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.

=item B<-fix_fss_data> I<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.

=back

=head2 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 the data.

When restoring to multiple-file database the target argument is of form:
I<file_1> I<pages_1> I<file_2> I<pages_2> ... I<file_N-1> I<pages_N-1>
I<file_N>

Each I<pages_n> argument specifies at most how many pages to put in I<file_n>.
Last in the list is a filename without page limit - it will contain all the
pages that don't fit in I<file_N-1>. Note that I<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.

B<NOTE>: On a recent OS and filesystem Firebird can use 64-bit file pointers
rendering multi-file databases unnecessary.

=head1 ENVIRONMENT

As all other Firebird utilities, B<gbak> accepts the following environment
variables:

=over

=item B<ISC_USER>

Default value for the B<-user> option.

=item B<ISC_ROLE>

Default value for the B<-role> option.

=item B<ISC_PASSWORD>

Default value for the B<-password> option.

=back

=head1 EXAMPLES

In all examples the B<-user>, B<-role> and B<-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 but is not mandatory.

Here are some commonly used extensions:

=over

=item B<.fdb>

Firebird database

=item B<.gdb>

Firebird database, legacy extension from the days when Firebird was Interbase.
C<gdb> actually comes from Grotton database, named after the company that
created the software back in 1984.

=item B<.fdb.2>

Second file of multi-file database.

=item B<.fdb.>I<N>

I<N>-th file of multi-file database.

=item B<.fbk>

Firebird backup file.

=item B<.gbk>

Legacy extension for backup file.

=item B<.fbk.gz>

Gzipped backup file.

=back

=head2 Backup a database into a compressed format

 gbak -b db-srv:/database.fdb stdout | gzip > /file.fbk.gz

=head2 Restore a compressed backup into a new filename

 zcat /file.fbk.gz | gbak -c stdin db-srv:/new-database.fdb


=head1 COPYRIGHT AND LICENSE

Copyright (c) 2004,2007 Damyan Ivanov E<lt>dmn@debian.orgE<gt>.

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.
