GTR FAQ

05 How the operations work

6 min read

Every operation consists of a backup and a restore. The steps around them depend on the database location.

The GUI application and the command line application store the temporary backup in the same place. The backup is <database name>.fbk in a new folder firebird_<random> in the Windows temp folder. This folder is usually C:\Users\<name>\AppData\Local\Temp. It needs enough free space for a backup of the database.

Vacuum

A vacuum of a database on this computer runs these steps:

  1. Safety copy: the tool copies the database file to <database>_orig, for example customers.fdb_orig.
  2. Backup: the Firebird server on this computer writes a backup of the database to a temporary .fbk file. The file lies in a new folder firebird_<random> in the Windows temp folder.
  3. Restore: the Firebird server restores the backup and replaces the original database file.
  4. Cleanup: the tool deletes the backup file and the temporary folder.

The result:

  • a smaller database file
  • faster queries
  • free disk space

The Log Output panel shows the progress messages of the Firebird server during backup and restore.

Migration

A migration of a database on this computer runs these steps:

  1. Safety copy: the tool copies the database file to <database>_orig.
  2. Backup with Firebird 2.5: the Firebird 2.5 server writes a backup of the database.
  3. Restore with Firebird 5: the Firebird 5 server restores the backup in the Firebird 5 format. The new database replaces the original file under the same name.
  4. Cleanup: the tool deletes the backup file and the temporary folder.

Both servers run on this computer. The tool reaches them on the ports FB25_PORT and FB50_PORT from .env.

Migration without a Firebird 2.5 server

The Firebird 2.5 server may already be uninstalled or stopped. In that case nothing answers on port FB25_PORT, and the tool writes the backup with its own Firebird 2.5 engine. The log shows:

No Firebird 2.5 server is running on this computer. The tool reads the database with its own Firebird 2.5 engine.

The engine comes with the GTR Firebird setup as firebird25_embed.zip in the installation folder, in the bitness of Windows. For the backup, the tool unpacks it into a temporary folder and deletes the folder afterwards. The engine opens no network port and installs no service.

This applies to the migration in the modes Local Database and Remote Database (file access via network share), and to the command line application. The TCP/IP mode needs the Firebird 2.5 server that manages the database. Vacuum Firebird 2.5 Database also needs a running Firebird 2.5 server.

Warning

After the migration, only Firebird 5 can open the database. The _orig copy keeps the Firebird 2.5 version.

Network share mode

Mode: Remote Database (file access via network share)

The tool processes a copy on this computer. It then replaces the database on the share:

  1. Local copy: the tool copies the database from the share to a new folder firebird_<random> in the Windows temp folder.
  2. Backup and restore: the Firebird servers on this computer vacuum or migrate the local copy, as described above.
  3. Copy-back: the tool copies the result to the share as <database>.new and compares the file sizes.
  4. Swap: the tool renames the database on the share to <database>_orig.new and then renames <database>.new to the original name.
  5. Safety copy: the tool renames <database>_orig.new to <database>_orig. An older _orig file is replaced only now.
  6. Cleanup: the tool deletes the temporary folder on this computer.

The completion dialog confirms that the processed database replaced the original on the share. No manual copy is needed.

If the backup or the restore fails, the database on the share stays unchanged. The tool deletes the temporary folder.

If the copy-back fails, the tool renames the original back and deletes <database>.new on the share. The error message names the temporary folder that still holds the processed database.

TCP/IP mode

In the TCP/IP mode the tool has no access to the database file. It works through the Firebird port:

  1. Check: the tool checks the server that the restore writes to. See Checks before the backup.
  2. Backup: the Firebird server backs up the database and sends the backup over the network connection. The tool writes it to a .fbk file in a new temporary folder on this computer.
  3. Restore: the tool sends the backup file back to a Firebird server, which restores it:
    • For a vacuum, the same server restores it and replaces the database.
    • For a migration, the Firebird 5 server from the box Firebird 5 target restores it to the target path. It replaces an existing database there only if Overwrite an existing database at the target is ticked.
  4. Cleanup: the tool deletes the backup file and the temporary folder.

The Firebird 5 target can run on another computer than the Firebird 2.5 source. The backup passes through this computer in both cases.

The TCP/IP mode makes no _orig safety copy:

  • Migration to a new target path: the Firebird 2.5 database stays unchanged and serves as the safety copy. No separate backup is needed.
  • Vacuum, or migration with Overwrite an existing database at the target: the restore replaces a database. Back up the database on the server before you start.

The Log Output panel shows no progress messages of the Firebird server in this mode. After the backup it shows the size of the backup file, for example Backup completed: 812.4 MB.

Failed operations

If a check before the backup fails, the tool transfers nothing and deletes the temporary folder. The database stays unchanged.

If the backup fails, the tool deletes the incomplete backup file and the temporary folder.

If the restore fails, the tool keeps the backup file and its folder. The error message names the backup file, for example The backup is kept at C:\Users\<name>\AppData\Local\Temp\firebird_...\PROFDIA.fbk. A restore that replaces a database can leave that database incomplete. The error message then names the database as well. Restore it from the kept backup. In the local and network share modes, you can also return to the _orig copy.

For a database on this computer, the error message also names the safety copy. For a database on a network share, it states that the share is unchanged, or it names the folder with the processed database.

The safety copy

The _orig file is a plain copy of the database before the operation. It stays next to the database after the operation. In the network share mode it lies on the share.

  • The next operation on the same database overwrites the _orig file.
  • To return to the previous state, stop all programs that use the database. Then replace the database file with the _orig copy.
  • Delete the _orig file once the processed database works. It takes as much disk space as the database.

The TCP/IP mode makes no safety copy. See TCP/IP mode.

Graph View

Backlinks