FirebirdSQL logo

Making and restoring backups

To begin with: nbackup.exe is located in the bin subdirectory of your Firebird folder.Typical locations are e.g. C:\Program Files\Firebird\Firebird_3_0 or C:\Program Files\Firebird\Firebird_2_0\bin (Windows) or /opt/firebird/bin (Linux).Just like most of the tools that come with Firebird, nbackup has no graphical interface;you launch it from the command prompt or call it from within a batch file or application.

Warning

Under heavy-load circumstances in some environments, nbackup of Firebird 2.0.3 and below may cause problems that will lead to deadlocks or even corrupted databases.While these problems aren’t common, they are serious enough to warrant upgrading to Firebird 2.0.4 or higher if you want to use nbackup comfortably.If it concerns large databases under Posix, the use of direct I/O may also make a difference.More about this in the section Direct I/O.

Making full backups

To make a full database backup, the command syntax is:

nbackup [-USER user -PASSWORD password] -BACKUP 0 database [backupfile]

For instance, assuming the database is located in C:\Data, and `nbackup.exe ` is in the search of path Windows:

C:\Data>nbackup -BACKUP 0 inventory.fdb inventory_1-Mar-2006.nbk

Or, if Firebird (from version 2.5) is running on non-standard port, in this example, 3051:

C:\Data>nbackup -BACKUP 0 localhost/3051:C:\Data\inventory.fdb C:\Data\inventory-level-0-Jul-2020.nbk -user SYSDBA -pass masterkey

In Firebird 3.0 and higher, in a case of successful completing the backup, the nbackup will print the short statistics:

time elapsed    0 sec
page reads      307
page writes     307
Comments
  • The backup level 0 indicates a full backup.Backup levels greater than 0 are used for incremental backups;we’ll discuss those later on.

  • Instead of a database filename you may also use an alias.

  • Instead of a backup filename you may also specify stdout.This will send the backup to standard output, from where you can redirect it to e.g. a tape archiver or a compression tool.

  • The -USER and -PASSWORD parameters may be omitted if at least one of the following conditions is met:

    • The environment variables ISC_USER and ISC_PASSWORD have been set, either to SYSDBA or to the owner of the database.

    • You are logged on as root on a Posix system.This makes you SYSDBA by default.

    • Under Windows: Trusted authentication is enabled in firebird.conf, and you are logged on to the Windows account that owns the database.This is possible in Firebird 2.1 and above.

    • Under Windows: Trusted authentication is enabled in firebird.conf, and you are logged on as a Windows administrator.In Firebird 2.1, this automatically gives you SYSDBA rights.In Firebird 2.5 and above, there is the additional condition that AUTO ADMIN MAPPING has been set in the database.

    For clarity and brevity, the -USER and -PASSWORD parameters are not used in the examples.

  • Starting with Firebird 2.5, instead of -P password (or -PASSWORD password) you may also use -FE filename (or -FETCH_PASSWORD filename).This will cause nbackup to fetch the password from the given file.With -FE, the password itself doesn’t appear in the command and will thus be better shielded against people who might otherwise pick it up via the command history, the w command on Unix or from a script or batch-file.

  • In Firebird 3.0 and up, the firing of database triggers can be prevented by specifying the -NODBTRIGGERS option.For more information, see Suppressing database triggers.

  • In Firebird 2.1 and up, the firing of database triggers can be prevented by specifying the -T option.For more information, see Suppressing database triggers.The -T option was deprecated in Firebird 3.0 in favour of -NODBTRIGGERS.

  • Starting with Firebird 2.1.4, it is possible to force direct I/O on or off by specifying -D ON or -D OFF.For details and background see Direct I/O, elsewhere in this manual.

  • The different parameters (-BACKUP, -USER etc.) may occur in any order.Of course each parameter should be immediately followed by its own argument(s).In the case of -BACKUP there are three of them: backup level or guid, database, and backup file — in that order!

  • If the -B parameter comes last, you may leave out the name of the backup file.In that case nbackup will compose a filename based on the database name, the backup level, and the current date and time.This can lead to a name clash (and a failed backup) if two backup commands of the same level are issued in the same minute.

Warning

Do not use nbackup for multi-file databases.This can lead to corruption and loss of data, despite the fact that nbackup will not complain about such a command.

A word on the inner workings
Note
What follows here is not necessary knowledge to use nbackup. It just gives a rough (and incomplete) impression of what happens under the hood during execution of nbackup -BACKUP:
  1. First of all, the main database file is locked by changing an internal state flag.From this moment on, any and all mutations in the database are written to a temporary file — the difference file or delta file.By default, the delta file is created in the same folder as a database file, with the additional extension .delta, for example: MyDatabase.fdb.delta

  2. Then the actual backup is made.This isn’t a straight file copy;restoring must be done by nbackup as well.

  3. Upon completion of the backup, the contents of the delta file are integrated with the main database file.After that, the database is unlocked (flag goes back to “normal”) and the delta is removed.

The functionality of steps 1 and 3 is provided by two new SQL statements: ALTER DATABASE BEGIN BACKUP and ALTER DATABASE END BACKUP.Contrary to what the names suggest, these statements do not take care of making the actual backup;rather, they create the conditions under which the main database file can be safely backed up.And to be clear: you don’t need to issue these commands yourself;nbackup will do that for you, at the right moments.