Man Linux: Main Page and Category List

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.

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

       (C) 2004,2007 Damyan Ivanov