Locking and unlocking

Locking the database and backing up yourself
Restoring a backup made after nbackup -L
Under the hood

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 lives in the bin subdir of your Firebird folder. Typical locations are e.g. 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 from within a batch file or application).

Locking the database and backing up yourself

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

Lock the database with the -L (lock) switch:
```
nbackup [-U <user> -P <password>] -L <database>
```
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.

Unlock the database with -N (uNlock):

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.

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”

An 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:

Copy/restore/unzip the backed-up database file yourself with the necessary tools.
Now unlock the database, not with the -N switch, but with -F (fixup):
```
nbackup -F <database>
```

Why are there two unlock switches, -N en -F?

-N 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 self-restored database to “normal”.

So you use:

-N after having made a copy/backup yourself (to reverse the -L issued earlier);
-F after having restored such a backup yourself.

Note

It is a bit unfortunate that the last switch should be called -F for Fixup. After all, it doesn't fix anything; it only unlocks the database. The -N (uNlock) flag on the other hand performs not only an unlock, but also a fixup (integration of mutations into the main file). But we'll have to live with that.

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 -L does the following:

Connect to the database;
Start a transaction;
Call ALTER DATABASE BEGIN BACKUP (this statement has been discussed in the extra information on nbackup -B);
Commit the transaction;
Disconnect from the database.

nbackup -N follows the same steps, but with “...END BACKUP” in step 3.

nbackup -F works as follows:

The restored database file is opened;
Within the file, the state flag is changed from locked (nbak_state_stalled) to normal (nbak_state_normal);
The file is closed again.

Note

nbackup -F operates purely on file level and can therefore even be performed without a Firebird server running. Any -U or -P parameters added to the command will be completely ignored.