# Running a Restore - Firebird

The syntax pattern for the restore options is as follows. POSIX:

$] ./gbak {-c[reate] | -r[eplace_database] } <options> source target or$] /opt/firebird/bin/gbak {-c[reate] | -r[eplace_database] }<options> source target

Windows:

C:Program FilesFirebirdFirebird_1_5in> {-c[reate] | -r[eplace_database] }
<options> source target

or

C:> C:Program FilesFirebird_1_5ingbak {-c[reate] |
-r[eplace_database] }<options> source target

Arguments for gbak Restores

source is the full path and file name of an authentic gbak file. If the backup is a multiple-file set, name only the first (primary) gbak file. On POSIX, source can also be stdin, in which case gbak reads its input from the standard input (usually a pipe).

target is the full path and file name for the restored database. In Firebird 1.5, it can be an alias. The target can be a single file or multiple files. The possible syntax options for target databases are discussed in later sections of this chapter.

options can be a valid combination of switches from Table. The switches are case insensitive.

Restore Switches

Table lists and describes the switches that can be used with gbak when running restores.

gbak Switches for Restores

Restore or Create?

The notion of “restoring a database” by overwriting it was born in another age, when disk space was worth more than hiring an expert to reconstruct a broken database or taking on a team of data-entry staff to reconstruct the company’s system from paper records.

In short, overwriting a database whose survival you care about is not recommended under any circumstances. Ponder these painful facts:

• If a restore fails to complete, the overwritten database is gone forever—and things can go wrong with any restore.
• Restoring over a database that is in use will cause corruption.
• Allowing users to log into a partly restored database will also cause corruption.

If you decide to use –r[eplace_database] anyway, despite the risks, then you can only do so if you supply the login credentials of the database owner, or of SYSDBA. Any user authenticated on the server can restore using the –c[reate] option. Consider the implications of that fact and take the appropriate precautions to keep your backups out of the wrong hands.

User-Defined Objects

When restoring a backup file to a server other than the one on which it was backed up, you must ensure that any character sets and collations referenced in the backup file exist on the destination server. The backup will not be able to be restored if the language objects are missing.

External function and BLOB filter libraries referred to by declarations in the database, similarly, must be present for a restored database to work without errors.

Restoring to a Single File

The following command performs a simple restore from one backup file to one database file:

gbak -c d:dataackupsourdata.fbk d:dataourdata_trial.fdb

Multiple-File Restores

Single or multiple backup files can be restored to single- or multiple-volume database files. There is no requirement to have a one-to-one correspondence between a backup file volume and a database file volume.

When restoring from a multi-file backup, you must name all of the backup files, in the order in which they were backed up. gbak complains noisily if it gets the list in the wrong order or if a volume is missing.

For the target (database) files, you need to supply a size parameter for all files except the last. The minimum value is 200 database pages. The last file always expands as needed to fill all available space.

Single-Volume Backup to Multiple-Volume Database

POSIX:

./gbak -c /backups/stocks.fbk /data/stocks_trial.fdb -user SYSDBA -password m1llp0nd -v -y /logs/backups/stocks_r.20040703.log

Windows:

gbak -c e:backupsstocks.fbk d:datastocks_trial.fdb -user SYSDBA -password m1llp0nd -v -y d:databackuplogsstocks_r.20040703.log

If you specify several target database files but have only a small amount of data, the target files are initially quite small—around 800K for the first one and 4KB for subsequent files. They grow in sequence, to the specified sizes, as you populate the database.

Multiple-Volume Backup to Single-Volume Database

POSIX:

./gbak -c /backups/accounts.fb1 /backups2/accounts.fb2 /backups3/accounts.fb3 /data/accounts_trial.fdb -user SYSDBA -password m1llp0nd -v -y /logs/backups/accounts.20040703.log

Windows:

gbak -c e:backupsaccounts.fb1 f:backups2accounts.fb2 g:backups3accounts.fb3 d:dataaccounts_trial.fdb -user SYSDBA -password m1llp0nd -v -y d:databackuplogsaccounts.20040703.log

Restoring to Multiple Files from Multiple Files

POSIX:

./gbak -c /backups/accounts.fb1 /backups2/accounts.fb2 /backups3/accounts.fb3 /data/accounts_trial.fd1 500000 /data/accounts_trial.fd2 -user SYSDBA -password m1llp0nd -v -y /logs/backups/accounts.20040703.log

Windows:

gbak -c e:backupsaccounts.fb1 f:backups2accounts.fb2 g:backups3accounts.fb3 d:dataaccounts_trial.fdb 500000 d:dataaccount_trial.fd2 -user SYSDBA -password m1llp0nd -v -y d:databackuplogsaccounts.20040703.log

Return Codes and Feedback

A restore on Windows returns an error level of 0 on success and 1 on failure. If an error occurs, check the log file (firebird.log on v.1.5; interbase.log on v.1.0.x).

Page Size and Default Cache Size

You can optionally change the page size when restoring, by including a –p[age_size] parameter switch in the command, followed by an integer representing the size in bytes. Refer to Table for valid page sizes.

This example tells gbak to restore the database with a page size of 8192 bytes:

gbak -c -p 8192 d:databackupsourdata.fbk d:dataourdata_trial.fdb

Similarly, you can use a restore to change the default database cache size (in pages, or “buffers”):

gbak -c -b 10000 d:databackupsourdata.fbk d:dataourdata_trial.fdb

Page Size and Performance

The size of a restored database is specified in database pages. The default size for database files is 200 pages. The default database page size is 4K, so if the page size has not been changed, the default database size is 800K. This is sufficient for only a very small database.

Changing the page size can improve performance in the following conditions:

• Firebird performs better if rows do not span pages. Consider increasing the page size if a database contains any frequently accessed tables with long rows of data.
• If a database contains any large indexes, a larger database page size reduces the number of levels in the index tree. The smaller the depth of indexes, the faster they can be traversed. Consider increasing the page size if index depth is greater than three on any frequently used index. Refer to Chapter indexes, especially the “Optimization Topic” near the end of the chapter and the notes about using the gstat utility to work out how well your indexes are performing.
• Storing and retrieving BLOB data is most efficient when the entire BLOB fits on a single database page. If an application stores many BLOBs exceeding 4K, a larger page size reduces the time for accessing BLOB data.
• Reducing the page size may be appropriate if most transactions involve only a few rows of data, because the volume of data needing to be passed back and forth is lower and less memory is used by the disk cache.