FirebirdSQL logo

Locking and unlocking

If you prefer to use your own backup tools or just make a file copy, nbackup’s lock-unlock mode comes into view.“Locking” means here that the main database file is frozen temporarily, not that no changes can be made to the database.Just like in backup mode, mutations are directed to a temporary delta file;upon unlocking, the delta file is merged with the main file.

As a reminder: 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).There’s no GUI;you launch it from the command prompt or call it from within a batch file or application.

Locking the database and making the backup yourself

A typical session in which you make your own backup goes as follows:

  1. Lock the database with the -L (lock) switch:

    nbackup [-U user -P password] -L database
  2. Now copy/backup/zip the database file to your heart’s content, with your own choice of tools. A simple file copy is also possible.

  3. Unlock the database with -N (uNlock), or — since Firebird 3.0 — -UN:

    nbackup [-U user -P password] -N database

The last command will also cause any mutations — which have been written to the delta file — to be merged into the main file.

The backup you made contains the data as they were at the moment the database was locked, regardless how long the locked state has lasted, and regardless how long you may have waited before making the actual backup.

Comments:

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

  • The -U and -P parameters may be omitted if the envars ISC_USER and ISC_PASSWORD are set, if you are root on a Posix system, or if trusted authentication under Windows permits it.For a detailed description see the comments under Making full backups.

  • Starting with Firebird 2.5, instead of -P password you may also use -FE filename.

  • Both -L and -N (-UN) make a regular connection to the database, so in Firebird 2.1 and above it may be wise to add the -T (or -NODBTRIGGERS) parameter (see Suppressing database triggers).

  • If you’re locking a raw-device database with Firebird 2.1 or above, the -S option can be very helpful;see [nbackup-lock-unlock-rawdevices].

  • You can optionally add -Z to have version information printed on the first line of the output.

Warning

What goes for backup/restore also applies to the lock/unlock switches: do not use them on multi-file databases.Until things have changed, don’t let nbackup loose on multi-file databases at all!

Restoring a backup made after “nbackup -L”

A copy of a locked database is itself a locked database too, so you can’t just copy it back and start using it.Should your original database get lost or damaged and the self-made copy needs to be restored (or should you wish to install the copy on another machine), proceed like this:

  1. Copy/restore/unzip the backed-up database file yourself with the necessary tools.

  2. Now unlock the database, not with the -N (or -UN) switch, but with -F (fixup):

    nbackup -F database

    Here too, you can optionally use an alias instead of a filename, and add -Z for version info.Other options make no sense.

Why are there two unlock switches, -N/-UN and -F?

  • -N/-UN first sees that any changes made since the locking by -L are merged into the main database file.After that, the database goes back into normal read/write mode and the temporary file is deleted.

  • -F only changes the state flag of the user-restored database to “normal”.

So you use:

  • -N/-UN after having made a copy/backup yourself (to reverse the -L issued earlier);

  • -F after having restored such a backup yourself.

Note

The term fixup is used because it doesn’t attempt to reintegrate the delta-file, but only makes the minimum changes necessary to make the database file usable again.

Under the hood

Note

This section doesn’t contain any necessary knowledge, but provides some extra information which could deepen your understanding of the various switches.

nbackup [parameter] -L does the following:

  1. Connect to the database;

  2. Start a transaction;

  3. Call ALTER DATABASE BEGIN BACKUP (this statement has been discussed in the extra information on nbackup -B);

  4. Commit the transaction;

  5. Disconnect from the database.

nbackup [parameter] -N follows the same steps, but with “…​ END BACKUP” in step 3.

nbackup [parameter] -F works as follows:

  1. The restored database file is opened;

  2. Within the file, the state flag is changed from locked (nbak_state_stalled) to normal (nbak_state_normal);

  3. The file is closed again.

Note

nbackup -F operates purely on file level and can therefore also be performed without a Firebird server running.Any credentials supplied via the -U, -P or -FE parameters are ignored, just as with nbackup -R.