GBAK – Firebird Backup and Restore

 Banco de Dados, Leitura Recomendada, Linux, Redes  Comentários desativados em GBAK – Firebird Backup and Restore
abr 292013

GBAK is Firebird’s command line tool for online backup and restore of a complete database.

GBAK is able to perform a backup while the database is running. There is no need to shut down the database during a GBAK backup. GBAK will create a consistent snapshot of the database at the time it starts running. You will, however, notice a perfomance degradation during the backup, so it is a good idea to backup at night. As GBAK visits all pages of the database, so it will also perform a garbage collection on the database.

General Syntax

gbak <options> -user <username> -password <password> <source> <destination>


For backups, <source> is the database you want to back up, <destination> is the file name of the backup file. The usual extension for the backup file is .fbk for Firebird and .gbk for InterBase.

Only SYSDBA or the database owner can perform a backup. For multi-file databases, specify only the name of the first file as the database name.


For restores, <source> is the backup file and <destination> is the name of the database that is to be built up from the backup file. You will have to specify the -C option for restore.

General Options

Suppresses Database Triggers from running [Firebird 2.1]
-pas[sword] <password>
Database password
-fet[ch_password] <filename>
Instead of -password: Fetch password from the file so it is not visible in the command line. When <filename> is stdin, the user will be prompted for the password. [Firebird 2.5]
Only backs up/restores metadata (schema). No table data will be re/stored.
-role <role>
Connect as role
Backup: Creates the backup file on the database server, using the Service Manager.
Restore: Creates the database from a backup file on the server, using the Service Manager.
All file names (backup file, log file) must be specified as viewn from the server’s perspective.
-u[ser] <username>
Database user name
-v[erbose] or
Verbose output of what GBAK is doing
-y <filename>
Redirect all output messages to <filename>
The file must not exist before running GBAK!
-y suppress
Quiet mode: suppress any output
Show GBAK version and server version

Backup Options

Back up. This switch is optional.
Converts external tables to internal tables
Creates an uncompressed backup
-fa[ctor] n
Blocking factor for tape device
-g[arbage collect]
Does not perform garbage collection during backup, so the backup will be faster. When you plan to da a Restore or Sweep anyway after the backup.
Ignores checksum errors while backing up
Ignores limbo transactions while backing up
Only backs up metadata (schema). No table data will be stored.
Non-transportable format (use only when you know you will restore on same platform and database version)
Creates a transportable backup (transportable between platforms and server versions). This is the default.

Restore Options

Set cache size for restored database
Restore to a new database (the target database file MUST NOT exist)
-fix_fss_d[ata] <charset>
Repair malformed UNICODE_FSS data during Restore [Firebird 2.5]
-fix_fss_m[etadata] <charset>
Repair malformed UNICODE_FSS metadata during Restore [Firebird 2.5]
All indexes will be restored as INACTIVE
Does not create shadows that are defined in the backup
Only restores metadata (schema). No table data will be restored.
-mo[de] read_write
Restores to a read/write database (This is the default)
-mo[de] read_only
Restores to a read-only database
Does not restore validity constraints. So you can restore data that does not meet these constraints and could not be restored otherwise.
Usually the restore takes place in one single transaction for the whole database. This switch puts a commit after each table. So you can use this to partially restore databases with corrupt table data.
-p[age_size] <size>
Sets page size of new database. <size> can be one of 1024, 2048, 4096, 8192. Default is 1024.
Restores over an existing database. This can only be performed by SYSDBA or the owner of the database that is overwritten. Do NOT restore over a database that is in use! [Firebird 1.0, 1.5]
New abbreviation for the old -replace_database [Firebird 2.0]
-r[ecreate_database] o[verwrite]
[Firebird 2.0] Restores over an existing database. This can only be performed by SYSDBA or the owner of the database that is overwritten. Do NOT restore over a database that is in use!-r is equivalent to -c. Only the “overwrite” option will restore over an existing database.
Normally, on restore, database pages will be filled to about 80 %. With the use_all_space option, database pages will be filled to 100 %. (Useful for read-only databases which will see no more modifications.)


A regular Backup

gbak -v -t -user SYSDBA -password "masterkey" dbserver:/db/warehouse.fdb c:\backups\warehouse.fbk

Backup with output to a logfile

del c:\backups\warehouse.log
gbak -v -t -user SYSDBA -password masterkey -y c:\backups\warehouse.log dbserver:/db/warehouse.fdb c:\backups\warehouse.fbk

A regular Restore

gbak -c -v -user SYSDBA -password masterkey c:\backups\warehouse.fbk dbserver:/db/warehouse2.fdb

Restore to an already existing database (Firebird 1.0, 1.5)

gbak -c -r -v -user SYSDBA -password masterkey c:\backups\warehouse.fbk dbserver:/db/warehouse.fdb

Restore to an already existing database (Firebird 2.x)

gbak -r o -v -user SYSDBA -password masterkey c:\backups\warehouse.fbk dbserver:/db/warehouse.fdb

Create a read-only database

gbak -c -v -mode read_only -use_all_space -user SYSDBA -password masterkey c:\backups\warehouse.fbk c:\files\warehousedb.fdb

Multi-file backups

Syntax for backup

gbak [options] <database> <target file 1> <size 1> <target file 2> <size 2> ... <target file n>

NOTE: Do not specify a size for the last file. It will always be filled to take up what is left over, no matter how large.

Size can be given in bytes (8192), kilobytes (1024k), megabytes (5m), or gigabytes (2g)

Syntax for restore

gbak -c [options] <source file 1> <source file 2> ... <source file n> <database>

Restoring to a multi-file database

gbak -c [options] <source file> <db file 1> <size 1> <db file 2> <size 2> ... <db file n>

NOTE: Do not specify a size for the last database file. It can always grow unlimited to take up the rest.

Size can be given in bytes (8192), kilobytes (1024k), megabytes (5m), or gigabytes (2g)

Restoring from a multi-file backup to a multi-file database

gbak -c [options] <source file 1> <source file 2> ... <source file n> <db file 1> <size 1> <db file 2> <size 2> ... <db file n>

Backup and Restore at the same time

Use this when you want to test the physical and logical health of your database or to copy a database to another location using a proper Backup-&-Restore cycle.

Note that stdin and stdout get special treatment from gbak here, so don’t use “/dev/stdin” or “/dev/stdout”.


gbak -c [options] <source database> stdout | gbak -r [options] stdin <target database>

Backing up and Restoring the Security Database

Firebird 1.0, 1.5

You can perform a regular backup of the security database.  The security database resides in the Firebird directory. It is named

  • ISC4.gdb in Firebird 1.0 and
  • security.fdb in Firebird 1.5.

Firebird 2.x (using the Service Manager)

Firebird 2.x does not allow regular database access to the security database. Its name is now security2.fdb

The only way to access the security database is via the Service Manager. As GBAK can also use the Service Manager (Option -se), you can run a backup using this option. However, the backup file will also be written to the server machine.

General Syntax:

gbak <options> -user <username> -password <password> -service <servername>:service_mgr <sec-db-name> <backup-filename>


gbak -v -t -user sysdba -password masterkey -service dbserver:service_mgr c:\Programme\Firebird2\security2.fdb C:\Backups\Security2.fbk
  (in this case, Security2.fbk will be written to the C:\Backups folder of dbserver!)

When your database server listens on a non-default port:

gbak -v -t -user sysdba -password masterkey -se dbserver/3051:service_mgr c:\Programme\Firebird2\security2.fdb C:\Backups\Security2.fbk

Firebird 2.1/2.5

In Firebird 2.1 there is a new option -no_dbtriggers that suppresses database triggers from running during backup/restore. So you can suppress any unwanted behaviour for the connection that GBAK needs to establish for the database.

Restoring the Security Database

It is not possible to restore the security database while Firebird is running. In case your security database gets destroyed, this is what you can do:

  • Stop the Firebird service/daemon
  • Replace the current security database with a new one. If anything else fails, re-install the Firebird server
  • You should now have a working SYSDBA login and password. If not, re-install the Firebird server …
  • Start the Firebird service/daemon
  • Using GBAK, restore your backup of the security database to a temporary place (like C:\Temp\security2.fdb)
  • Stop the Firebird service/daemon again
  • Now copy the file from the temporary place to the correct place in the Firebird folder
  • Start the Firebird service/daemon
  • Now you should have your “old” security database back.
  • Good Luck! 🙂

Upgrading a Security Database to Firebird 2.0

There is a special chapter “Dealing with the New Security Database” about this in the Firebird 2.0 Release Notes, which get installed to the doc subdirectory of your Firebird directory. You should also take a look at the misc\upgrade\security\security_database.txt file, which explains in detail how to do it.

Firebird – SuperServer, ClassicServer ou SuperClassic?

 Banco de Dados, Clusterweb, Linux, Redes  Comentários desativados em Firebird – SuperServer, ClassicServer ou SuperClassic?
abr 262013

Firebird installation screen exerpt

Uma das decisões mais importantes na implantação de um servidor Firebird é a escolha do tipo de servidor. A escolha é feita na tela do instalador.

Se já é difícil fazer uma escolha bem informada hoje, espere até o lançamento do Firebird 2.5. Serão 3 opções. SuperServer, ClassicServer e SuperClassic.

As grandes diferenças entre eles estão no cache de páginas e no modo como o servidor gerencia o processo e os threads que executam seus comandos.


No Super Server existe apenas um cache de páginas que é compartilhado por todas as conexões.

Por ser compartilhado, este cache é muito eficiente. Quando vários clientes acessam as mesmas áreas do banco de dados ou quando algumas tabelas são muito mais acessadas que outras, todos os clientes se beneficiam de um cache grande e bem preenchido.

Por exemplo, quando o cliente A executa:


algumas páginas relacionadas a tabela CLIENTES e ao índice da chave primária CODIGO são carregados para o cache.

Quando o cliente B executa:


ele se beneficia do cache compartilhado porque as páginas que este comando precisa já estão no cache.

Note também que existe apenas um único processo onde todos os clientes se conectam.

Veja no diagrama:

Firebird super server architecture diagram

O SuperServer sofre de problemas de escalabilidade. Se você instalá-lo num computador com mais de uma CPU (o que é bem provável hoje em dia) ele vai usar apenas uma delas1. Isto não é problema para instalações pequenas ou ambientes onde o servidor terá outras atividades além do banco de dados.

Por exemplo, você tem um servidor dual-core e quer usá-lo como servidor de arquivos, web, impressão e banco de dados. Não é problema que o Firebird use apenas uma CPU porque o servidor terá outras atividades para ocupar a outra CPU. E você ainda terá o benefício de usar um banco de dados leve e ágil, que consome poucos recursos do servidor.

Mas para operações grandes, em que você quer que o banco de dados aproveite cada ciclo das CPUs do servidor, o SuperServer pode ser frustrante.

1 Exceto se você tiver mais de um banco de dados. A partir do Firebird 2.5, o Superserver consegue usar mais de uma CPU desta maneira. Uma para cada banco de dados. Se você tiver apenas um banco de dados o limite ainda se aplica.


No Classic, cada cliente tem um cache próprio e está conectado a um processo dedicado.

O cache dedicado é muito menos eficiente. Se dois clientes acessam a mesma área do banco de dados, esta área será copiada no cache de cada um deles. Usando o exemplo anterior, quando o cliente B executasse seu comando, ele não teria o benefício de um cache já preenchido e o Firebird precisaria acessar o disco novamente para responder.

Além do mais, a sincronização entre os caches é feita através do disco. Isto aumenta consideravelmente o custo de I/O para ambientes de alta concorrência.

Veja no diagrama:

Firebird classic server architecture diagram

Um grande benefício deste modelo é a resiliência oferecida pelos múltiplos processos. Se um deles tiver problemas, apenas o cliente conectado a ele será desconectado. Todo o restante do banco de dados continua funcionando normalmente.

O outro grande benefício é a escalabilidade. Acredito que esta característica seja a responsável por boa parte das instalações do ClassicServer. Mesmo em casos onde o cache dedicado produz resultados inferiores ao cache compartilhado do Superserver, a escalabilidade do ClassicServer compensa. Basta adicionar mais hardware e pronto, seu servidor fica mais rápido.

Mas esta escalabilidade não vem de graça. Imagine que você tem 200 clientes simultâneos. São 201 processos, um para cada cliente e mais um para ficar ouvindo novas conexões. Seu sistema operacional deve gerenciar todos estes processos e mantê-los em sincronia. Eles consomem muitos recursos de kernel e isto significa que ele pode ser relativamente lento.

Veja neste exemplo: Firebird 2.5 Alpha 1 Classic com 7 clientes conectados. São 8 processos, 18 threads, 1050 identificadores.

Firebird Classic Task Manager Screen


a partir do Firebird 2.5

A equipe de desenvolvimento decidiu usar o Firebird Classic Server como base para construir o Firebird 3.0, que será totalmente compatível com SMP. O SuperClassic é o primeiro passo nessa direção. É uma evolução do Classic Server que resolve o maior problema que o Classic Server tem: Todos aqueles processos o deixam lento e tornam a manutenção mais difícil.

Bem-vindo ao SuperClassic: Um único processo com cache dedicado.

Firebird superclassic architecture diagram

Olhando assim e levando em consideração o nome, parece um híbrido entre o Classic e o Super, mas não é. O que fizeram foi encapsular todos aqueles processos em threads. Agora cada cliente tem um thread dedicado dentro de um único processo.

Criar centenas de threads é muito mais barato que criar centenas de processos e não existe perda de escalabilidade. A sincronização entre os caches pode ser feita diretamente em memória, o que reduz o custo de I/O. E outros controles que antes eram inter-processo agora são inter-thread, muito mais rápidos.

Veja exemplo comparável ao Classic: Firebird 2.5 Alpha 1 SuperClassic com 7 clientes conectados, 1 processo, 6 threads, 172 identificadores.

Firebird SuperClassic Task Manager Screen


Esta compilação dos casos mais comuns de uso é uma sugestão e serve apenas como guia, um ponto inicial na sua  escolha. A sua instalação pode ter detalhes próprios que não foram abordados aqui.


  • Bases de dados pequenas ou pouco acessadas
  • Servidores pequenos
  • Ambientes onde o cache compartilhado é mais vantajoso que a escalabilidade do SuperClassic


  • Ambientes onde a estabilidade é a maior preocupação
  • Servidores multi-processados
  • Grandes bases de dados com centenas de usuários


  • Servidores multi-processados
  • Grandes bases de dados com centenas de usuários
  • Ambientes onde o cache dedicado é mais vantajoso que o cache compartilhado do SuperServer
  • Ambientes onde o ClassicServer já não consegue escalar