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

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

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

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

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.

A full backup is restored as follows:

For instance:

To make an incremental (“differential”) backup, specify a backup level greater than 0.An incremental backup of level N always contains the database mutations since the most recent level N-1 backup.

Examples:

One day after the full backup (level 0), you make one with level 1:

This backup will only contain the mutations of the last day.

One day later again, you make another one with level 1:

This one contains the mutations of the last two days, since the full backup, not only those since the previous level-1 backup.

A couple of hours on we go for a level-2 backup:

This youngest backup only contains the mutations since the most recent level-1 backup, that is: of the last few hours.

Before Firebird 3.0, all incremental backups (i.e., level 1, 2, etc.) will read the whole database file to locate the changes and store them into a backup file.This can affect the database performance in a case of big databases (100Gb+) and slow disk subsystem (usually, slowness can be noticed on non-SSD drives).Starting from Firebird 3.0, only the changed portion of the database file is read, so incremental backups level 1 and higher are much faster, and reduce impact on database performance.

When restoring incremental backups, you must specify the entire chain of backup files, from level 0 through the one you wish to restore.The database is always built up from the ground, step by step.(It is this stepwise adding until the database is restored that gave rise to the term incremental backup.)

The formal syntax is:

So, restoring the level-2 backup from the previous example goes as follows:

Of course the line has been split here for layout reasons only — in reality you type the entire command and only hit kbd:[Enter] at the end.

What happens if you accidentally leave out a file, or specify a series of files that don’t all belong together?You could imagine that you specify inventory_2-Mar-2006.nbk by mistake instead of inventory_3-Mar-2006.nbk in the above example.Both are level-1 backup files, so in both cases we get a nice “0, 1, 2” level series.But our level-2 file is incremental to the level-1 backup of 3 March, not to the one of 2 March.

Fortunately such a mistake can never lead to an incorrectly restored database.Each backup file has its own unique ID.Furthermore, each backup file of level 1 or above contains the ID of the backup on which it is based.When restoring, nbackup checks these IDs;if somewhere in the chain the links don’t connect, the operation is cancelled, and you get an error message.

Firebird databases need not be files;they can also be placed on a so-called raw device, for instance a disk partition without a file system.The question of where the delta has to be placed in such cases was at first overlooked during the development of nbackup.On Posix systems, if the database was located at e.g. /dev/hdb5, it could happen that the delta was created as /dev/hdb5.delta.In light of the nature and purpose of the /dev directory and its often limited available space, this is undesirable.

As of Firebird 2.1, nbackup refuses to operate on raw-device databases unless an explicit location for the delta file has been set.The way to do this is discussed in [nbackup-deltafile], later on in this manual.

Firebird 2.1 introduced the concept of database triggers.Certain types of these triggers can fire upon making or breaking a database connection.As part of the backup process, nbackup opens a regular connection to the database (in some versions even more than once).To prevent database triggers from firing inadvertently, the -T or — since Firebird 3.0 — -NODBTRIGGERS switch can be used.

Originally, nbackup used direct I/O only when making a backup under Windows NT (and successors like 2000, 2003 etc).On all other OS’es, direct I/O was off.This caused problems on some Linux systems, so in versions 2.0.6 and 2.1.3 direct I/O was switched on under Linux as well.However, this turned out to be problematic for certain other Linux configurations.In 2.1.4 and 2.5 the original behaviour was restored, but this time as a default that was overridable by a newly added parameter: -D.Its use is as follows:

Just like the option letters themselves, the arguments ON and OFF are case-insensitive.

Direct I/O is only applied when making a backup, not during a restore.Under Windows it is realized by setting FILE_FLAG_NO_BUFFERING.On other systems, O_DIRECT and POSIX_FADV_NOREUSE are used.The latter two are sometimes unavailable;in such cases, they are (or one of them is) silently left out.Even if the user specified -D on explicitly, this doesn’t lead to a warning or error message.

Apart from the already mentioned -FE and -D parameters, Firebird 2.5 also saw the introduction of the following two:

Nbackup itself only operates on local databases.But in Firebird 2.5 and up, nbackup-type backups and restores can also be performed remotely via the Services Manager.For this, the program fbsvcmgr.exe on the local machine is used;it is located in the same folder as nbackup.exe and the other Firebird command-line tools.The first argument is always “hostname:service_mgr”, with hostname being the name of the remote server.Other available parameters are:

Making a full backup on the remote machine frodo goes like this:

And a subsequent incremental backup:

To restore the whole shebang:

Comments:

An nbackup-based incremental backup scheme could look like this:

As long as all backups are preserved, you can restore the database to its state at any hour in the past.For each restore action, a maximum of four backup files is used.Of course, you schedule things in such a way that the bigger, time-consuming backups are made during off-peak hours.In this case the levels 0 and 1 could be made at weekends, and level 2 at night.

If you don’t want to keep everything for eternity, you can add a deletion schedule:

This is only an example of course.What’s useful in an individual case depends on the application, the size of the database, its activity, etc.

At this point you know everything you need in order to make and restore full and/or incremental backups with nbackup.You only need to read any further if you want to use backup tools of your own choice for your Firebird databases (see [nbackup-lock-unlock]), or if you want to override the default name or location of the delta file (see [nbackup-deltafile]).

If you have no craving for any of that: good luck in your work with nbackup!

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

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:

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:

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

So you use:

nbackup [parameter] -L does the following:

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

nbackup [parameter] -F works as follows:

As discussed in [nbackup-backups-rawdevices], 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 [nbackup-deltafile], 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.

Using Virtual Machines backup tools without preparing database for such type of backup can lead to the corrupted (i.e. useless) backup copy.

Firebird server intensively uses its own cache in RAM to speed up operations, and implements complex techniques to ensure database consistency at the every given moment.Virtual Machine backup tools are not aware about Firebird’s cache, and usually they do not consider database files as random-access files.

As a result, when the virtual machine backup is done, the database file inside it will have the state as after a hard reset of VM, and very often such copy is not consistent (i.e. corrupted).The chance of such problem is higher when many active users are changing the database, or if there is active sweep process.

Such inconsistent backups can occur in any virtualized environment, including public clouds.

In order to create good Firebird database backup with VM backup tool, it is necessary to lock database file with nbackup before the VM backup, and unlock after it.Usually VM backup tool allows executing custom pre- and post-backup scripts, where you can lock/unlock Firebird databases.