Firebird Gbak

0 views

Skip to first unread message

Enrichetta

unread,

Aug 3, 2024, 4:28:09 PM8/3/24

to lipfiveta

In most cases, I'd suggest to use gbak, because it is simpler and also allows you to move backups between platforms and Firebird versions, while nbackup is only really suitable for the same platform and Firebird version (but has the advantage of allowing incremental backups).

ISQL is an interactive query CLI, and cannot be used to create backups. Fbsvcmgr is the "Firebird Service Manager" tool, which can be used to invoke service operations on a (remote) Firebird server. This includes backup and restore operations through gbak and nbackup. Fbsvcmgr is pretty low-level and hard to use (see fbsvcmgr -? for options).

For gbak, you'd normally invoke the services through the gbak executable (option -se[rvice] ), see also Remote Backups & Restores in the gbak documentation. For nbackup you either can use the nbackup tool locally, or you need to use the fbsvcmgr (or another tool that supports service operations) to invoke the same functionality remotely (action_nbak and action_nrest), see also Backups on remote machines (Firebird 2.5+) in the nbackup documentation.

With a gbak backup, you'd normally restore the database using 'create' (option -c[reate]) or 'recreate' (-r[ecreate] without o[verwrite] option), which will fail if the database file already exists. See also the gbak manual linked above for more information.

I won't really answer your question about how to do it from a C++ application, because I don't program C++, and your question is already too broad as it is. But know that it is possible to invoke Firebird service operations, including backup and restore using both gbak and nbackup, from C++ code (that is essentially what Firebird tools itself do). If you want to know more about that, I'd suggest you ask on the firebird-support Google Group.

This switch causes the password for the appropriate user to be read from a file as opposed to being specified on the command line.The filename supplied is not in quotes and must be readable by the user running gbak.If the filename is specified as stdin, then the user will be prompted for a password.On POSIX systems, the filename /dev/tty will also result in a prompt for the password.

This switch causes your data to be ignored and not backed up or restored.In a backup, only the database metadata (tables, triggers, etc.) are backed up.When used in a restore, only the database metadata are restored, and any data in the backup file will not be restored.This switch can be used when creating database clones which are required to contain only the tables, indices, etc., but no data.

For backup, this option controls the number of connections used to read user-data.Every additional worker creates its own thread and connection to read data in parallel with other workers.All worker connections share the same database snapshot to ensure a consistent data view across all workers.Workers are created and managed by gbak itself.The database metadata is read by a single thread.

This switch causes gbak to backup or restore a remote database via the service manager.This causes the backup file to be created or read on the remote server, so the path format and filename must be valid on the remote server.For Firebird 3.0 and earlier, the servicename must always end in service_mgr.

You can use this option to connect to a locally hosted database as well.If you do, taking a backup or restoring using this option can run quicker than accessing the database directly.See also Speeding up the Backup.

Excluding data from a backup or restore can yield errors during restore when constraints are enabled, and a foreign key constraint exists on a table not excluded, depending on a table that was excluded.

Selectively including data in a backup or restore can yield errors during restore when constraints are enabled, and a foreign key constraint exists on a table that was included, depending on a table that was not included.

All known documentation on this switch mentions that the text should be "suppress_output" rather than "suppress".This is an error in the documentation as the source code for gbak shows that the switch must be "suppress".

This displays the current version of gbak, and after displaying a couple of error messages, exits with an error code of 1 as shown above by the echo command.This method does not attempt to backup any databases and does not require a username and password to be defined or supplied.

You will note from the above that a valid username and password must be defined on the command line, or by the use of environment variables ISC_USER and ISC_PASSWORD.This version of the command will exit with a error code of zero.

This method of calling gbak will make a backup of the database.If your database is large, this can take some time to complete and the backup file specified will be overwritten if it already exists.Beware.

When running gbak, if the first filename is a database name, or database alias then gbak will default to taking a backup of the database in transportable format.The backup file will be named as per the second filename supplied on the command line.

You can also send the output to standard output rather than a backup file.In this case, you must specify stdout as the backup filename.This is not really of much use, unless you wish to pipe the backup through a tool to modify it in some way.You can pipe the output directly to a gbak restore operation to clone a database without needing an intermediate backup file.An example is given later in this manual.

This switch causes any external tables to be backed up as if they were normal (non-external) tables.When this backup file is used to restore a database, the tables that were external in the original database will now be normal tables.

This switch causes gbak to ignore bad checksums in the database.This can be used to attempt to backup a database that failed due to checksum errors.There is no guarantee that the data will be usable though, so it is best to take other precautions to preserve your data.

The default backup file format is transportable.Transportable backup files are written in a format known as external data representation (XDR) format.It is this format which allows a backup taken on a server of one type to be successfully restored on a server of another type.

You may read the backup data directly from standard input rather than a backup file.In this case, you must specify stdin as the backup filename.You could pipe a gbak backup operation directly to a gbak restore operation to clone a database without needing an intermediate backup file.An example is given later in this manual.

This switch sets the default database cache size (in number of database pages) for the database being restored.If a database is being overwritten then this setting will overwrite the previous setting for the cache size.

Malformed string data will be attempted to be read using the specified character set charset-name, and then transformed to UNICODE_FSS.Specifying the wrong character set name may result in logical corruption of your data.

This switch, and the following one, should not be required under normal circumstances.However, if a restore operation fails with a "malformed string" error, the message output from gbak will refer the user to one or both of these switches to fix the malformed UNICODE_FSS data or metadata as appropriate.

Malformed metadata string will be attempted to be read using the specified character set charset-name, and then transformed to UNICODE_FSS.Specifying the wrong character set name may result in logical corruption of the strings in your metadata.

This switch, and the preceding one, should not be required under normal circumstances.However, if a restore operation fails with a "malformed string" error, the message output from gbak will refer the user to one or both of these switches to fix the malformed UNICODE_FSS data or metadata as appropriate.

This switch can be used to restore a database when a previous restore attempt failed due to index errors.All indexes in the restored database will be inactive, and as a consequence all primary key, unique key and foreign key constraints as well.

This switch forces the restore to use 100% of each database page and thus not leave any room for changes.If you omit this switch, some space will be kept free for subsequent changes.Using this switch is likely to be only of practical use where the database is created and used in read-only mode and no updates to existing data are required.

Once a database has been restored with this option specified, all database pages will be filled to 100% and no free space will be left for updates.Using this option for a read/write database can cause performance problems due to record versions or record updates getting split over multiple pages.

Before you consider using other tools to take a backup of your Firebird database, make sure that you know what the tools do and how a running database will be affected by them.For example, if you use Winzip to create a compressed copy of a database, and you do it when users are accessing the system, the chances of a successful restore of that database are slim.You must either always use the gbak or nbackup tools which know how the database works, enable the database backup mode with ALTER DATABASE BEGIN BACKUP (and end it with ALTER DATABASE END BACKUP), or, use gfix to shut the database down completely before you even attempt to backup the database file(s).

Gbak creates a consistent backup of the database by starting a transaction that spans the backup period.When the backup is complete, the transaction is ended and this means that the backup process can be run while users are working in the database.However, any transactions started after the backup process begins will not have any of their changed data written to the backup file.The backup will represent a copy of the entire database at the moment the backup began.

The backup file created by a default gbak backup is cross-platform (transportable), so a backup taken on a Windows server can be used to recreate the same database on a Linux server, or on any other platform supported by Firebird.This is not true of the copies of your database taken (while the database was closed or in backup-mode!) with tools such as Winzip etc.Those copies should only ever be used to restore a database on the same platform as the one copied.