<< Making and restoring backups | Firebird's nbackup tool | Setting the delta file >>

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, so 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 subdirectory 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 call it 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:

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

 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 make a regular connection to the database, so in Firebird 2.1 and above it may be wise to add the -T 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 Locking raw-device databases.
• 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!

back to top of page

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:

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

2. Now unlock the database, not with the -N 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 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. Come to think of it: you can read -F as flag-only.

back to top of page

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:

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 -N follows the same steps, but with "...END BACKUP" in step 3.

nbackup -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 even be performed without a Firebird server running. Any credentials supplied via the -U, -P or -FE parameters are ignored, just as with nbackup -R.

back to top of page

Locking raw-device databases

As discussed in Backing up raw-device databases, problems can arise if a delta has to be created for a database located on a raw device. Therefore, in Firebird 2.1 and up, nbackup refuses to operate on raw-device databases unless an explicit location for the delta file has been set previously. For the procedure, see Setting the delta file, a little further down.

There's also another problem if you lock and copy a raw device: you don't know the actual size of the database! The raw device may be 10 GB, but the database might only take up 200 MB of that space. To prevent having to copy the entire device just to be on the safe side – possibly wasting huge amounts of time and space – Firebird 2.1 has introduced a new parameter for nbackup: -S. This parameter is only valid in combination with -L and when it is present, nbackup writes the database size in pages to stdout after locking the database. Because the size is given in pages, it has to be multiplied by the database page size in order to get the actual number of bytes to be copied. Or, if you use the dd copy utility, you could specify the page size as (i)bs and the output of nbackup -L -S as count.

See also:
InterBase® and Firebird command-line utilities: nbackup

back to top of page
<< Making and restoring backups | Firebird's nbackup tool | Setting the delta file >>