| Firebird Docset → Firebird Database Docs → Firebird's nbackup tool → 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_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 from within a batch file or application).
To make a full database backup, the command syntax is:
nbackup [-U <user> -P <password>] -B 0 <database> [<backupfile>]
For instance:
C:\Data> nbackup -B 0 inventory.fdb inventory_1-Mar-2006.nbk
The parameter -B stands for backup (gee!). 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 specify 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 -U (user) and -P (password) parameters may be omitted:
if you're logged on as superuser (root, Administrator...), or
if the environment variables ISC_USER and ISC_PASSWORD are set.
For clarity and brevity, these parameters are not used in the examples.
The different parameters (-B, -U and -P) may occur in any order. Of course each parameter should be immediately followed by its own argument(s). In the case of -B there are three of them: backup level, 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.
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.
Note: What follows here is not necessary knowledge to use nbackup. It just gives a rough (and incomplete) image of what happens under the hood during execution of nbackup -B:
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.
Then the actual backup is made. This isn't a straight file copy; restoring must be done by nbackup as well.
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.
A full backup is restored as follows:
nbackup [-U <user> -P <password>] -R <database> [<backupfile>]
For instance:
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk
You don't specify a level for a restore.
When restoring, the -R parameter must come last, for reasons that will become clear later.
If the specified database already exists and there are no connections, it will be overwritten without any warning! If there are users connected, the restore fails and you get an error message.
Here too, you may omit the name of the backup file. If you do, nbackup will prompt you for it. However, this feature is currently broken (at least under Windows). If you specify your backup file name(s) like this, you'll get an error message and a failed restore.
To make an incremental (“differential”) backup we 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:
C:\Data> nbackup -B 1 inventory.fdb inventory_2-Mar-2006.nbk
This backup will only contain the mutations of the last day.
One day later again, you make another one with level 1:
C:\Data> nbackup -B 1 inventory.fdb inventory_3-Mar-2006.nbk
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:
C:\Data> nbackup -B 2 inventory.fdb inventory_3-Mar-2006_2.nbk
This youngest backup only contains the mutations since the most recent level-1 backup, that is: of the last few hours.
All the comments that have been made about full backups also apply to incremental backups.
Again: do not use nbackup for multi-file databases.
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:
nbackup [-U <user> -P <password>]
-R <database> [<backup0> [<backup1> [...] ] ] So restoring the level-2 backup from the previous example goes as follows:
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk
inventory_3-Mar-2006.nbk inventory_3-Mar-2006_2.nbkOf course the line has been split here for layout reasons only - in reality you type the entire command and only hit Enter at the end.
Comments (in addition to the comments with restoring a full backup):
Because it is not known beforehand how many filenames will follow the -R switch (as we don't specify a level when restoring), nbackup considers all arguments after the -R to be names of backup files. It is for this reason that no other parameter (-U or -P) may follow the list of filenames.
There is no formal limit to the number of backup levels, but in practice it will rarely make sense to go beyond 3 or 4.
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.
An nbackup-based incremental backup scheme could look like this:
Each month a full backup (level 0) is made;
Each week a level-1;
A level-2 backup daily;
A level-3 backup hourly.
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:
Level-3 backups are deleted after 8 days;
Level-2s after a month;
Level-1s after six months;
Full backups after two years, but the first one of each year is kept.
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 Locking and unlocking), or if you want to override the default name or location of the delta file (see Setting the delta file).
If you have no craving for any of that: good luck in you work with nbackup!
|
| Firebird Docset → Firebird Database Docs → Firebird's nbackup tool → Making and restoring backups |