1

Guia de Migração para o Firebird 3

1ª edição – 2016
Autor: Carlos Henrique Cantu
Piracicaba – São Paulo

Copyright 2016 © Carlos Henrique Cantu

Todos os direitos reservados pelo autor.

Nenhuma parte deste livro poderá ser reproduzida, transmitida e/ou

gravada por qualquer meio eletrônico, mecânico, por fotocópia e
outros, sem a prévia autorização, por escrito, do autor.

Edição, diagramação, finalização e publicação:

Carlos Henrique Cantu

Revisão 1.20 - COMPLEMENTO

As principais mudanças da revisão 1.20 concentram-se nos capítulos

sobre conexão com o Firebird 3 usando um fbclient antigo, testando
as queries das suas aplicações, Jaybird, .NET Provider, bem como as
duas novas seções sobre permissão para criação de bases de dados e
uso de generators e exceções.

ESSE PDF CONTÉM APENAS AS ALTERAÇÕES DA

REVISÃO 1.20 E DESTINA-SE AS PESSOAS QUE
COMPRARAM A VERSÃO IMPRESSA DO GUIA.
 110

O Firebird 3 introduziu uma nova API orientada a objetos (C++),

no entanto, foi mantida total compatibilidade com a API antiga, ou
seja, a nova fbclient poderá ser usada por aplicações legadas, pois todas
as chamadas de API já existentes continuam funcionando.
No entanto, existem alguns outros pontos de atenção que devem
ser observados.

Aplicações feitas em .NET

As versões mais recentes do .NET Provider do Firebird foram

atualizadas de forma a suportar compactação de tráfego e
autenticação via SRP (padrão no Firebird 3).
O .NET Provider implementa o protocolo de comunicação do
Firebird de forma pura (C#), ou seja, ele não usa a fbclient para se
comunicar com o servidor. Sendo assim, precisará ter sua
implementação pura do protocolo atualizada, para que possa suportar
o recurso de criptografia de tráfego.
Isso significa que para que uma aplicação que usa o .NET Provider
consiga se conectar ao Firebird 3, os seguintes parâmetros precisam
ser alterados no firebird.conf:
WireCrypt = enabled

O padrão do WireCrypt é required, obrigando todos os clientes a se

conectarem com criptografia ativada. Alterando para enabled, o
servidor passa a aceitar também conexões sem criptografia.

Caso esteja usando uma versão antiga do .NET Provider, será

necessário configurar a autenticação “legada” (menos segura):
AuthServer = Legacy_Auth, Srp, Win_Sspi

 Tanto AuthServer como AuthClient podem ser

definidos também por conexão, através do DPB
(Database Parameter Block). A definição do AuthServer
também pode ser feita por banco de dados, no
databases.conf.

Firebird 3 e aplicações/
comportamentos legados
 111

Aplicações usando Jaybird

Jaybird é o driver JDBC para aplicações em Java. Similar ao .NET

Provider, o Jaybird implementa o protocolo de comunicação do
Firebird de forma pura (em Java, sem depender da fbclient), além de
possibilitar opcionalmente que a conexão seja feita através da
biblioteca cliente do Firebird.
Até o Jaybird 2.2, a implementação pura do protocolo de
comunicação não suportava criptografia e compressão dos dados
trafegados. O Jaybird 3 introduziu o suporte a autenticação via SRP.
Segundo Mark Rotteveel, responsável pelo driver, a criptografia no
tráfego deve estar disponível na versão 4 do Jaybird. Já a compressão
de dados não tem um prazo definido para implementação.
Sendo assim, usuários do Jaybird que desejarem utilizar a
implementação Java pura do protocolo de comunicação, terão que
configurar o Firebird 3 desligando a criptografia dos dados trafegados
(WireCrypt). Se a versão do driver for anterior a 3.0, terão também que
ativar a autenticação legada (LegacyAuth, insegura).
WireCrypt = Enabled
AuthServer = Srp, Win_Sspi, Legacy_Auth
UserManager = Srp, Legacy_UserManager

Para mais informações sobre como usar o Jaybird com o Firebird

3, sugiro a leitura da página
github.com/FirebirdSQL/jaybird/wiki/Jaybird-and-Firebird-3 ou
goo.gl/ebRykk. O FAQ do Jaybird está disponível em
www.firebirdsql.org/file/documentation/drivers_documentation/ja
va/faq.html ou goo.gl/9GQ6NC.

 O Jaybird pode ser configurado de forma a usar a

biblioteca cliente do Firebird (fbclient), ao invés da
implementação nativa do protocolo de
comunicação. Isso permite usar o Jaybird para
conectar ao Firebird 3 com conexões SRP,
criptografadas e/ou com compressão de dados!
Para versões do JayBird anteriores a 3, a fbclient deve
estar disponível no path de pesquisa do sistema
operacional onde o Jaybird está sendo usado, e as

Firebird 3 e aplicações/
comportamentos legados
 112

bibliotecas jaybird22 ou jaybird22_x64 devem

constar no java.library.path.
A partir da versão 3 do Jaybird, a biblioteca
jaybird22(_x64) não é mais usada, sendo necessário
incluir a JNA 4.4.0 no classpath, além da fbclient estar
no path de pesquisa do sistema operacional (ou a
pasta onde ela está gravada constar na propriedade
de sistema jna.library.path).
Informações detalhadas podem ser vistas em
goo.gl/kwUDVC. Para saber como usar o Jaybird
com o Firebird Embedded, veja goo.gl/RMYFYG.
Para indicar ao Jaybird que se deseja usar a fbclient,
a string de conexão JDBC deve mencionar “native”,
seguindo o seguinte formato:
jdbc:firebirdsql:native:host[/port]:<database>

Tipo lógico (boolean )

O Firebird 3 introduz um novo tipo de dado lógico, o famoso

boolean. No entanto, antes de criar objetos no banco de dados usando
esse tipo, tenha certeza que a tecnologia de acesso ao Firebird usada
em suas aplicações já o suporte, caso contrário, ela não será capaz de
“entender” a informação e você terá problemas!
Por exemplo, aplicações usando a velha BDE, que está estagnada
há muito anos, com certeza não serão capazes de entender esse novo
tipo de dado.

Conectando o FB 3 usando uma fbclient antiga

É sempre recomendável usar uma versão da biblioteca cliente do

Firebird que seja da mesma versão que o servidor instalado, pois isso
permite aproveitar todas as melhorias possíveis. Se por alguma razão
você precisa conectar no Firebird 3 usando uma fbclient “antiga”, será
necessário configurar o firebird.conf de forma a usar a autenticação
legada, e aceitar conexões sem criptografia:
WireCrypt = enabled
AuthServer = Legacy_Auth, Srp, Win_Sspi

Firebird 3 e aplicações/
comportamentos legados
 113

Lembre-se que a autenticação legada é totalmente insegura, e deve

ser usada somente em ambientes confiáveis.

Com as configurações acima, já é possível conectar no Firebird 3

usando bibliotecas clientes de versões anteriores, mas ainda não será
possível gerenciar (criar/modificar/apagar) os usuários reconhecidos
pelo plug-in de autenticação legada. Para emular totalmente o
comportamento legado, outros dois parâmetros precisam ser
configurados:
UserManager = Legacy_UserManager
AuthClient = Legacy_Auth, Srp, WinSspi

UserManager instrui o Firebird como gerir a manutenção de

usuários. No exemplo acima, estamos dizendo que os usuários devem
ser gerenciados através do método legado. Podemos listar mais de um
plug-in de gerenciamento, sendo que a ordem é importante. Por
padrão, o Firebird tentará usar o primeiro plug-in listado, e somente
tentará os próximos, caso o anterior tenha falhado de alguma forma.
O AuthClient é usado para instruir as novas bibliotecas cliente (a
partir do Firebird 3) sobre quais plug-ins de autenticação elas devem
usar, e em qual sequência. Esse parâmetro pode ser configurado tanto
no lado cliente como no servidor.
No exemplo acima, quando configurado no lado cliente, instruirá
a biblioteca cliente para tentar autenticar a conexão usando primeiro
o plug-in de autenticação legada. Se a tentativa falhar (ex: usuário não
existe, senha incorreta, etc), ele irá para o próximo plug-in da lista
reconhecido pelo servidor (SRP), e assim por diante. Lembre-se que
o Firebird 3 permite ter vários usuários com o mesmo nome, desde
que criados por plug-ins diferentes, portanto, mais uma vez, a ordem
que os plug-ins são listados é importante.
No lado do servidor, o AuthClient afeta conexões de saída, quando
o comando execute statement com a cláusula ON EXTERNAL DATA
SOURCE for usado para conectar um servidor remoto. Se houver um
grande número dessas conexões (ou se o servidor remoto estiver em
uma WAN), colocar o plug-in usado como sendo o primeiro da lista
trará um ganho de performance, visto que não se perderá tempo
tentando autenticar com plug-ins não utilizados.

Firebird 3 e aplicações/
comportamentos legados
 114

Os parâmetros AuthClient, UserManager e WireCrypt também

podem ser definidos no databases.conf, portanto, por banco de dados.

Performance de queries

Pode ser que após a mudança para o Firebird 3 (ou mesmo para
qualquer versão do Firebird), queries que anteriormente tinham uma
boa performance, passem a apresentar performance ruim (apesar de
raro, pode acontecer!). As principais razões para justificar tal
comportamento são:

1. Bases de dados que estavam com as estatísticas dos índices

desatualizadas, pela necessidade de fazer um backup/restore
para migrar para o Firebird 3, terão as estatísticas
atualizadas, o que pode fazer com que o otimizador
escolha um novo PLANo de acesso para determinadas
consultas. Às vezes, o otimizador se engana na escolha do
plano, e a performance acaba sendo prejudicada.
2. Em toda nova versão do Firebird, o otimizador sofre
melhorias em sua lógica, com o intuito de se tornar mais
eficiente/inteligente. No entanto, algumas vezes essas
melhorias produzem “efeitos colaterais”, podendo fazer
com que ele escolha PLANos não tão eficientes para
algumas queries.

Se estiver sofrendo com alguma das opções acima, reporte no

tracker do Firebird (tracker.firebirdsql.org), para que os core-developers
analisem o caso e determinem se é uma falha do otimizador, para que
possam corrigi-lo. Como solução de curto prazo, pode-se tentar
forçar um PLANo, ou mesmo usar de artifícios para alterar a query,
fazendo com que o otimizador escolha outro plano.

 O Firebird não atualiza as estatísticas dos índices

automaticamente. Elas são atualizadas apenas
quando o índice é criado, reconstruído, ou quando
o comando SET STATISTICS é executado. A
maioria das aplicações não possuem rotinas para
forçar a atualização das estatísticas dos índices,

Firebird 3 e aplicações/
comportamentos legados
 118

 Tenha muito cuidado ao apagar os códigos das

procedures e triggers, pois se eles não estiverem
disponíveis em pelo menos uma base de dados de
referência ou em scripts sql, você ficará em uma
situação complicada quando precisar alterá-los.

Testando as Queries de suas aplicações

Já foi dito que a mudança de uma versão do Firebird pode implicar

em diversos problemas com queries já existentes, desde performance
ruim, até “quebra” devido ao uso de novas palavras reservadas, etc.
Uma aplicação geralmente é composta por centenas de queries, com
os mais variados propósitos, desde a visualização de informações em
tela, até geração de relatórios, etc. Pode haver também scripts
externos ou queries montadas dinamicamente, impossíveis de serem
checadas apenas olhando o código fonte da aplicação.
Uma dica que pode ajudar na certificação de aplicações existentes
para uso com o Firebird 3, é usar a ferramenta FBScanner, da IBSurgeon,
para logar e testar as queries na nova versão do servidor.
O FBScanner faz parte do pacote HQBird, que consiste em uma
série de ferramentas de análise, monitoramento e otimização de
servidores Firebird. Ele funciona como um proxy entre as estações e
o servidor, permitindo logar toda a comunicação: conexões,
transações, comandos SQL, número de fetches, planos, erros, além do
tempo de preparação e execução de queries.
Você pode instalar o FBScanner ainda quando estiver usando a
versão anterior do Firebird, configura-lo de forma que monitore a
comunicação, e armazene as queries em uma base de dados de log. O
processo mais comum de configuração é instalar o FBScanner na porta
3050, na mesma máquina onde o Firebird está rodando, e alterar o
Firebird de forma a usar alguma outra porta que esteja livre (por
exemplo, a 3053). Fazendo isso, as aplicações que usam o Firebird
continuarão conectando as bases de dados normalmente, passando
pelo FBScanner, sem qualquer tipo de alteração na string de conexão:

Firebird 3 e aplicações/
comportamentos legados
 119

Também é possível instalar o FBScanner em outro computador, e

rotear apenas os terminais/aplicações desejadas para passar por ele.
Depois de alguns dias de monitoramento, você terá um log
contendo grande parte dos selects utilizados em suas aplicações. O
ideal seria cobrir todos os comandos SQL executados na base de
dados, obtendo os detalhes sobre o tempo de execução, etc:

O FBScanner permite executar os comandos logados, ou seja, de

posse da base de dados de log obtida ainda com a versão anterior do
Firebird, pode-se montar um servidor Firebird 3 para testes, fazer o
backup/restore da base de dados nele, e usar o FBScanner Log Analyzer
para executar as queries logadas previamente. A ferramenta mostrará
o resultado da execução dos comandos em uma grade, incluindo as

Firebird 3 e aplicações/
comportamentos legados
 120

informações de performance, permitindo comparar o tempo de

execução da query no servidor antigo com o novo tempo, além do
PLAN antigo e o novo PLAN. As informações da grade podem ser
exportadas para uma planilha Excel.

 Ao comparar o tempo de execução das queries,

tenha em mente que fatores “externos” podem
influenciar no resultado, especialmente se o cache do
sistema operacional (ou do Firebird) estiver “frio”
ou “quente”. Obviamente, o resultado de queries
executadas quando a maior parte das informações
se encontra em cache será sempre melhor do que se
o Firebird precisar busca-las no disco.

O HQBird pode ser adquirido com um super desconto através

dos links disponíveis na página de parceria com a FireBase:
www.firebase.com.br/ibsurgeon ou goo.gl/lWxD9L. Existe também
uma versão de avaliação que funciona por alguns dias, assim poderá
testar antes de compra-lo. Um “Guia do Usuário” em português pode
ser baixado em
ibsurgeon.com/download/docs/FBScanner3UserGuide_PTBR.pdf
ou goo.gl/xaj1lx.

Firebird 3 e aplicações/
comportamentos legados
 121

 Caso pretenda usar o FBScanner para logar a

comunicação em um servidor Firebird 3, será
necessário ativar a autenticação legada e desligar a
criptografia no firebird.conf.
O HQBird também possui seu próprio plug-in de
TraceAPI, que é usado pela ferramenta FBPerfMon,
do mesmo pacote.

Firebird 3 e aplicações/
comportamentos legados
 123

Permissão para criação de bases de dados

No Firebird 3, um usuário precisa ter os direitos necessários

para conseguir criar uma nova base de dados. A exceção é o
usuário SYSDBA, que já “nasce” com esse direito.
A permissão deve ser concedida explicitamente para o usuário
ou para um ROLE, através do comando GRANT
CREATE DATABASE TO [USER | ROLE] <nome-do-
usuário> | <nome-do-role >.
Observe, no entanto, que um usuário sem direito de criação
de bases de dados conseguirá criá-las normalmente, desde que o
faça através de uma conexão embedded! A explicação é que em uma
conexão embedded, a única exigência é que o usuário tenha permissão
de escrita no local onde a base será criada.
De forma prática, imagine um usuário TESTE recém-criado,
e senha 1234, que entra no isql e executa o seguinte comando:
SQL> create database 'localhost:c:\temp\teste.fdb' user 'TESTE'
password '1234';
Statement failed, SQLSTATE = 28000
no permission for CREATE access to DATABASE C:\TEMP\TESTE.FDB

Firebird 3 e aplicações/
comportamentos legados
 124

O Firebird não permitiu a criação da base, pois o usuário TESTE

não tem permissão de criação concedida. No entanto, observe o
comando abaixo:
SQL> create database 'c:\temp\teste.fdb' user 'TESTE' password
'1234';
SQL>

Nesse caso, a base de dados foi criada sem qualquer problema!

Comparando os comandos, a única diferença é que no último,
omitimos o localhost na string de conexão, fazendo com que o Firebird
usasse uma conexão embedded.
Atribuir o role RDB$ADMIN ao usuário TESTE na base de
dados de segurança também fará com que ele tenha direito de criar
bases de dados. O problema é que não é possível conectar na base de
dados de segurança para atribuir o ROLE. Como “solução”, devemos
conectar como SYSDBA em qualquer base de dados já existente,
como por exemplo, a employee.fdb, e fazer a atribuição do ROLE
através do comando abaixo:
isql employee -user SYSDBA -pas masterkey
Database: employee, User: SYSDBA
SQL> alter user TESTE grant admin role;
SQL> commit;
SQL> quit;

O “quit” acima é necessário para sair do isql, pois ao executar o

alter user na conexão embedded, o Firebird coloca uma trava no
security3.fdb, e se tentássemos simplesmente criar a nova base de dados,
obteríamos um erro.
Agora basta entrarmos no isql para criar a base desejada:
isql
Use CONNECT or CREATE DATABASE to specify a database
SQL> create database 'localhost:c:\temp\teste.fdb' user 'TESTE'
password '1234';
SQL>

Permissões para generators e exceptions

Seguindo o SQL-2008, o Firebird 3 introduziu o conceito de

atribuir permissões para o uso de generators/sequences e exceptions. Em
resumo, quando se cria um generator ou exception, o usuário que o criou
Firebird 3 e aplicações/
comportamentos legados
 125

automaticamente tem direito de usá-los, mas os outros usuários não.

Sendo assim, se você realiza as alterações de metadata com um usuário
específico, e executa DML usando outros usuários, terá que dar o
direito de uso a eles, através do comando GRANT USAGE ON:
GRANT USAGE ON <object type> <name> TO <grantee list>
[<grant option> <granted by clause>]
--
REVOKE USAGE ON <object type> <name> FROM <grantee list>
[<granted by clause>]
--
<object type> ::= {DOMAIN | EXCEPTION | GENERATOR | SEQUENCE |
CHARACTER SET | COLLATION}

Atualmente, não é possível atribuir direitos de uso para

DOMAINS, CHARSETS nem COLLATIONS. Eles são acessíveis
por todos os usuários, mas nada impede que essa política mude no
futuro.

Firebird 3 e aplicações/
comportamentos legados