FirebirdSQL logo

Ce matériel a été créé avec le soutien et le parrainage de iBase.ru, une société qui développe des outils Firebird SQL pour les entreprises et fournit des services d’assistance technique pour Firebird SQL.

Le matériel est publié sous la licence de documentation publique https://www.firebirdsql.org/file/documentation/html/en/licenses/pdl/public-documentation-license.html

Introduction

Cet article s’adresse principalement à ceux qui prévoient passer à Firebird 5.0 dans un avenir rapproché. De nombreux administrateurs utilisent encore Firebird 2.5, mais prévoient de passer à la version 5.0. C’est pourquoi cet article décrit le processus de migration à partir des versions 2.5, 3.0 et 4.0 de Firebird.

Le sponsor de l’article « Migration Guide to Firebird 5.0 » est IBSurgeon (iBase.ru) (https://www.ib-aid.com, https://www.ibase.ru) : support technique et outils de développement et d’administration pour le SGBD Firebird.

Installation manuelle de Firebird 5.0 sous Windows

Ce qui suit décrit comment installer à partir d’une archive zip. Même si vous installez Firebird à partir d’une trousse d’installation spéciale, il se peut que vous ayez à modifier certains paramètres après l’installation. De plus, l’installation manuelle vous permet d’installer plusieurs versions de Firebird sur la même machine.

Téléchargez l’archive de débit appropriée et extrayez-la dans le répertoire où se trouvera le serveur Firebird.

L’étape suivante consiste à créer un utilisateur SYSDBA. Pour les administrateurs qui ont migré de Firebird 3.0 ou 4.0, cette opération n’est pas nouvelle. Dans Firebird 2.5 et les versions antérieures, l’utilisateur SYSDBA existait toujours après l’installation et avait un mot de passe par défaut de masterke, qui devait être changé immédiatement.

Initialisation de SYSDBA

Depuis Firebird 3.0, l’utilisateur SYSDBA n’est pas initialisé par défaut (pour le plugin de gestion des utilisateurs SRP), il est donc nécessaire de créer explicitement un utilisateur et de lui donner un mot de passe. Cela peut être fait de deux manières : en utilisant l’outil de console isql.exe pour exécuter des requêtes interactives et l’outil de console gsec.exe pour gérer la base de données de sécurité.

Note
Remarque

Selon le déploiement de Firebird, ces utilitaires peuvent devoir être exécutés avec des privilèges d’administrateur.

Initialisation de SYSDBA avec ISQL

Exécutez l’outil de requête interactif isql.exe.Se connecter à la base de données de sécurité en mode serveur intégré, en spécifiant l’utilisateur SYSDBA sans mot de passe.L’utilisateur SYSDBA n’existe pas encore dans la base de données de sécurité, mais en mode intégré, l’utilisateur et son mot de passe ne sont pas vérifiés, et Firebird fait confiance à tout nom d’utilisateur spécifié.Exécutez une requête SQL pour créer un utilisateur SYSDBA :

CREATE USER SYSDBA PASSWORD '<password>';

L’utilisateur SYSDBA est initialisé, vous pouvez quitter le mode interactif.

Example 1. Initialisation du SYSDBA via ISQL
c:\Firebird\5.0>isql security.db -user SYSDBA

Database: security.db, User: SYSDBA

SQL> CREATE USER SYSDBA PASSWORD 'm8ku234pp';
SQL> exit;

Initialisation de SYSDBA avec GSEC

Exécutez gsec.exe, en spécifiant l’utilisateur SYSDBA et la base de données security.db.Exécutez la commande pour ajouter un utilisateur SYSDBA :

add SYSDBA -pw <password>
Example 2. Initialisation de SYSDBA via GSEC
c:\Firebird\5.0>gsec -user SYSDBA -database security.db

* gsec est obsolète et sera bientôt supprimé *

GSEC> add SYSDBA -pw m8ku234pp
GSEC> quit
Warning
Avertissement

L’outil gsec.exe est obsolète, de nombreuses fonctionnalités disponibles via SQL ne sont pas disponibles dans cet outil.

Configuration

Avant de pouvoir installer et exécuter Firebird en tant que service, vous devez sélectionner un mode serveur.

Mode serveur

Par défaut, Firebird démarre en mode SuperServer. Si vous voulez que le serveur démarre dans une architecture différente, vous devez changer la valeur du paramètre ServerMode dans firebird.conf. Décommentez-le (enlevez le caractère dièse '#') et définissez le mode désiré : Super, SuperClassic ou Classic.

ServerMode = Classic

Autorisation des bibliothèques client Firebird 2.5

Firebird 5.0 utilise par défaut l’authentification par mot de passe sécurisé (SRP). Les clients Firebird 2.5 et antérieurs utilisaient l’authentification traditionnelle (Legacy_Auth), qui est désactivée par défaut dans Firebird 5.0 parce qu’elle n’est pas sécurisée.

Les paramètres suivants AuthServer, UserManager et WireCrypt doivent être modifiés pour prendre en charge l’authentification traditionnelle.

Example 3. Permettre l’autorisation avec les versions antérieures du client Firebird
AuthServer = Srp256, Srp, Legacy_Auth
UserManager = Srp, Legacy_UserManager
WireCrypt = Enabled

Après les manipulations ci-dessus, nous aurons deux gestionnaires d’utilisateurs actifs. Par défaut, c’est le premier de la liste des gestionnaires d’utilisateurs qui est actif.

Important
Important

Les utilisateurs portant le même nom dans différents gestionnaires d’utilisateurs sont des utilisateurs différents et peuvent avoir des mots de passe différents. Cela s’applique également à SYSDBA et au propriétaire de la base de données.
Note

Si vous n’avez pas besoin du support pour l’authentification par mot de passe sécurisé (SRP), supprimez les plugins Srp256 et Srp de AuthServer ; supprimez Srp de UserManager ; et vous pouvez changer WireCrypt en Disabled.

Précédemment, nous avons déjà créé un SYSDBA dans le gestionnaire des utilisateurs SRP. Dans Legacy_UserManager, SYSDBA existe déjà, et avec un mot de passe standard masterkey, qui doit être changé. Nous allons le faire en utilisant l’outil isql. Dans la déclaration ALTER USER, il est nécessaire de spécifier le Legacy_UserManager.

Example 4. Modification du mot de passe SYSDBA dans Legacy_UserManager
c:\Firebird\5.0>isql security.db -user SYSDBA

Database: security.db, User: SYSDBA

SQL> ALTER USER SYSDBA SET PASSWORD 'er34gfde' USING PLUGIN Legacy_UserManager;
SQL> exit;

Réglage du fuseau horaire de connexion par défaut

A partir de Firebird 4.0, de nouveaux types de date et d’heure avec prise en charge des fuseaux horaires sont disponibles.

Même si vous n’avez pas l’intention d’utiliser des types avec des fuseaux horaires de sitôt, vous devez savoir que les expressions CURRENT_TIMESTAMP et CURRENT_TIME renvoient maintenant des types de données avec des fuseaux horaires. Il existe un mode de compatibilité qui vous permet de convertir les types avec des fuseaux horaires en types sans fuseaux horaires. Toutefois, cette conversion peut ne pas fonctionner correctement si le fuseau horaire de la connexion est mal défini.

Normalement, le fuseau horaire de la session est défini du côté du client. Si le fuseau horaire côté client n’est pas défini, le fuseau horaire par défaut est celui du système d’exploitation. Vous pouvez également définir le fuseau horaire par défaut de la session en utilisant le paramètre de configuration DefaultTimeZone.

DefaultTimeZone = Europe/Moscow

Exécution simultanée de plusieurs instances Firebird

Nous partons ici du principe que vous souhaitez faire fonctionner des instances de différentes versions de Firebird, chacune étant installée dans un répertoire différent.

Pour démarrer plusieurs instances de Firebird en même temps, il est nécessaire de les répartir sur des ports tcp différents (si, bien sûr, le listener fonctionne en mode d’écoute TCP/IP). Pour ce faire, changez le paramètre RemoteServicePort dans firebird.conf.

Par exemple, si vous avez déjà un serveur qui écoute sur le port 3050, vous devriez définir un autre port libre, tel que 3051. Dans ce cas, vous devrez spécifier le nouveau port dans la chaîne de connexion (sauf si firebird.conf avec le numéro de port par défaut modifié est disponible pour l’application et le client Firebird).

RemoteServicePort = 3051

Il est également nécessaire de définir des valeurs uniques pour le paramètre IpcName pour chaque instance de serveur SGBD. Cela évitera les messages d’erreur dans firebird.log. Ces erreurs ne sont pas critiques si vous n’utilisez pas le protocole XNET. Cependant, si vous l’utilisez, vous devez prendre en compte le fait que ce paramètre devra être modifié du côté client via DPB.

Installation et fonctionnement de Firebird en tant que service

L’utilitaire instsvc.exe écrit, supprime ou modifie les informations de démarrage du serveur dans la base de données des services du système d’exploitation. Il permet également de contrôler le démarrage et l’arrêt des services.

Si vous l’exécutez sans paramètres, il affichera de l’aide sur les commandes et les paramètres.

instsvc
Usage:
  instsvc i[nstall]
                    [ -a[uto]* | -d[emand] ]
                    [ -g[uardian] ]
                    [ -l[ogin] username [password] ]
                    [ -n[ame] instance ]
                    [ -i[nteractive] ]

          sta[rt]   [ -b[oostpriority] ]
                    [ -n[ame] instance ]
          sto[p]    [ -n[ame] instance ]
          q[uery]
          r[emove]  [ -n[ame] instance ]


  '*' indique les valeurs par défaut
  '-z' peut être utilisé avec n'importe quelle autre option, version imprimée
  'username' fait référence par défaut à un compte local sur cette machine.
  Utilisez le format "domain\username" ou "server\username" si nécessaire.
Important
Important

L’utilitaire instsvc doit être exécuté dans une console avec des privilèges administratifs (exécuter la console en tant qu’administrateur).

Pour installer le service, vous devez entrer la commande suivante

instsvc install

Dans ce cas, Firebird sera installé en tant que service nommé "Firebird Server - DefaultInstance". Ce service sera lancé automatiquement au démarrage du système d’exploitation, sous le compte LocalSystem dédié aux services.

Si vous souhaitez que plusieurs instances de Firebird fonctionnent en tant que services, vous devez leur donner des noms différents en utilisant l’option -n.

instsvc install -n fb50

Pour démarrer le service, utilisez la commande

instsvc start

Si le service a été installé avec un nom autre que celui par défaut, vous devez utiliser le commutateur -n.

instsvc start -n fb50

Pour arrêter le service, utilisez la commande

instsvc stop

Si le service a été installé avec un nom autre que celui par défaut, vous devez utiliser le commutateur -n.

instsvc stop -n fb50

Pour supprimer un service, entrez la commande

instsvc remove

Si le service a été installé avec un nom autre que celui par défaut, vous devez utiliser le commutateur -n.

instsvc remove -n fb50

Pour afficher tous les services Firebird installés dans le système, utilisez la commande

instsvc query
Firebird Server - fb30 IS installed.
  Status  : running
  Path    : C:\Firebird\3.0\firebird.exe -s fb30
  Startup : automatic
  Run as  : LocalSystem

Firebird Server - fb40 IS installed.
  Status  : running
  Path    : C:\Firebird\4.0\firebird.exe -s fb40
  Startup : automatic
  Run as  : LocalSystem

Firebird Server - fb50 IS installed.
  Status  : running
  Path    : C:\Firebird\5.0\firebird.exe -s fb50
  Startup : automatic
  Run as  : LocalSystem

Utilisation de install_service.bat et uninstall_service.bat

Pour simplifier l’installation et la désinstallation des services, deux fichiers BAT, install_service.bat et uninstall_service.bat, sont fournis avec Firebird dans une archive ZIP.

Dans ce cas, la procédure d’installation de Firebird en tant que service est la suivante

install_service.bat

Dans ce cas, la procédure de désinstallation du service Firebird est la suivante

uninstall_service.bat

S’il est nécessaire de donner au service un nom différent de celui par défaut, spécifiez ce nom en tant qu’argument

install_service.bat fb50

Si le service a été installé avec un nom autre que celui par défaut, spécifiez ce nom en tant qu’argument

uninstall_service.bat fb50

Installation du client

Si seule la partie client doit être installée, le fichier fbclient.dll est nécessaire. Le client Firebird 5.0 nécessite l’installation de Microsoft Runtime C++ 2015-2022 avec le débit binaire approprié. Si cette bibliothèque n’est pas installée, vous pouvez copier les bibliothèques supplémentaires fournies dans l’archive ZIP pour Windows msvcp140.dll et vcruntime140.dll (pour l’installation 64-bit également vcruntime140_1.dll).

Il est souhaitable d’avoir un fichier de messages firebird.msg à côté de fbclient.dll. La plupart des messages d’erreur sont déjà contenus dans fbclient.dll, mais si vous voulez utiliser les utilitaires de la console, le fichier firebird.msg doit être présent.

Contrairement à Firebird 2.5 et Firebird 3.0, la bibliothèque client nécessite également les fichiers ICU (icudt63.dll, icuin63.dll, icuuc63.dll et icudt63l.dat). Auparavant, la bibliothèque ICU n’était requise que par le serveur. Maintenant, elle peut être requise par le client si vous allez travailler avec les types de données TIMESTAMP WITH TIME ZONE et TIME WITH TIME ZONE. La bibliothèque ICU est également requise lors de l’appel des fonctions UtilInterface::decodeTimeTz() et UtilInterface::decodeTimestampTz().

Note
Remarque

Windows 10 peut utiliser la bibliothèque ICU fournie avec le système d’exploitation.

Si la compression du trafic est nécessaire lors de l’utilisation de TCP/IP, la bibliothèque zlib1.dll est requise.

Vous pouvez avoir besoin de la bibliothèque plugins/chacha.dll si vous avez l’intention d’utiliser le plugin de cryptage du trafic ChaCha. Ce plugin est utilisé par défaut depuis Firebird 4.0, car il est le premier listé dans le paramètre de configuration WireCryptPlugin = ChaCha, Arc4.

Note
Note sur le chargement des plug-ins

La version 3.0 de fbclient.dll ne chargeait pas par défaut les plugins des bibliothèques dynamiques du répertoire plugins. fbclient.dll version 4.0 et plus utilise plugins/chacha.dll par défaut si ce plugin est présent. Les plugins absents sont ignorés.

Cependant, il y a une caractéristique importante. fbclient.dll recherche dans son répertoire le fichier firebird.conf, et s’il est manquant, il essaie de le trouver dans le répertoire supérieur. Le répertoire où firebird.conf est trouvé est le répertoire racine — à partir duquel tous les autres chemins relatifs connus (plugins, intl) sont utilisé.

Ce comportement peut vous jouer un mauvais tour. Le fait est que l’installateur 64 bits localise la bibliothèque 32 bits fbclient.dll dans le dossier $(fbroot)/WOW64. Si vous voulez utiliser la bibliothèque à partir de ce répertoire, vous pouvez obtenir le message d’erreur suivant

Error loading plugin ChaCha.
Module C:\Firebird\5.0\plugins/ChaCha exists but can not be loaded.
unknown Win32 error 193.

Dans ce cas, le fichier 32-bit fbclient.dll essayait de charger le plugin 64-bit ChaCha.

Pour corriger cette erreur, il suffit de placer le fichier firebird.conf dans le dossier $(fbroot)/WOW64.

La bibliothèque fbclient.dll, ainsi que les autres fichiers de la bibliothèque du client, doivent être situés soit près de l’application, soit dans l’un des répertoires dans lesquels la recherche est effectuée, par exemple ajouté à PATH ou au répertoire système pour les bibliothèques publiques (system32 ou SysWOW64).

Important
Important

Placer la bibliothèque du client dans le PATH peut interférer avec d’autres applications qui nécessitent une bibliothèque du client d’une version différente ou d’un serveur différent. Par conséquent, si une application est supposée fonctionner indépendamment d’autres applications avec une version particulière du client, les fichiers du client doivent être placés dans le dossier de l’application, et le chemin ne doit pas être écrit dans le PATH.

Utilité instclient

Pour déployer la bibliothèque client Firebird dans le répertoire système de Windows, utilisez la commande

instclient install fbclient
Important
Important

L’utilitaire instclient ne copie aucun fichier autre que fbclient.dll dans le répertoire système.

Installation de la version embedded

Depuis Firebird 3.0, la version intégrée n’est plus distribuée séparément. Vous pouvez utiliser le même ensemble de fichiers à la fois en tant que serveur réseau et en tant que serveur intégré. Cependant, si vous avez besoin d’un ensemble de fichiers de taille minimale, la structure des fichiers et des répertoires pour Firebird 5.0 embedded est la suivante :

  • intl

    • fbintl.conf

    • fbintl.dll

  • plugins

    • engine13.dll

  • firebird.conf

  • icudt63l.dat

  • fbclient.dll

  • ib_util.dll

  • icudt63.dll

  • icuin63.dll

  • icuuc63.dll

  • msvcp140.dll

  • vcruntime140.dll

  • vcruntime140_1.dll

  • firebird.msg

Si nécessaire, vous pouvez également copier les exécutables des utilitaires fbsvcmgr.exe, fbtracemgr.exe, gbak.exe, gfix.exe, gstat.exe, isql.exe, nbackup.exe. Si vous allez utiliser gbak avec le commutateur -zip, vous aurez également besoin de la bibliothèque zlib1.dll.

Note
Remarque

Pour ceux qui migrent depuis Firebird 2.5, il y a deux choses à prendre en compte :

  • Plusieurs fichiers sont nécessaires au lieu d’une seule bibliothèque fbembed.dll, et le fichier fbclient.dll ne peut pas être renommé. Les composants d’accès doivent utiliser la bibliothèque fbclient.dll comme point d’entrée.

  • Dans le fichier de configuration firebird.conf, le paramètre ServerMode doit être changé en SuperClassic ou Classic pour permettre l’accès à la même base de données à partir de différentes applications embarquées sur le même ordinateur (comportement embarqué de Firebird 2.5 par défaut).

Conversion de la base de données dans un nouveau format

Les bases de données Firebird 5.0 ont un ODS (On-Disk Structure) de 13.1. Pour que Firebird 5.0 fonctionne avec votre base de données, celle-ci doit être ramenée à l’ODS natif. Cela se fait généralement en utilisant l’outil gbak. Cependant, ne vous précipitez pas pour sauvegarder votre base de données et la restaurer avec la nouvelle ODS - vous devez d’abord résoudre les éventuels problèmes de compatibilité.

Liste des incompatibilités au niveau du langage SQL

Des problèmes de compatibilité avec le langage SQL sont possibles tant pour les objets de la base de données eux-mêmes (procédures et fonctions PSQL) que pour les requêtes DSQL utilisées dans votre application.

La méthode suivante est recommandée pour détecter les problèmes de compatibilité SQL pour les objets de la base de données. Effectuer l’extraction des métadonnées de la base de données dans un script sur une ancienne version de Firebird.

isql <database> -x -o create_script.sql

Commentez l’instruction CREATE DATABASE à l’intérieur du script, faites les modifications nécessaires, et essayez de créer une nouvelle base de données à partir du script dans Firebird 5.0 :

isql -i create_script.sql -o error.log -m

où la clé -i est le fichier d’entrée du script ; la clé -o est le fichier de messages de sortie ; la clé -m fait en sorte que isql produise des messages d’erreur dans le fichier de messages de sortie.

Nous recherchons ensuite les erreurs dans le fichier error.log et, si nous en trouvons, nous modifions les métadonnées dans la base de données source. Répétez l’algorithme ci-dessus jusqu’à ce que toutes les erreurs soient éliminées. Après cela, vous pouvez sauvegarder/restaurer en toute sécurité.

Voici quelques-uns des problèmes de compatibilité les plus courants au niveau de SQL que vous pouvez résoudre avant de passer au nouvel ODS. Vous pouvez consulter la liste complète des incompatibilités dans les notes de mise à jour 5.0 au chapitre "Problèmes de compatibilité". Si vous migrez à partir de la version 3.0, vous devez également lire le chapitre du même nom dans les notes de mise à jour 4.0, et si vous migrez à partir de la version 2.5 — notes de mise à jour 3.0.

Nouveaux mots réservés

Vérifiez que votre base de données ne contient pas de nouveaux mots réservés dans les identificateurs, les colonnes et les variables. Dans le premier dialecte SQL, ces mots ne peuvent en principe pas être utilisés (vous devrez les renommer). Dans le dialect 3, ils peuvent être utilisés, mais doivent être encadrés par des guillemets doubles.

Vous trouverez une liste des nouveaux mots-clés et des mots réservés dans les notes de version 3.0 et 4.0 au chapitre Mots réservés et changements. Les mots-clés peuvent être utilisés comme identifiants, bien que cela ne soit pas recommandé.

Depuis Firebird 5.0, vous pouvez afficher la liste complète des mots-clés et des mots réservés avec une requête :

SELECT
  RDB$KEYWORD_NAME,
  RDB$KEYWORD_RESERVED
FROM RDB$KEYWORDS

Cette requête peut être exécutée sur n’importe quelle base de données avec ODS 13.1, telle que employee.db fournie avec Firebird 5.0.

La colonne RDB$KEYWORD_NAME contient le mot-clé lui-même, et RDB$KEYWORD_RESERVED indique si le mot-clé est réservé.

Noms de colonnes dans les curseurs PSQL

Concerne : lors de la migration à partir de Firebird 2.5.

Toutes les colonnes de sortie des curseurs PSQL déclarés comme DECLARE CURSOR doivent avoir un nom explicite ou un alias. La même chose s’applique aux curseurs PSQL utilisés en tant que FOR SELECT …​ AS CURSOR <cursor name> DO …​.

Example 5. Problème avec les colonnes non nommées dans les curseurs
create procedure sp_test
returns (n int)
as
  declare c cursor for (select 1 /* as a */ from rdb$database);
begin
  open c;
  fetch c into n;
  close c;
  suspend;
end
Statement failed, SQLSTATE = 42000
unsuccessful metadata update
-ALTER PROCEDURE SP_TEST failed
-Dynamic SQL Error
-SQL error code = -104
-Invalid command
-no column name specified for column number 1 in derived table C

Nouveaux types de données

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Firebird 4.0 introduit de nouveaux types de données :

  • TIMESTAMP WITH TIME ZONE

  • TIME WITH TIME ZONE

  • INT128

  • NUMERIC(38, x) et DECIMAL(38, x)

  • DECFLOAT(16) et DECFLOAT(34)

Les deux derniers types ne posent pas beaucoup de problèmes parce que vous ne les avez jamais utilisés auparavant et que les expressions ne les renvoient généralement pas.

Certaines expressions peuvent maintenant retourner les types NUMERIC(38, x), DECIMAL(38, x) et INT128. Nous parlerons de la solution de ce problème plus tard, car ils ne sont généralement pas visibles au stade de la modification de l’ODS.

Les expressions CURRENT_TIMESTAMP et CURRENT_TIME renvoient maintenant les types TIMESTAMP WITH TIME ZONE et TIME WITH TIME ZONE.

Pour les anciennes bibliothèques et applications clientes, vous pouvez installer le type mode de compatibilité, Cependant, cela ne sera pas utile dans les procédures stockées, les fonctions et les déclencheurs. Vous devez utiliser les expressions LOCALTIMESTAMP et LOCALTIME au lieu de CURRENT_TIMESTAMP et CURRENT_TIME lorsque vous ne voulez pas obtenir des types de données avec des fuseaux horaires. Ces expressions ont été spécifiquement introduites dans les versions correctives de Firebird 2.5.9 et Firebird 3.0.4 afin que vous puissiez préparer vos bases de données à l’avance pour la migration vers Firebird 4.0 et plus.

L’affectation d’une variable (colonne) de type TIMESTAMP à la valeur de l’expression CURRENT_TIMESTAMP effectuera une conversion de type, c’est-à-dire un CAST(CURRENT_TIMESTAMP AS TIMESTAMP) implicite, de sorte que même sans remplacer CURRENT_TIMESTAMP et CURRENT_TIME par LOCALTIMESTAMP et LOCALTIME, tout fonctionnera toujours, mais les performances peuvent chuter dans certains cas. Par exemple :

create global temporary table gtt_test (
    id  integer not null,
    t   timestamp default current_timestamp
) on commit preserve rows;

alter table gtt_test add constraint pk_gtt_test primary key (id);

Ici, le champ t est de type TIMESTAMP et CURRENT_TIMESTAMP renvoie TIMESTAMP WITH TIME ZONE, ce qui réduit les performances de INSERT dans une telle table.

Note

Ce cas est détaillé dans le bug tracker, ticket 7854.

Initialement, la baisse de performance était de 30%, ce qui est assez significatif, mais après un certain nombre d’optimisations, l’overhead a été réduit à 3-5%. Si vous ne voulez pas de coûts inutiles, il est préférable d’utiliser LOCALTIMESTAMP lorsque vous n’avez pas l’intention d’opérer avec le fuseau horaire.

Caractères littéraux de la date et de l’heure

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Firebird 4.0 a redéfini la syntaxe des valeurs littérales de la date et de l’heure.

Les littéraux 'NOW', 'TODAY', 'TOMORROW', 'YESTERDAY' avec les préfixes TIMESTAMP, DATE, TIME sont désormais interdits. La raison en est que la valeur de ces littéraux était calculée lors de la préparation des requêtes DSQL ou de la compilation des modules PSQL, ce qui conduisait à des résultats inattendus.

Si quelque chose comme TIMESTAMP 'NOW' a été utilisé dans des requêtes DSQL dans le code de l’application ou dans le PSQL porté, il y aura un problème de compatibilité avec Firebird 4 et plus.

Example 6. Le code suivant ne sera pas compilé
..
DECLARE VARIABLE moment TIMESTAMP;
..
SELECT TIMESTAMP 'NOW' FROM RDB$DATABASE INTO :moment;

/* ici, la variable : moment sera "gelée" en tant qu'horodatage au moment de la dernière compilation de la procédure ou de la fonction.  */
..

Vous devez éliminer ces littéraux, par exemple en les remplaçant par une conversion explicite CAST('NOW' AS TIMESTAMP), dans le code de vos procédures et fonctions avant de convertir votre base de données vers le nouvel ODS.

En outre, il convient de vérifier d’autres éléments littéraux de date et d’heure avec l’attribution explicite d’une date (heure) connue. Auparavant, ces littéraux permettaient de délimiter des parties de la date et de l’heure qui n’étaient pas conformes à la norme. Désormais, ces délimiteurs sont interdits. Vous pouvez en savoir plus sur les formats autorisés pour les littéraux de date et d’heure dans le "Firebird 5.0 SQL Language Guide" dans le chapitre "Litérals de Date et Heure".

INSERT … RETURNING exige le privilège SELECT

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Depuis Firebird 4.0, si une instruction INSERT contient une phrase RETURNING qui fait référence à des colonnes de la table de base, l’appelant doit se voir accorder le privilège SELECT approprié.

Effet de stabilité du curseur

Concerne : lors de la migration à partir de Firebird 2.5.

Firebird 3.0 a apporté une amélioration importante appelée "stabilité du curseur". En conséquence de cette amélioration, certaines requêtes peuvent fonctionner différemment. Ceci est particulièrement vrai pour les requêtes qui modifient une table et la lisent dans le même curseur. La stabilité du curseur élimine de nombreux bogues présents dans les versions précédentes de Firebird, dont le plus célèbre est la boucle infinie dans une requête :

INSERT INTO some_table
SELECT * FROM some_table

Il est peu probable que vos applications contiennent uniquement des demandes de ce type, mais la stabilité du curseur peut ne pas apparaître dans des cas évidents :

  • un déclencheur DML modifie une table, puis le même déclencheur lit cette table via une instruction SELECT. Si les données ont été modifiées en dehors du contexte actuel de l’exécution du déclencheur, il est possible que les changements ne soient pas visibles dans la requête SELECT ;

  • La procédure stockée sélective SP_SOME modifie les enregistrements d’une table SOME_TABLE, puis vous effectuez un JOIN avec la même table :

    FOR
  SELECT ...
  FROM SP_SOME(...) S
  JOIN SOME_TABLE ...

Si vous avez de tels cas dans votre code, nous vous recommandons de réécrire ces parties pour prendre en compte l’effet de la "stabilité du curseur".

La prise en charge des fonctions externes (UDF) a été déclarée obsolète.

La prise en charge des fonctions externes (UDF) a été déclarée obsolète à partir de Firebird 4.

L’effet de ceci est que UDF ne peut pas être utilisé avec la configuration par défaut, puisque la valeur par défaut du paramètre UdfAccess dans firebird.conf est maintenant None. Les bibliothèques UDF ib_udf et fbudf ont été supprimées de la distribution.

La plupart des fonctions de ces bibliothèques ont déjà été dépréciées dans les versions précédentes de Firebird et ont été remplacées par leurs équivalents intégrés. Des remplacements sûrs pour certaines des fonctions restantes sont maintenant disponibles, soit dans une nouvelle bibliothèque de sous-routines définies par l’utilisateur (UDR) nommée [lib]udf_compat.[dll/so/dylib] (ceci est fait après la modification de l’ODS), soit sous forme de conversions scriptées vers des fonctions PSQL stockées.

Nous recommandons de remplacer les fonctions UDF par leurs équivalents intégrés à l’avance (avant de migrer vers un nouvel ODS). Si vous migrez de Firebird 3.0, vous pouvez également réécrire certaines fonctions en PSQL.

Si vous avez encore des fonctions UDF après ces étapes, vous devez modifier le paramètre de configuration

UdfAccess = Restrict UDF

Conversion de la base de données vers le nouvel ODS

Après une préparation préliminaire, vous pouvez essayer de convertir la base de données vers le nouvel ODS à l’aide de l’outil gbak.

Note

Il est recommandé de toujours commencer par une sauvegarde/restauration des métadonnées :

old_version\gbak -b -g -m old_db stdout | new_version\gbak -c -m stdin new_db

Sinon, vous risquez d’obtenir une erreur de métadonnées après que tout le téraoctet de données a été écrit, ce qui sera très frustrant. En outre, il est pratique de vérifier le travail des scripts de recompilation des objets de la base de données sur les métadonnées restaurées dans la nouvelle version.

Cet exemple suppose que Firebird 3.0 et Firebird 5.0 se trouvent sur la même machine. Firebird 3.0 fonctionne sur le port TCP 3053 et Firebird 5.0 sur le port TCP 3055.

Tout d’abord, vous devez sauvegarder votre base de données dans la version actuelle de Firebird en utilisant la commande suivante.

gbak -b -g -V -user <username> -pas <password> -se <service> <database> <backup_file> -Y <log_file>
Example 7. Création d’une sauvegarde sur la version actuelle de Firebird
gbak -b -g -V -user SYSDBA -pas 8kej712 -se server/3053:service_mgr my_db d:\fb30_backup\my_db.fbk -Y d:\fb30_backup\backup.log

Ensuite, vous devez restaurer votre copie vers Firebird 5.0.

gbak -c -v -user <username> -pas <password> -se <service> <backup_file> <database_file> -Y <log_file>

Depuis Firebird 5.0, l’utilitaire gbak peut sauvegarder et restaurer une base de données en utilisant le parallélisme. Le nombre de threads parallèles utilisés pendant la sauvegarde ou la restauration est spécifié avec l’option -parallel ou -par. L’utilisation de threads parallèles peut accélérer le processus de restauration de 2 à 3 fois, en fonction de votre matériel et de votre base de données.

Le parallélisme est désactivé par défaut dans Firebird 5.0. Pour pouvoir l’utiliser, le paramètre MaxParallelWorkers doit être défini dans firebird.conf.Ce paramètre limite le nombre maximum de threads parallèles qui peuvent être utilisés par le noyau Firebird ou ses utilitaires. La valeur par défaut est 1. Il est recommandé de fixer MaxParallelWorkers à une valeur égale au nombre maximum de cœurs physiques ou logiques de votre processeur (ou de vos processeurs).

Vous pouvez maintenant utiliser la commande suivante pour restaurer.

gbak -c -par <N>  -v -user <username> -pas <password> -se <service> <backup_file> <database_file> -Y <log_file>

Ici N est le nombre de threads parallèles que gbak va utiliser, il doit être inférieur ou égal à la valeur fixée dans MaxParallelWorkers.

Example 8. Restaurer une sauvegarde sur Firebird 5.0 en utilisant 8 threads parallèles
gbak -c -par 8 -v -user SYSDBA -pas 8kej712 -se server/3055:service_mgr d:\fb30_backup\my_db.fbk d:\fb50_data\my_db.fdb -Y d:\fb50_data\restore.log
Important
Important

Notez les commutateurs -V et -Y, ils doivent absolument être utilisés pour que vous puissiez voir dans le fichier journal ce qui s’est mal passé pendant le processus de restauration.

Après la restauration, examinez attentivement le fichier restore.log à la recherche d’erreurs. Cependant, il n’y aura pas d’erreurs d’incompatibilité au niveau SQL dans ce journal, parce que les objets de la base de données ne sont pas recompilés pendant la restauration. Si une procédure ou un trigger contient des constructions incompatibles, une erreur sera générée plus tard lors de l’opération ALTER d’un tel objet.

La seule façon d’éliminer complètement ces erreurs de la base de données est d’extraire le script de la base de données à l’aide de l’opération

isql -x <database> > script.sql

dans une version précédente de Firebird, et de créer une base de données vide dans Firebird 5.0 à partir de ce script, en corrigeant une à une les erreurs de création de métadonnées qui en résultent.

Avertissements concernant les UDF manquants

Après la restauration, vous pouvez voir les avertissements suivants dans le fichier restore.log.

gbak: WARNING:function UDF_FRAC is not defined
gbak: WARNING: module name or entrypoint could not be found

Cela signifie que vous avez des UDF qui sont déclarés dans la base de données, mais que leur bibliothèque est manquante. Ce que vous devez faire dans ce cas a déjà été décrit ci-dessus. Mais il s’agissait principalement de vos bibliothèques d’UDF. Cependant, si vous avez utilisé des UDFs du kit fourni avec Firebird, à savoir ib_udf et fbudf, vous pouvez les remplacer par des fonctions intégrées ou par des analogues UDR sûrs situés dans la bibliothèque udf_compat.dll. Pour ce faire, vous devez exécuter le script SQL de migration fourni avec Firebird 5.0, qui se trouve dans misc/upgrade/v4.0/udf_replace.sql. Cela se fait avec la commande suivante

isql -user sysdba -pas masterkey -i udf_replace.sql {your-database}
Example 9. Avertissement

Ce scénario n’affectera pas les déclarations UDF provenant de bibliothèques tierces !

Mise à jour rapide de l’ODS lors de la migration depuis Firebird 4.0

Si vous migrez depuis Firebird 4.0, il existe un moyen plus rapide de mettre à jour l’ODS que la sauvegarde/restauration.

La méthode traditionnelle pour mettre à jour une ODS (On-Disk Structure) consiste à effectuer une sauvegarde sur l’ancienne version de Firebird et à la restaurer sur la nouvelle. Il s’agit d’un processus assez long, en particulier pour les grandes bases de données.

Cependant, dans le cas d’une mise à niveau d’une version mineure de l’ODS (le numéro après le point), la sauvegarde/restauration est redondante (seuls les tables et champs système manquants et certains paquets doivent être ajoutés). Un exemple d’une telle mise à jour est la mise à jour d’ODS 13.0 (Firebird 4.0) vers ODS 13.1 (Firebird 5.0), puisque la version majeure d’ODS 13 reste la même.

A partir de Firebird 5.0, il est maintenant possible de mettre à jour une version mineure d’ODS sans avoir à effectuer une longue opération de sauvegarde et de restauration. L’utilitaire gfix avec le commutateur -upgrade est utilisé dans ce but.

Points clés :

  • La mise à jour doit être effectuée manuellement en utilisant la commande gfix -upgrade.

  • Un accès monopolistique à la base de données est nécessaire, sinon une erreur est générée.

  • Privilège système requis USE_GFIX_UTILITY.

  • La mise à jour est transactionnelle, toutes les modifications sont annulées en cas d’erreur.

  • Après la mise à jour de Firebird 4.0, il ne peut plus ouvrir la base de données.

Note

  • Il s’agit d’une modification à sens unique, il n’y a pas de retour en arrière possible. Donc avant de mettre à jour, faites une copie de la base de données (avec nbackup -b 0) pour avoir un point de restauration si quelque chose se passe mal pendant le processus.

  • La mise à jour de l’ODS avec gfix -upgrade ne modifie pas les pages de données des tables utilisateur, donc les enregistrements ne seront pas reconditionnés en utilisant le nouvel algorithme de compression RLE. Mais les enregistrements nouvellement insérés seront compressés en utilisant l’algorithme RLE amélioré.

Vous devez donc suivre les étapes ci-dessous pour mettre à jour rapidement votre ODS :

  • Faites une sauvegarde de la base de données, par exemple avec nbackup -b 0, afin d’avoir un point de restauration en cas de problème.

  • Exécuter la commande :

    gfix -upgrade <dbname> -user <username> -pass <password>

Cette méthode de mise à jour de l’ODS, contrairement à la sauvegarde/restauration, prend quelques secondes (nous parlons de gfix -upgrade), et non des minutes ou des heures.

Transfert des alias de base de données

Cette section concerne les personnes qui migrent depuis Firebird 2.5.

Le fichier aliases.conf dans lequel les alias de base de données étaient configurés a été renommé en databases.conf. Il est entièrement compatible avec la syntaxe antérieure, mais son objectif a été considérablement élargi. Il vous permet maintenant de définir des paramètres individuels pour chaque base de données. Nous vous recommandons fortement de profiter de cette fonctionnalité si votre serveur dessert plus d’une base de données.

Les paramètres qui peuvent être définis au niveau de la base de données sont étiquetés "Configurable par base de données" dans le fichier firebird.conf.

Migration des listes d’utilisateurs

Le transfert de la liste des utilisateurs à partir des versions 2.5, 3.0 et 4.0 de Firebird se fait différemment.

Migration des listes d’utilisateurs depuis Firebird 4.0

Le plus simple serait de migrer la liste des utilisateurs de Firebird 4.0.

Pour migrer la base de données de sécurité de Firebird 4.0 vers 5.0, sauvegardez le fichier security4.fdb en utilisant gbak Firebird 4.0 et restaurez-le en tant que security5.fdb en utilisant gbak Firebird 5.0. Utilisez gbak localement (en utilisant une connexion en ligne) lorsque le serveur Firebird n’est pas en cours d’exécution.

Note

Copier le fichier security4.fdb et le renommer en security5.fdb et mettre à jour l’ODS avec l’option gfix -UPGRADE peut également fonctionner, mais nous recommandons d’effectuer une sauvegarde et une restauration.

Transférer la liste des utilisateurs de Firebird 3.0

Pour migrer les utilisateurs de la base de données de sécurité Firebird 3.0 vers la base de données de sécurité Firebird 4.0, vous devez sauvegarder security3.fdb en utilisant gbak et la restaurer en tant que security5.fdb en utilisant gbak Firebird 5.0.

Toutefois, sachez que dans ce cas, vous perdrez certaines nouvelles fonctionnalités. Nous allons donc opter pour la solution la plus compliquée :

  1. Sauvegarder la base de données de sécurité sur Firebird 3.0

    c:\Firebird\3.0>gbak -b -g -user SYSDBA security.db d:\fb30_backup\security.fbk

  2. Restaurer la sauvegarde vers Firebird 5.0 sous un nouveau nom

    c:\Firebird\5.0>gbak -c -user SYSDBA -pas 8kej712 -se localhost/3054:service_mgr d:\fb30_backup\security.fbk d:\fb50_data\security_30.fdb

  3. Enregistrez le script suivant pour migrer les utilisateurs dans le fichier copy_user.sql.

    set term ^;

EXECUTE BLOCK
AS
  -- remplacer par les paramètres de la copie de votre base de données de sécurité
  DECLARE SRC_SEC_DB     VARCHAR(255) = 'd:\fb50_data\security_30.fdb';
  DECLARE SRC_SEC_USER   VARCHAR(63) = 'SYSDBA';
  ---------------------------------------------------
  DECLARE PLG$USER_NAME  SEC$USER_NAME;
  DECLARE PLG$VERIFIER   VARCHAR(128) CHARACTER SET OCTETS;
  DECLARE PLG$SALT       VARCHAR(32) CHARACTER SET OCTETS;
  DECLARE PLG$COMMENT    BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
  DECLARE PLG$FIRST      SEC$NAME_PART;
  DECLARE PLG$MIDDLE     SEC$NAME_PART;
  DECLARE PLG$LAST       SEC$NAME_PART;
  DECLARE PLG$ATTRIBUTES BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
  DECLARE PLG$ACTIVE     BOOLEAN;
  DECLARE PLG$GROUP_NAME SEC$USER_NAME;
  DECLARE PLG$UID        PLG$ID;
  DECLARE PLG$GID        PLG$ID;
  DECLARE PLG$PASSWD     PLG$PASSWD;
BEGIN
  -- déplacer des utilisateurs du plugin SRP
  FOR EXECUTE STATEMENT Q'!
      SELECT
          PLG$USER_NAME,
          PLG$VERIFIER,
          PLG$SALT,
          PLG$COMMENT,
          PLG$FIRST,
          PLG$MIDDLE,
          PLG$LAST,
          PLG$ATTRIBUTES,
          PLG$ACTIVE
      FROM PLG$SRP
      WHERE PLG$USER_NAME <> 'SYSDBA' !'
          ON EXTERNAL :SRC_SEC_DB
          AS USER :SRC_SEC_USER
          INTO :PLG$USER_NAME,
               :PLG$VERIFIER,
               :PLG$SALT,
               :PLG$COMMENT,
               :PLG$FIRST,
               :PLG$MIDDLE,
               :PLG$LAST,
               :PLG$ATTRIBUTES,
               :PLG$ACTIVE
  DO
  BEGIN
    INSERT INTO PLG$SRP (
        PLG$USER_NAME,
        PLG$VERIFIER,
        PLG$SALT,
        PLG$COMMENT,
        PLG$FIRST,
        PLG$MIDDLE,
        PLG$LAST,
        PLG$ATTRIBUTES,
        PLG$ACTIVE)
    VALUES (
        :PLG$USER_NAME,
        :PLG$VERIFIER,
        :PLG$SALT,
        :PLG$COMMENT,
        :PLG$FIRST,
        :PLG$MIDDLE,
        :PLG$LAST,
        :PLG$ATTRIBUTES,
        :PLG$ACTIVE);
  END
  -- déplacer les utilisateurs du plugin Legacy_UserManager
  FOR EXECUTE STATEMENT Q'!
      SELECT
          PLG$USER_NAME,
          PLG$GROUP_NAME,
          PLG$UID,
          PLG$GID,
          PLG$PASSWD,
          PLG$COMMENT,
          PLG$FIRST_NAME,
          PLG$MIDDLE_NAME,
          PLG$LAST_NAME
      FROM PLG$USERS
      WHERE PLG$USER_NAME <> 'SYSDBA'
!'
          ON EXTERNAL :SRC_SEC_DB
          AS USER :SRC_SEC_USER
          INTO :PLG$USER_NAME,
               :PLG$GROUP_NAME,
               :PLG$UID,
               :PLG$GID,
               :PLG$PASSWD,
               :PLG$COMMENT,
               :PLG$FIRST,
               :PLG$MIDDLE,
               :PLG$LAST
  DO
  BEGIN
    INSERT INTO PLG$USERS (
        PLG$USER_NAME,
        PLG$GROUP_NAME,
        PLG$UID,
        PLG$GID,
        PLG$PASSWD,
        PLG$COMMENT,
        PLG$FIRST_NAME,
        PLG$MIDDLE_NAME,
        PLG$LAST_NAME)
    VALUES (
        :PLG$USER_NAME,
        :PLG$GROUP_NAME,
        :PLG$UID,
        :PLG$GID,
        :PLG$PASSWD,
        :PLG$COMMENT,
        :PLG$FIRST,
        :PLG$MIDDLE,
        :PLG$LAST);
  END
END^

set term ;^

commit;

exit;
    Important
    Important

    N’oubliez pas de remplacer la valeur de la variable SRC_SEC_DB par le chemin d’accès à votre copie de la base de données de sécurité.
    Note
    Remarque

    Nous avons exclu une copie de l’utilisateur SYSDBA car nous l’avons initialisé lors de l’installation.

  4. Exécutez le script sur Firebird 5.0 en vous connectant à la base de données de sécurité en mode intégré.

    c:\Firebird\5.0>isql -i "d:\fb50_data\copy_users.sql" -u SYSDBA -ch UTF8 security.db

Félicitations ! Vos utilisateurs ont été migrés avec tous les attributs et mots de passe intacts.

Transférer la liste des utilisateurs de Firebird 2.5

La migration des utilisateurs de Firebird 2.5 est plus complexe.Firebird 3.0 a introduit une nouvelle méthode d’authentification SRP - Secure Remote Password Protocol.L’ancienne méthode d’authentification est également disponible, mais elle est désactivée par défaut car elle n’est pas considérée comme suffisamment sûre.Les notes de mise à jour 3.0 décrivent un moyen de déplacer les utilisateurs de Legacy_UserManager vers SRP, mais dans ce cas, vous ne pourrez pas vous connecter via fbclient version 2.5. En outre, il n’est pas possible de transférer les mots de passe de Legacy_UserManager vers SRP.Le script proposé migrera la liste des utilisateurs, mais des mots de passe aléatoires seront générés.Si vous souhaitez restaurer des mots de passe antérieurs, vous devrez le faire manuellement.J’ai écrit un script alternatif qui vous permet de migrer les utilisateurs de security2.fdb vers security5.fdb dans le plugin Legacy_UserManager.Je décrirai ici les deux options.

Copie de la liste des utilisateurs dans le plugin SRP

En raison du nouveau modèle d’authentification de Firebird 3, il n’est pas possible de mettre à niveau la base de données de sécurité de la version 2.5 (security2.fdb) directement pour l’utiliser dans Firebird 5. Cependant, il existe une procédure de mise à niveau qui vous permet de conserver les données des comptes d’utilisateurs - nom d’utilisateur, nom et autres attributs, mais pas les mots de passe - de la base de données security2.fdb qui était utilisée sur les serveurs de la version 2.x.

La procédure nécessite l’exécution du script security_database.sql, qui se trouve dans le répertoire misc/upgrade de votre installation de Firebird 3. Ces instructions supposent que vous avez une copie temporaire de ce script dans le même répertoire que l’exécutable isql.

Note
Remarque

  • Dans Firebird 5.0, le fichier script de mise à jour de la base de données de sécurité security_database.sql est absent du répertoire misc/upgrade, vous devez donc télécharger l’archive zip avec la distribution de Firebird 3.0.

  • Dans les commandes ci-dessous, remplacez masterkey par le mot de passe SYSDBA de votre serveur, si nécessaire.

  1. Sauvegarder la base de données de sécurité security2.fdb sur Firebird 2.5

    c:\Firebird\2.5>bin\gbak -b -g -user SYSDBA -password masterkey -se service_mgr c:\Firebird\2.5\security2.fdb d:
\fb25_backup\security2.fbk

  2. Déployer la sauvegarde vers Firebird 5.0

    c:\Firebird\5.0>gbak -c -user SYSDBA -password masterkey -se localhost/3054:service_mgr d:\fbdata\5.0\security2.fbk d:\f
bdata\5.0\security2db.fdb -v

  3. Sur un serveur Firebird 5.0, naviguez jusqu’au répertoire où se trouve l’utilitaire isql et exécutez le script de mise à niveau :

    isql -user sysdba -pas masterkey -i security_database.sql
{host/path}security2db.fdb

    security2db.fdb - n’est qu’un exemple de nom de base de données : il peut s’agir de n’importe quel nom préféré.

  4. La procédure génère de nouveaux mots de passe aléatoires et les affiche à l’écran. Copiez la sortie et informez les utilisateurs de leurs nouveaux mots de passe.

Copie de la liste des utilisateurs dans le plugin Legacy_UserManager

Contrairement à l’option précédente, ce script sauvegardera vos mots de passe originaux. Cependant, nous vous conseillons de passer au plugin Srp à l’avenir.

  1. Sauvegarder la base de données de sécurité security2.fdb sur Firebird 2.5

    c:\Firebird\2.5>bin\gbak -b -g -user SYSDBA -password masterkey -se service_mgr c:\Firebird\2.5\security2.fdb d:\fb25_backup\security2.fbk

  2. Déployer la sauvegarde vers Firebird 5.0

    c:\Firebird\5.0>gbak -c -user SYSDBA -password masterkey -se localhost/3054:service_mgr d:\fbdata\5.0\security2.fbk d:\fbdata\5.0\security2db.fdb -v

  3. Enregistrez le script suivant pour migrer les utilisateurs dans le fichier copy_security2.sql.

    set term ^;

EXECUTE BLOCK
AS
  -- remplacer par les paramètres de la copie de votre base de données de sécurité
  DECLARE SRC_SEC_DB     VARCHAR(255) = 'd:\fbdata\5.0\security2.fdb';
  DECLARE SRC_SEC_USER   VARCHAR(63) = 'SYSDBA';
  ---------------------------------------------------
  DECLARE PLG$USER_NAME  SEC$USER_NAME;
  DECLARE PLG$COMMENT    BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
  DECLARE PLG$FIRST      SEC$NAME_PART;
  DECLARE PLG$MIDDLE     SEC$NAME_PART;
  DECLARE PLG$LAST       SEC$NAME_PART;
  DECLARE PLG$GROUP_NAME SEC$USER_NAME;
  DECLARE PLG$UID        INT;
  DECLARE PLG$GID        INT;
  DECLARE PLG$PASSWD     VARBINARY(64);
BEGIN
  FOR EXECUTE STATEMENT q'!
      SELECT
          RDB$USER_NAME,
          RDB$GROUP_NAME,
          RDB$UID,
          RDB$GID,
          RDB$PASSWD,
          RDB$COMMENT,
          RDB$FIRST_NAME,
          RDB$MIDDLE_NAME,
          RDB$LAST_NAME
      FROM RDB$USERS
      WHERE RDB$USER_NAME <> 'SYSDBA'
!'
      ON EXTERNAL :SRC_SEC_DB
      AS USER :SRC_SEC_USER
      INTO
          :PLG$USER_NAME,
          :PLG$GROUP_NAME,
          :PLG$UID,
          :PLG$GID,
          :PLG$PASSWD,
          :PLG$COMMENT,
          :PLG$FIRST,
          :PLG$MIDDLE,
          :PLG$LAST
  DO
  BEGIN
    INSERT INTO PLG$USERS (
        PLG$USER_NAME,
        PLG$GROUP_NAME,
        PLG$UID,
        PLG$GID,
        PLG$PASSWD,
        PLG$COMMENT,
        PLG$FIRST_NAME,
        PLG$MIDDLE_NAME,
        PLG$LAST_NAME)
    VALUES (
        :PLG$USER_NAME,
        :PLG$GROUP_NAME,
        :PLG$UID,
        :PLG$GID,
        :PLG$PASSWD,
        :PLG$COMMENT,
        :PLG$FIRST,
        :PLG$MIDDLE,
        :PLG$LAST);
  END
END^

set term ;^

commit;

exit;
    Important
    Important

    N’oubliez pas de remplacer la valeur de la variable SRC_SEC_DB par le chemin d’accès à votre copie de la base de données de sécurité.
    Note
    Remarque

    Nous avons exclu une copie de l’utilisateur SYSDBA car nous l’avons initialisé lors de l’installation.

  4. Exécutez le script sur Firebird 5.0 en vous connectant à la base de données de sécurité en mode intégré.

    c:\Firebird\5.0>isql -i "d:\fb40_data\copy_security2.sql" -u SYSDBA -ch UTF8 security.db

Félicitations ! Vos utilisateurs ont été migrés avec tous les attributs et mots de passe intacts.

Configuration de l’authentification de confiance

La mise en place de l’authentification de confiance (trusted authentication) dans Firebird 5.0 se fait de la même manière que dans Firebird 3.0 ou 4.0. Pour ceux qui migrent de Firebird 2.5, nous décrirons ce processus plus en détail.

  1. La première chose à faire est d’activer le plugin d’authentification de confiance dans le fichier de configuration firebird.conf ou databases.conf dans le paramètre AuthServer (il est désactivé par défaut).Pour ce faire, nous devons ajouter un plugin nommé Win_Sspi, et nous l’utiliserons avec Srp256.

    AuthServer = Srp256, Win_Sspi

  2. L’étape suivante consiste à activer le mappage des utilisateurs de Win_Sspi vers CURRENT_USER. Pour ce faire, créez le mappage dans la base de données cible à l’aide de la requête suivante

    CREATE MAPPING TRUSTED_AUTH
USING PLUGIN WIN_SSPI
FROM ANY USER
TO USER;

    Cette requête SQL crée une correspondance uniquement au niveau de la base de données actuelle.Le mappage ne sera pas appliqué à d’autres bases de données situées sur le même serveur.Si vous souhaitez créer une correspondance commune à toutes les bases de données, ajoutez le mot-clé GLOBAL.

    CREATE GLOBAL MAPPING TRUSTED_AUTH
USING PLUGIN WIN_SSPI
FROM ANY USER
TO USER;

  3. Activer l’accès de type SYSDBA pour les administrateurs Windows (si nécessaire).

    Pour permettre cet accès, le mappage suivant doit être créé

    CREATE MAPPING WIN_ADMINS
USING PLUGIN WIN_SSPI
FROM Predefined_Group
DOMAIN_ANY_RID_ADMINS
TO ROLE RDB$ADMIN;

    Au lieu d’accorder un accès de type SYSDBA à tous les administrateurs Windows, vous pouvez accorder des privilèges administratifs à un utilisateur spécifique en utilisant le mappage suivant

    create global mapping cto_sysdba
using plugin win_sspi
from user "STATION9\DEVELOPER"
to user SYSDBA;

Incompatibilités au niveau de l’application

Au niveau de l’API, la bibliothèque client fbclient 5.0 est compatible avec les versions précédentes. Cependant, il peut y avoir des problèmes de compatibilité au niveau de certaines requêtes SQL. La plupart d’entre elles ont déjà été décrites dans la section Liste des incompatibilités au niveau du langage SQL.Ensuite, décrivons quelques autres problèmes qui peuvent survenir dans l’application.

Suppression du protocole réseau WNET

Le protocole réseau WNET (alias Named Pipes, alias NetBEUI), précédemment pris en charge sur la plate-forme Windows, est supprimé dans Firebird 5.0.

Les utilisateurs de Windows qui ont travaillé avec une chaîne de connexion WNET (\\Nserver\Ndbname ou wnet://server/dbname`) doivent passer au protocole INET (TCP) (chaîne de connexion server:dbname`, server/port:dbname, inet://server/dbname`, ou inet://server:port/dbname`) à la place.

Nouveaux types de données

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Comme indiqué précédemment, certaines expressions peuvent renvoyer de nouveaux types de données qui ne peuvent pas être interprétés par votre application sans la modifier.Un tel affinage peut prendre beaucoup de temps ou peut être au-delà de vos capacités.Pour simplifier la migration vers de nouvelles versions, vous pouvez définir le paramètre DataTypeCompatibility pour qu’il soit compatible avec la version souhaitée dans firebird.conf ou databases.conf.

DataTypeCompatibility = 3.0

ou

DataTypeCompatibility = 2.5

C’est le moyen le plus rapide d’assurer la compatibilité avec les nouveaux types de données.Cependant, au fil du temps, vous pouvez commencer à intégrer la prise en charge de nouveaux types dans votre application.Naturellement, cela se fera progressivement - d’abord un type, puis un autre et ainsi de suite.Dans ce cas, vous devez configurer le mappage des types dont vous n’avez pas encore finalisé la prise en charge avec d’autres types de données.L’opérateur SET BIND OF est utilisé à cette fin.

Syntaxe
SET BIND OF { <type-from> | TIME ZONE } TO { <type-to> | LEGACY | NATIVE | EXTENDED }

Le mot-clé LEGACY dans la partie TO est utilisé lorsqu’un type de données non présent dans une version précédente de Firebird doit être représenté d’une manière compréhensible pour les anciens logiciels clients (une certaine perte de données peut se produire). Il existe les conversions suivantes vers les types LEGACY :

Table 1. Conversions vers les anciens types
DataTypeCompatibility Native type Legacy type

2.5

BOOLEAN

CHAR(5)

2.5 ou 3.0

DECFLOAT

DOUBLE PRECISION

2.5 ou 3.0

INT128

BIGINT

2.5 ou 3.0

TIME WITH TIME ZONE

TIME WITHOUT TIME ZONE

2.5 ou 3.0

TIMESTAMP WITH TIME ZONE

TIMESTAMP WITHOUT TIME ZONE

Lorsque le paramètre DataTypeCompatibility est défini, les nouveaux types de données sont convertis en types hérités selon le tableau décrit ci-dessus.

Une description détaillée de cette déclaration est disponible dans "Firebird 4.0 Release Notes" et "Firebird 5.0 SQL Language Guide".Grâce à lui, vous pouvez contrôler l’affichage des nouveaux types dans votre application en exécutant la requête appropriée immédiatement après la connexion, et même écrire un déclencheur AFTER CONNECT dans lequel vous pouvez utiliser plusieurs de ces opérateurs.

Par exemple, supposons que vous ayez ajouté le support de la date et de l’heure avec les fuseaux horaires à votre application, mais que vous n’ayez toujours pas le support des types INT128 et DECFLOAT. Dans ce cas, vous pouvez écrire le trigger suivant.

create or alter trigger tr_ac_set_bind
on connect
as
begin
  set bind of int128 to legacy;
  set bind of decfloat to legacy;
end

Lecture agréée dans les transactions READ COMMITTED

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Firebird 4 introduit non seulement la cohérence en lecture (READ CONSISTENCY) pour les requêtes dans les transactions READ COMMITTED, mais en fait aussi le mode par défaut pour toutes les transactions READ COMMITTED, indépendamment de leurs propriétés RECORD VERSION ou NO RECORD VERSION.

L’objectif est d’offrir aux utilisateurs un meilleur comportement, à la fois conforme à la spécification SQL et moins sujet aux conflits. Toutefois, ce nouveau comportement peut également avoir des effets secondaires inattendus.

Le plus important d’entre eux est sans doute le redémarrage lors de la gestion des conflits de mise à jour. Certains codes qui ne sont pas soumis au contrôle transactionnel peuvent ainsi être exécutés plusieurs fois dans PSQL. Voici quelques exemples de ce type de code :

  • l’utilisation de tableaux, de séquences ou de variables contextuelles externes ;

  • l’envoi de courriers électroniques à l’aide d’UDF ;

  • Utilisation de transactions hors ligne ou de requêtes externes.

Note

Dans le mode d’isolation READ COMMITTED READ CONSISTENCY, le conflit de mise à jour est géré différemment. Si pendant l’exécution de UPDATE ou DELETE un enregistrement est trouvé qui a déjà été modifié ou supprimé par une autre transaction (transaction confirmée), toutes les modifications faites dans la requête courante sont annulées et la requête est exécutée à nouveau. C’est ce qu’on appelle redémarrer la requête.

Vous pouvez en savoir plus sur les lectures cohérentes dans les transactions READ COMMITTED dans les "Firebird 4.0 Release Notes".

Un autre effet important est que les curseurs sous-déclarés dans les transactions READ COMMITTED READ CONSISTENCY en mode lecture seule tiennent maintenant la collecte des déchets.Nous vous recommandons d’éviter d’utiliser une seule longue transaction READ COMMITTED READ ONLY dans votre application, et de la remplacer par plusieurs transactions de ce type, chacune d’entre elles étant active exactement pendant la durée nécessaire.

Si les caractéristiques du mode READ CONSISTENCY ne sont pas souhaitables pour une raison quelconque, le paramètre de configuration ReadConsistency doit être mis à 0 pour revenir à l’ancien comportement.

Changements dans l’optimiseur

L’optimiseur change dans chaque version de Firebird. La plupart de ces changements sont positifs, c’est-à-dire que vos requêtes devraient s’exécuter plus rapidement, mais certaines requêtes peuvent ralentir. Vous devez donc tester les performances de votre application, et s’il y a un ralentissement quelque part, l’intervention du programmeur est nécessaire.

Pour la plupart des modifications de l’optimiseur, vous ne pouvez pas affecter le plan de requête en modifiant la configuration du serveur. Dans ce cas, vous pouvez procéder comme suit :

  • réécrire la requête SQL pour qu’elle s’exécute plus rapidement sur la nouvelle version du serveur ;

  • créer ou supprimer des index ;

  • Si aucune des solutions ci-dessus ne vous a aidé, créez un ticket de régression à l’adresse suivante FirebirdSQL ticket.

Il y a quelques éléments de l’optimiseur qui peuvent être affectés par la modification de la configuration :

Utilisation de Refetch pour le tri de grands ensembles de données

Concerne : lors de la migration à partir des versions 2.5 et 3.0 de Firebird.

Depuis Firebird 4.0, une nouvelle méthode d’accès Refetch a été introduite pour optimiser le tri des ensembles de données larges. Un ensemble de données large est un ensemble de données dans lequel la longueur totale des champs d’enregistrement est importante.

Historiquement, lorsqu’il effectue un tri externe, Firebird écrit à la fois les champs clés (c’est-à-dire ceux spécifiés dans la phrase ORDER BY ou GROUP BY) et les champs non-clés (tous les autres champs référencés dans la requête) dans des blocs de tri qui sont soit stockés en mémoire, soit dans des fichiers temporaires. Une fois le tri terminé, ces champs sont relus à partir des blocs de tri.Cette approche est généralement considérée comme plus rapide car les enregistrements sont lus à partir des fichiers temporaires dans l’ordre des enregistrements triés, plutôt que d’être sélectionnés de manière aléatoire à partir de la page de données.Cependant, si les champs non-clés sont grands (par exemple, de longs VARCHARs sont utilisés), cela augmente la taille des blocs de tri et résulte donc en plus d’opérations d’entrées-sorties pour les fichiers temporaires. Firebird 4 offre une approche alternative (méthode d’accès Refetch) où seuls les champs clés et les enregistrements DBKEY sont stockés à l’intérieur des blocs de tri, et les champs non-clés sont récupérés à partir des pages de données après le tri. Cela permet d’améliorer les performances de tri dans le cas de longs champs non clés.

Ainsi, les plans de vos requêtes qui utilisent le tri peuvent changer. Un nouveau paramètre de configuration InlineSortThreshold est introduit pour contrôler cette méthode d’accès. La valeur spécifiée pour InlineSortThreshold définit la taille maximale d’un enregistrement de tri (en octets) qui peut être stocké en ligne, c’est-à-dire à l’intérieur d’un bloc de tri. Zéro signifie que les enregistrements sont toujours rechargés. La valeur optimale de ce paramètre doit être choisie de manière expérimentale. La valeur par défaut est de 1000 octets.

Prenons l’exemple suivant :

SELECT
  field_1, field_2, field_3, field_4
FROM SomeTable
ORDER BY field_1

Avant Firebird 4.0, les 4 champs étaient toujours inclus dans les blocs de tri. Depuis Firebird 4.0, si la longueur totale des champs field_1 . field_4 dépasse la valeur de InlineSortThreshold, seul field_1 sera inclus dans les blocs de tri et ensuite Refetch sera exécuté.

Conversion des JOIN OUTER en JOIN INNER

L’optimisation des JOIN OUTER dans Firebird pose un certain nombre de problèmes.

Tout d’abord, le OUTER JOIN ne peut actuellement être exécuté que par un seul algorithme de connexion NESTED LOOP JOIN, ce qui pourrait être modifié dans les versions futures.

Deuxièmement, lorsque les threads sont reliés par des connexions externes, l’ordre de connexion est strictement fixe, c’est-à-dire que l’optimiseur ne peut pas le modifier pour que le résultat reste correct.

Cependant, s’il y a un prédicat pour le champ WHERE de la table "de droite" (jointe) dans la condition WHERE qui ne gère pas explicitement la valeur NULL, il n’y a pas d’intérêt à faire une jointure externe. Dans ce cas, à partir de Firebird 5.0, une telle jointure sera convertie en jointure interne, permettant à l’optimiseur d’appliquer la gamme complète des algorithmes de jointure disponibles.

Supposons que vous ayez la requête suivante :

SELECT
  COUNT(*)
FROM
  HORSE
  LEFT JOIN FARM ON FARM.CODE_FARM = HORSE.CODE_FARM
WHERE FARM.CODE_COUNTRY = 1

Firebird 5.0 convertira implicitement une telle requête en une forme équivalente :

SELECT
  COUNT(*)
FROM
  HORSE
  JOIN FARM ON FARM.CODE_FARM = HORSE.CODE_FARM
WHERE FARM.CODE_COUNTRY = 1

Si LEFT JOIN a été utilisé comme un indice pour spécifier l’ordre de jointure de manière très active, il peut être problématique de réécrire de nombreuses requêtes d’une nouvelle manière. Pour ces développeurs, il existe un paramètre de configuration OuterJoinConversion dans firebird.conf ou database.conf. Mettre le paramètre OuterJoinConversion à false désactive la transformation des jointures externes en jointures internes. Notez que ce paramètre est une solution temporaire pour faciliter la migration et peut être supprimé dans les versions futures de Firebird.

RETURNING, retour d’un ensemble d’enregistrements

Depuis Firebird 5.0, les instructions de modification du client INSERT . SELECT, UPDATE, DELETE, UPDATE OR INSERT et MERGE contenant une clause RETURNING retournent un curseur, c’est à dire qu’elles sont capables de retourner plusieurs enregistrements au lieu de donner l’erreur "multiple rows in singleton select" comme auparavant.

Ces requêtes pendant la préparation sont maintenant décrites comme isc_info_sql_sql_stmt_select, alors que dans les versions précédentes elles étaient décrites comme isc_info_sql_sql_stmt_exec_procedure.

Les opérateurs singleton INSERT …​ VALUES, ainsi que les instructions UPDATE et DELETE positionnées (c’est-à-dire, qui contiennent une clause WHERE CURRENT OF) conservent le comportement existant et sont décrites comme isc_info_sql_sql_stmt_exec_procedure.

Cependant, toutes ces requêtes, si elles sont utilisées dans PSQL et que la phrase RETURNING est appliquée, sont toujours traitées comme des singletons.

Si votre application utilise des instructions de modification INSERT . SELECT, UPDATE, DELETE, UPDATE OR INSERT, et MERGE contenant une phrase RETURNING, elle peut provoquer des erreurs. Assurez-vous que votre pilote ou composant d’accès gère correctement ces requêtes, et si ce n’est pas le cas, modifiez le code (de l’application ou du composant) ou attendez une mise à jour du pilote/composant correspondant qui gère ces requêtes correctement.

Exemples de modification d’opérateurs contenant RETURNING, et de retour d’un ensemble de données :

INSERT INTO dest(name, val)
SELECT desc, num + 1 FROM src WHERE id_parent = 5
RETURNING id, name, val;

UPDATE dest
SET a = a + 1
WHERE id = ?
RETURNING id, a;

DELETE FROM dest
WHERE price < 0.52
RETURNING id;

MERGE INTO PRODUCT_INVENTORY AS TARGET
USING (
  SELECT
    SL.ID_PRODUCT,
    SUM(SL.QUANTITY)
  FROM
    SALES_ORDER_LINE SL
    JOIN SALES_ORDER S ON S.ID = SL.ID_SALES_ORDER
  WHERE S.BYDATE = CURRENT_DATE
    AND SL.ID_PRODUCT = :ID_PRODUCT
  GROUP BY 1
) AS SRC(ID_PRODUCT, QUANTITY)
ON TARGET.ID_PRODUCT = SRC.ID_PRODUCT
WHEN MATCHED AND TARGET.QUANTITY - SRC.QUANTITY <= 0 THEN
  DELETE
WHEN MATCHED THEN
  UPDATE SET
    TARGET.QUANTITY = TARGET.QUANTITY - SRC.QUANTITY,
    TARGET.BYDATE = CURRENT_DATE
RETURNING OLD.QUANTITY, NEW.QUANTITY, SRC.QUANTITY;

Conclusion

Dans cet article, j’ai essayé de décrire les problèmes les plus courants et leurs solutions lors de la migration vers Firebird 5.0 à partir de Firebird 2.5, 3.0 et 4.0. J’espère que cet article vous aidera à migrer vos bases de données et vos applications vers Firebird 5.0 et à profiter de tous les avantages de la nouvelle version.