=head1 NAME

gbak -- backup /restore Firebird database

=head1 SYNOPSIS

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

B<gbak> -c|-r [I<restore option>...] [I<common option>...] I<source> I<target>

=head1 DESCRIPTION

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

In backup mode I<source> is the path to an existing database and I<target> is
the backup file name. If I<target> is C<stdout>, the backup is sent to the
standard output.

In restore mode I<source> is an existing backup file and I<target> is the path
to a firebird database. If I<source> is C<stdin>, the backup data is expected
on the standard input.

=head1 COMMON OPTIONS

Most options can be abbreviated. Below are given the shortest abbreviations as
well as the full versions.

=over

=item B<-user> I<string>

User name to use when connecting to the database.

=item B<-ro> I<string>

=item B<-role> I<string>

SQL role to use when connecting to theh database.

=item B<-pas> I<string>

=item B<-password> I<string>

Password to use when connecting to the database.

=item B<-se>

=item B<-service>

Use services manager when talking to the database.

=item B<-v>

=item B<-verify>

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<string>

Redirects status/error messages to the given path.

=item B<-z>

Prints full program version number before doing anything else. Prints server
and database version information after connecting to the database.

=back

=head1 BACKUP OPTIONS

=over

=item B<-b>

=item B<-backup_database>

Turns on backup mode.

=item B<-co>

=item B<-convert>

Converts external tables into 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> I<number>

=item B<-factor> I<number>

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

=item B<-g>

=item B<-garbage_collect>

Inhibits 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. Using this switch speeds up the backup process and also
can help in some cases of backing up damaged databases.

=item B<-ig>

=item B<-ignore>

Ignores records with bad checksums.

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

=item B<-l>

=item B<-limbo>

Ignores transactions in limbo.

=item B<-m>

=item B<-metadata_only>

Backs up metadata only. No table content is included in the backup.

=item B<-nt>

Uses non-transportable backup format.

Non-transportable backups can be restored only on machines using the same byte
order.

=item B<-o>

=item B<-old_descriptions>

Saves old-style metadata descriptions.

=back

=head1 RESTORE OPTIONS

=over

=item B<-c>

=item B<-create>

Turns on restore mode.

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

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

=item B<-recreate_database> [B<overwrite>]

Like B<-create_database>, but by adding C<overwrite> any existing database is
overwritten.

=item B<-rep>

=item B<-replace_database>

Turns on restore mode. Target database is overwritten if it exists.

=item B<-bu> I<number>

=item B<-buffers> I<number>

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

=item B<-e>

=item B<-expand>

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

=item B<-i>

=item B<-inactive>

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

Note that since version 3.0 gbak leaves any problematic indices in inactive
state automatically.

=item B<-k>

=item B<-kill>

Does not restore database shadow files.

=item B<-mo> I<access>

=item B<-mode> I<access>

Restores the database with given I<access>.

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

=item B<-n>

=item B<-no_validity>

Restores the database without its validity constraints. This includes foreign
key, unique and check constraints. Useful for restoring a backup, containing
inconsistent data.

=item B<-o>

=item B<-one_at_a_time>

Commits restoring transaction after each table.

=item B<-p> I<number>

=item B<-page_size> I<number>

Override page size stored in the backup. Valid values are 1024,
2048, 4096, 8192, 16384 and 32768.

=item B<-use_>

=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 be used mainly for read
operations, specifying this option will save disk space.

=item B<-fix_fss_metadata> I<string>

When restoring metadata, in case it is not valid UTF8, try to convert it 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<string>

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

When the I<target> argument is in the form I<file_1> I<pages_1> ... I<file_N>, the restored database is written in several files with I<file_i> not bigger than I<pages_i> pages. This may be useful if the file system that holds the database file can't handle files above certain size.

B<Note 1>: the file size limit is in B<pages>.

B<Note 1>: there is no limit on the size of the last file.

=head1 ENVIRONMENT

=over

=item B<ISC_USER>

Default value for the L<-user> option.

=item B<ISC_ROLE>

Default value for the L<-role> option.

=item B<ISC_PASSWORD>

Default value for the L<-password> option.

=back

=head1 EXAMPLES

=head2 Backup a database into a compressed format

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

=head2 Restore a database from a compressed backup

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

=head1 SEE ALSO

L<isql-fb(1)>, L<gfix(1)>, L<fbstat(1)>.


Additional documentation about Firebird can be found on the Firebird Project
website, L<http://www.firebirdsql.org>.

=head1 AUTHOR

This manual page was written by Damyan Ivanov L<dmn@debian.org> for the Debian
project. 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.
