Technical background information

Nbackup performs a physical backup of the database pages by copying pages that have been modified since the last backup of the immediately preceding level.A level 0 backup copies all pages, while a level 1 copies only those pages that have been modified after the most recent level 0.To be able to find the modified pages, Firebird uses a marker that is called the SCN (short for page scan).This number is incremented at each backup state change.For each backup with nbackup there are three state changes:

nbak_state_normal (no backup) to nbak_state_stalled (database writes to delta file)
nbak_state_stalled to nbak_state_merge (merging delta file back into database)
nbak_state_merge to nbak_state_normal (no backup)

Note	These three state changes occur even if the backup fails.

The SCN of the database before the start of the backup is recorded together with the backup.The very first backup gets SCN 0, the second 3, etc.This number is independent of the level of the backup.The SCN is used to mark the pages of a database.So for example:

SCN Explanation

SCN	Explanation
`0`	Pages before any backup
`1`	Pages written/updated into the delta file during the backup
`2`	Pages written/updated during the merge of delta file into main backup
`3`	Pages written/updated after ending first backup+merge

0

Pages before any backup

1

Pages written/updated into the delta file during the backup

2

Pages written/updated during the merge of delta file into main backup

3

Pages written/updated after ending first backup+merge

When a level 1 backup is made, nbackup looks for the last level 0 backup and backs up all pages with an SCN higher than the SCN of that level 0 backup (and so on).

A backup and restore with gbak does not restore the content of the RDB$BACKUP_HISTORY table, and it resets the SCN of all pages back to 0.The reason for this is that gbak creates a logical backup instead of a physical backup.So a restore using gbak will rewrite the entire database (and can even change the page size).This renders previous backups with nbackup meaningless as a starting point for subsequent backups: you need to start with a fresh level 0.

Document history

The exact file history is recorded in the firebird-documentation git repository; see https://github.com/FirebirdSQL/firebird-documentation

Revision History

Revision History
0.1	21 Oct 2005	PV	First edition.
1.0	1 Dec 2006	PV	Removed “beta” reference in edition info.Changed warning against specifying backup file names interactively with nbackup -R.Removed “(or will be)” from first sentence in Document History. Changed `C:\Databases` to `C:\Data` in the examples, just to keep the lines from running out of the shaded `screen` areas in the PDF. Added section Setting the delta file, and changed section Read on? accordingly.
1.1	5 May 2008	PV	Making and restoring backups: Added warning about heavy-load risks with nbackup 2.0.0–2.0.3. Restoring a full backup: Corrected wrong statement that nbackup will overwrite an existing database if there are no active connections.Changed italic text about interactive restore failure to a Note and mentioned its fix in 2.0.1. Incremental backups: Inserted warning that incremental backups are broken in 2.1. Suppressing database triggers (Firebird 2.1+): New section. Read on?: Fixed typo (you → your).
1.2	19 Sep 2011	PV	Document source formatting: Changed max. line length to 100, without open lines. All sections and subsections now have an `id`. Introduction: Edited first sentence. Nbackup features — an overview: First sentence: groups → kinds.Edited last para before first subsection: mentioned that only `SYSDBA`, owner and sometimes OS admins can make a backup. Nbackup features — an overview :: Limitations of nbackup: Edited previously last listitem to mention Services Manager.Added listitem about direct file access.Removed last para. Functions and parameters: New section. Making and restoring backups: Slightly altered last sentence of first para.Extended warning: added info on the role of direct I/O with large databases under Posix.
			Making and restoring backups :: Full backups :: Making full backups: Corrected and extended listitem on `-U` and `-P` parameters.Added listitems on `-FE` parameter (new in 2.5), `-T` parameter (new in 2.1) and `-D` parameter (new in 2.5, backport to 2.1.4).In listitem starting with “The different parameters”, the parenthesized text now reads (`-B`, `-U` etc.), because many new parameters have been added. Making and restoring backups :: A word on the inner workings: Small edit (image → impression). Making and restoring backups :: Full backups :: Restoring a full backup: Removed parameters `-U` and `-P` from specification.Added listitem on aliases.Changed separate Note about interactive restore failure back to italic text inside the listitem itself.Added listitem about non-necessity of running server and ignoring credentials. Making and restoring backups :: Incremental backups: Edited Warning: mentioned fix in 2.1.1. Making and restoring backups :: Incremental backups :: Restoring incremental backups: Removed parameters `-U` and `-P` from formal syntax and 1st listitem. Making and restoring backups :: Backing up raw-device databases: New section. Making and restoring backups :: Suppressing database triggers: Edited and extended this section, but removed the “`SYSDBA` and owner only” remark. Making and restoring backups :: Direct I/O (Firebird 2.1.4+): New section. Making and restoring backups :: Informational options (Firebird 2.5+): New section. Making and restoring backups :: Backups on remote machines (Firebird 2.5+): New section. Locking and unlocking: Slightly altered last sentence of second para. Locking and unlocking :: Locking the database and backing up yourself: Added Comments (para + itemizedlist). Locking and unlocking :: Restoring a backup made after nbackup -L: Added info on use of alias and `-Z` to step 2 of procedure.In next para, translated “en” (leftover from Dutch original) → “and”.Added sentence to Note about reading `-F` as Flag-only. Locking and unlocking :: Locking raw-device databases: New section. Locking and unlocking :: Under the hood: Edited Note. Setting the delta file: 1st para largely rewritten;now refers to raw-device databases.Split off last sentence into a para of its own.Added info (para + programlisting) about setting delta with `CREATE DATABASE`.1st listitem in Notes: `ADD` → `[ADD]`.
			Document history: Changed ulink to CVS (both text and url);now points directly to document. License notice: End year in copyright mention now 2011.
1.3	12 Oct 2011	PV	Functions and parameters: In first table: self-restored → user-restored.In second table: self-restore → user restore. Locking and unlocking :: Locking the database and backing up yourself: Section renamed Locking the database and making the backup yourself. Locking and unlocking :: Restoring a backup made after nbackup -L: 2nd listitem in 1st itemizedlist: self-restored → user-restored.
1.4	18 Sep 2014	MR	Backup history: New section Technical background information New section
1.5	27 Jun 2020	MR	Conversion to AsciiDoc, minor copy-editing
1.6	25 Jul 2020	AK	Paragraph about VM backups, example with non-standard port, performance notice paragraph on incremental backup
1.7	10 Oct 2022	MR	Added switches introduced in Firebird 3.0 and 4.0 Various copy-editing Fix rendering of Document History in PDF by breaking long entries into multiple entries

0.1

21 Oct 2005

First edition.

1.0

1 Dec 2006

Removed “beta” reference in edition info.Changed warning against specifying backup file names interactively with nbackup -R.Removed “(or will be)” from first sentence in Document History.
Changed C:\Databases to C:\Data in the examples, just to keep the lines from running out of the shaded screen areas in the PDF.
Added section Setting the delta file, and changed section Read on? accordingly.

1.1

5 May 2008

Making and restoring backups: Added warning about heavy-load risks with nbackup 2.0.0–2.0.3.
Restoring a full backup: Corrected wrong statement that nbackup will overwrite an existing database if there are no active connections.Changed italic text about interactive restore failure to a Note and mentioned its fix in 2.0.1.
Incremental backups: Inserted warning that incremental backups are broken in 2.1.
Suppressing database triggers (Firebird 2.1+): New section.
Read on?: Fixed typo (you → your).

1.2

19 Sep 2011

Document source formatting: Changed max. line length to 100, without open lines.
All sections and subsections now have an id.
Introduction: Edited first sentence.
Nbackup features — an overview: First sentence: groups → kinds.Edited last para before first subsection: mentioned that only SYSDBA, owner and sometimes OS admins can make a backup.
Nbackup features — an overview :: Limitations of nbackup: Edited previously last listitem to mention Services Manager.Added listitem about direct file access.Removed last para.
Functions and parameters: New section.
Making and restoring backups: Slightly altered last sentence of first para.Extended warning: added info on the role of direct I/O with large databases under Posix.

Making and restoring backups :: Full backups :: Making full backups: Corrected and extended listitem on -U and -P parameters.Added listitems on -FE parameter (new in 2.5), -T parameter (new in 2.1) and -D parameter (new in 2.5, backport to 2.1.4).In listitem starting with “The different parameters”, the parenthesized text now reads (-B, -U etc.), because many new parameters have been added.
Making and restoring backups :: A word on the inner workings: Small edit (image → impression).
Making and restoring backups :: Full backups :: Restoring a full backup: Removed parameters -U and -P from specification.Added listitem on aliases.Changed separate Note about interactive restore failure back to italic text inside the listitem itself.Added listitem about non-necessity of running server and ignoring credentials.
Making and restoring backups :: Incremental backups: Edited Warning: mentioned fix in 2.1.1.
Making and restoring backups :: Incremental backups :: Restoring incremental backups: Removed parameters -U and -P from formal syntax and 1st listitem.
Making and restoring backups :: Backing up raw-device databases: New section.
Making and restoring backups :: Suppressing database triggers: Edited and extended this section, but removed the “SYSDBA and owner only” remark.
Making and restoring backups :: Direct I/O (Firebird 2.1.4+): New section.
Making and restoring backups :: Informational options (Firebird 2.5+): New section.
Making and restoring backups :: Backups on remote machines (Firebird 2.5+): New section.
Locking and unlocking: Slightly altered last sentence of second para.
Locking and unlocking :: Locking the database and backing up yourself: Added Comments (para + itemizedlist).
Locking and unlocking :: Restoring a backup made after nbackup -L: Added info on use of alias and -Z to step 2 of procedure.In next para, translated “en” (leftover from Dutch original) → “and”.Added sentence to Note about reading -F as Flag-only.
Locking and unlocking :: Locking raw-device databases: New section.
Locking and unlocking :: Under the hood: Edited Note.
Setting the delta file: 1st para largely rewritten;now refers to raw-device databases.Split off last sentence into a para of its own.Added info (para + programlisting) about setting delta with CREATE DATABASE.1st listitem in Notes: ADD → [ADD].

Document history: Changed ulink to CVS (both text and url);now points directly to document.
License notice: End year in copyright mention now 2011.

1.3

12 Oct 2011

Functions and parameters: In first table: self-restored → user-restored.In second table: self-restore → user restore.
Locking and unlocking :: Locking the database and backing up yourself: Section renamed Locking the database and making the backup yourself.
Locking and unlocking :: Restoring a backup made after nbackup -L: 2nd listitem in 1st itemizedlist: self-restored → user-restored.

1.4

18 Sep 2014

Backup history: New section
Technical background information New section

1.5

27 Jun 2020

Conversion to AsciiDoc, minor copy-editing

1.6

25 Jul 2020

Paragraph about VM backups, example with non-standard port, performance notice paragraph on incremental backup

1.7

10 Oct 2022

Added switches introduced in Firebird 3.0 and 4.0
Various copy-editing
Fix rendering of Document History in PDF by breaking long entries into multiple entries

Technical Background Information

Technical background information

Document history

docnext count = 0