Restore mode

Restore or recreate?
Malformed string errors during restores
Speeding up the restore

Backups taken with the gbak application from one version of Firebird - or InterBase^Ž - can be used by later versions of Firebird to restore the database, however, while this may result in an upgrade to the On Disk Structure (ODS) for the database in question, the SQL dialect will never be changed. If you backup an InterBase dialect 1 database and then use the dump file to recreate it under Firebird 2.1, for example, the ODS will be updated to 11.1 but the SQL Dialect will remain as 1.

Important: Always restore the database with the version of gbak supplied with the database server you wish to run the (new) database under. However, gbak from Firebird 2.1 can be used to restore a database onto any version of Firebird.

You can change the SQL Dialect using gfix.

Under normal circumstances, restoring a database takes place as a single transaction. If the restore is successful, a commit at the end makes the data permanent, if not, the database will be empty at the end.

The restore option -o[ne_at_a_time] will use a transaction for each table and if the table is restored with no errors, a commit is executed rendering that table permanent regardless of what happens with subsequent tables.

Restore or recreate?

Should a database be restored or replaced? Restoring a database is the process by which you take the existing file and delete prior to replacing it on disc with a backup copy. gbak does this when you specify the -r[ecreate_database] o[verwrite] switch or the -rep[lace_database] switch. What is the difference?

If a database exists on disk and you ask gbak to restore it using one of the two switches above, you might corrupt the database especially if the database is in use and has not been shut down using gfix. In addition, if you have only partially completed the restore of a database, and some users decide to see if they can login, the database may well be corrupted.

Finally, if the restore process discovers that the dump file is corrupt, the restore will fail and your previously working database will be gone forever.

It can be seen that restoring a database can be a fraught experience.

For security, always recreate the database with a new name - a clone - and update the aliases.conf to reflect the new name. This way, your users will always refer to the database by the alias regardless of the actual filename on the server.

Malformed string errors during restores

During a restore operation, most likely when restoring a backup taken using an older gbak version, it is possible to see failure messages, in gbak's output, indicating malformed Unicode strings. The reason that these may occur is as explained by Helen Borrie:

The source text of stored procedures (and several other types of object, such as CHECK constraints) is stored in a blob, as is the "compiled" BLR code. When you restore a database, the BLR is not recreated: the same BLR is used until next time you recreate or alter the object.

Historically, the engine did not do the right thing regarding the transliteration of strings embedded in the source and the BLR. In v.2.1 and 2.5 a lot of work was done to address the international language issues, as you probably know. A side effect of this was that everything that was read from data and metadata became subject to "well-formedness" checks. Hence, on restoring, those previously stored source and BLR objects are throwing "malformed string" errors when gbak tries to read and write the data in these system table records. This very old bug affects user blobs, too, if they have been stored using character set NONE and the client is configured to read a specified character set to which the stored data could not be transliterated.

In v.2.1 there were scripts in ../misc that you could run to repair the metadata blobs and also use as a template for repairing the similar errors in blobs in your user data. The repair switches were added to the gbak restore code in v.2.5 to do the same corrections to metadata and data, respectively, during the process of restoring a database for upgrade.

Speeding up the restore

The restoration of a database, from a backup, can be made to execute quicker if the -se[rvice] option is used. Although this is used to perform remote restores, it can be used locally as well. It simply avoids the data being copied over the TCP network which can slow down the actions of the restore.

 tux> gbak -replace -service tux:service_mgr /backups/employee.fbk employee

The example above backs up the employee database, on the tux server, "remotely" using the service manager. The tux server is, of course, where the command is running, so it isn't really running remotely at all.

You can, of course, combine the -g[arbage_collect] and -se[rvice] options.