Firebird Backup & Restore Utility

1 Firebird Backup & Restore UtilityNorman Dunbar1 may 2013 - Document version of ContentsIntroduction .. 3 Command-line Options .. 3 Common Options .. 3 Backup Switches .. 8 Restore Switches .. 10 Backup Mode .. 13 Speeding up the Backup .. 14 Restore Mode .. 14 Restore Or Recreate? .. 15 Malformed String Errors During Restores .. 15 Speeding up the Restore .. 16 Security Of Backups .. 16 Backup & Restore Recipes .. 17 Backup & Restore Prerequisites .. 17A Simple Backup & Restore .. 17 Meta Data Only .. 17 Splitting The Backup .. 18 Change The ODS .. 18 Change The Cache Size.

2 19 Change The Page Size .. 19 Create A Read-Only Database Clone .. 20 Create a Database Clone Without a Dump File.. 20 Backup & Restore With & Without Shadow Files.. 21 Remote Backups & Restores .. 22 Remote Backups and Restores Using SSH .. 23 Using External Tools .. 24 Gbak Caveats .. 25 Gbak Default Mode .. 25 Normal Versus Privileged Users .. 26 Silent Running? .. 26 Gbak log file Cannot Be Overwritten .. 26 Use of 'stdin' or 'stdout' File Names .. 26 Appendix A: Document history .. 28 Appendix B: License notice .. 303 IntroductionGbak is one of the database Backup and Restore utilities supplied with Firebird .

3 In Firebird it is the only sup-plied Utility of this kind while Firebird also has the nbackup Utility which is described in another this manual, we will discuss: Command-line options for gbak. gbak commands and their parameters. Running gbak in Backup or Restore modes. Some caveats, gotchas and foibles of OptionsCommon OptionsWhen running gbak in Backup or Restore mode, there are a number of options which apply to either mode. Theseare: -?This switch displays the command line options and switches. It replaces the old method in which you had tosupply an invalid switch (see -help below) in order to see the list of valid onwards. -FE[TCH_PASSWORD] <password file name> | stdin | /dev/ttyThis switch causes the password for the appropriate user to be read from a file as opposed to being specifiedon the command line.

4 The file name supplied is not in quotes and must be readable by the user running the file name is specified as stdin, then the user will be prompted for a password. On POSIX systems,the file name /dev/tty will also result in a prompt for the onwards. -M[ETA_DATA]This switch causes your data to be ignored and not backed up or restored. In a Backup , only the databasemeta data are backed up. When used in a Restore , any data in the dump file will not be restored. This switchcan be used when creating database clones which are required to contain only the tables, indices etc but noneof the - Firebird Backup & Restore Utility4 -PAS[SWORD] <password>Supplies the password for the username specified above.

5 This need not be supplied if ISC_PASSWORD en-vironment variable exists and has the correct value. -RO[LE] <SQL role name>Allows the specification of the role to be used by the connecting user. Not of much practical use and is notnormally used in practice. -U[SER] <username>Allows the username of the SYSDBA or database owner user to be specified if the database is to be backedup, or, in the case of a Restore (with the -c[reate] switch specified), any valid username can be need not be supplied if ISC_USER environment variable exists and has a correct value for the can only be backed up by SYSDBA or the database owner. A Restore can also be carried out bySYSDBA or the database owner, however, if the -c(reate) switch is used, any validated username cancreate a new database from a Backup file.

6 -V[ERIFY]Normally gbak operates quietly with no information written to the display. This switch reverses that situationand causes lots of information to be displayed. The default is to display the output to the screen, but you canredirect the output to a log file using the -y switch. -Y <filename> or the text "suppress"Used in conjunction with the -v[erify] switch to redirect status messages to a file or device, rather thanthe screen, or to suppress them -y suppress is used, then no information will be written to screen regardless of whether -v[erify]is a filename is given and the -v[erify] switch is specified, the file will be written to record progress,errors known documentation on this switch mentions that the text should be "suppress_output" ratherthan "suppress".

7 This is an error in the documentation as the source code for gbak shows that the switchmust be "suppress".Gbak - Firebird Backup & Restore Utility5 WarningThe log file must not exist. If it does, the Backup or recovery operation will fail:tux> rm > gbak - Backup -y -vtux> ls -l 1 Firebird Firebird 21610 2010-08-04 10:22 > gbak - Backup -y -vgbak:cannot open status and error output file -ZThis option displays some information about the version of gbak being used, and optionally, a database. Toobtain the version of gbak only, run the command as follows:tux> gbak -zgbak:gbak version Firebird : ERROR:requires both input and output filenamesgbak:Exiting before completion due to errorstux> echo $?

8 1 This displays the current version of gbak, and after displaying a couple of error messages, exits with an errorcode of 1 as shown above by the echo command. This method does not attempt to Backup any databases anddoes not require a username and password to be defined or you wish to display the version number of the gbak Utility and also details of database, you must supplya valid database name and Backup filename, as follows:tux> gbak -z employee -user sysdba -password secretgbak:gbak version Firebird : Version(s) for database employeeFirebird/linux (access method),version Firebird (remote server),version (tux)/P11 Firebird /linux (remote interface), version (tux)/P11on disk structure version > echo $?

9 0 You will note from the above that a valid username and password must be defined on the command line, orby the use of environment variables ISC_USER and ISC_PASSWORD. This version of the command willexit with a error code of - Firebird Backup & Restore Utility6 WarningThis method of calling gbak will make a Backup of the database. If your database is large, this can take sometime to complete and the Backup file specified will be overwritten if it already exists. output above has been slightly abbreviated to allow it to fit the page width for a pdf. -helpHelp is actually not a valid option, but can be used to display the following screen of information as outputfrom gbak in Firebird :gbak:legal switches are.

10 -B[ACKUP_DATABASE] Backup database to file -BU[FFERS] override page buffers default -C[REATE_DATABASE] create database from Backup file -CO[NVERT] Backup external files as tables -E[XPAND] no data compression -FA[CTOR] blocking factor -G[ARBAGE_COLLECT) inhibit garbage collection -I[NACTIVE] deactivate indexes during Restore -IG[NORE] ignore bad checksums -K[ILL] Restore without creating shadows -L[IMBO] ignore transactions in limbo -M[ETA_DATA] Backup metadata only -MO[DE] <access> "read_only" or "read_write" access -N[O_VALIDITY] do not Restore database validity conditions -NOD[BTRIGGERS] do not run database triggers -NT Non-Transportable Backup file format -O[NE_AT_A_TIME] Restore one table at a time -OL[D_DESCRIPTIONS]]