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

AUTHOR

       This manpage was written by Damyan Ivanov <dam@modsoftsys.com> 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.

COPYRIGHT

       © 2004,2007 Damyan Ivanov

                                                                                          GBAK(1)