Firebird is a relational database offering many ANSI SQL-92 features that runs on Linux, Windows, and a variety of Unix platforms. Firebird offers excellent concurrency, high performance, and powerful language support for stored procedures and triggers. It has been used in production systems, under a variety of names since 1981. Firebird is a commercially independent project of C and C++ programmers, technical advisors and supporters developing and enhancing a multi-platform relational database management system based on the source code released by Inprise Corp (now known as Borland Software Corp and perhaps now CodeGear) under the InterBase Public License v.1.0 on 25 July, 2000.
When InterBase was originally released as an Open Source product, We had been users for the previous five years; supplied it with some of our bespoke software developments, and found it a reliable and powerful relational database engine for both single system and client/server operations. Now that it is Open Source we shall be making even greater use of the product.
We have created our own set of Firebird Merge Modules for use with Windows Installer, and, in the interests of ensuring commonality with other developers, we have made our Merge Modules available for wider use. The most recent set of Merge Modules are made available under the Initial Developer's Public License.
From Firebird 1.5.4 and 2.0.1 respectively, all of our Firebird Merge Modules are built using a common set of WiX scripts. These scripts ensure a consistent approach for installing Firebird Server (Classic or Super Server) and the Firebird Tools. This is a major upgrade from pervious practice for reasons outlined here.
The Merge Modules can also be used to support Firebird client applications. However, you may want to read this first.
The intended audience for these Merge Modules is Windows developers who want to install Firebird embedded with their applications and use Windows Installer (or one of its front ends e.g. WiX or recent versions of Installshield) to install their application. Not all of the Firebird distribution files are included in the Merge Modules. Specifically, developer tools, and examples are omitted. If you need these files then you need the full Firebird installation.
These merge modules support:
Installation of either the Classic or Super Server versions of the Firebird Server.
Installation under Windows 9X, NT4/2K/XP/Vista.
Installation as the Local System User or as a non-privileged user.
Automatic configuration of the Windows Firebird (under XP SP2 onwards)
The Firebird Client Merge Module installs the fbclient.dll and the supporting firebird.msg and firebird.conf files. It also creates the Firebird installation registry entry. All other Firebird Merge Modules are dependent on this Merge Module i.e. it must be included in an installation when they are required. It can also be used on its own to support an application that uses the Firebird Client Library. All files are installed into the standard Firebird Installation folder (i.e.. \Program Files\Firebird\Firebird_1_5 or \Program Files\Firebird\Firebird_2_0).
The Firebird bin directory path is also appended to the PATH environment variable. This is useful for locating the fbclient.dll and for running the command line tools (see below).
For Firebird 2.0 onwards, the Merge Module will copy the firebird.conf file from an earlier installation (if present) instead of installing a new version of firebird.conf. The new version of firebird.conf is instead installed as firebird.conf.orig.
The Firebird Command Line Tools (fbxxxtools.msm)
The Firebird Command Line Tools Merge Modules installs the command line tools (e.g. gbak, gsec, etc.) into the Firebird bin directory. use this Merge Module in installations that require these tools.
The client Merge Module must also be included when the command line tools merge module is included in an installation.
The Firebird Super Server (fbxxxSuperServer.msm)
The Firebird Super Server Merge Modules installs and starts the Firebird Super Server. Under Windows NT/2K/XP, it is installed as a Service. Under Windows 9X, it is run as an application.
The merge module also installs the security database and "aliases.conf" file.
From Firebird 1.5 onwards, an earlier version of the security database, if found, will be upgraded to the new version and location. The upgrade process uses "gbak" and the embedded server in order to ensure that the integrity of the security database. Firebird 2.0 introduces a new schema for the security database and isql is also used to upgrade security database schema. In all cases, the upgrade utilities are packaged in the merge module as a single self extracting executable.
For Firebird 2.0 onwards, the Merge Module will also copy the aliases.conf file from an earlier installation (if present) instead of installing a new version of aliases.conf. The new version of aliases.conf is instead installed as aliases.conf.orig.
This merge module also provides a configurable interface that may be used to control how the server is stopped before and uninstall or upgrade. By default, the server is stopped automatically and without user intervention. A single configurable parameter is used "FirebirdServerStop" (Display Name "Server Manual Stop"). If this is set to "yes" then the automatic stop feature is disabled and, instead:
If the installer is run with a reduced User Interface then the install/uninstall will be aborted if the server is running, with an error message telling the user to stop the Firebird Server before restarting the install/uninstall.
If the installer is run with the full User Interface, then a dialog is displayed informing the user that a server is still running and giving the user the option of aborting the install/uninstall or allowing the operation to continue with the server automatically stopped as before.
This feature may be useful for operational sites where stopping a Firebird Server unintentionally could lose user data, and gives the user the chance to organise a graceful close down if needed.
When installing the Firebird Server under Windows XP SP2 or later, the Windows firewall is automatically configured to allow remote access to the Firebrid Server.
If an earlier version of Firebird or InterBase is detected then the install is abandoned an error message is displayed telling the user to uninstall this version first. This behaviour is necessary because the Merge Module does not necessarily know how to uninstall the previous version.
The Firebird Classic Server (fbxxxClassicServer.msm)
This Merge Module is identical to the Super Server Merge Module except that it installs the classic server binary instead of the Super Server.
Note that when "Server Manual Stop" is used and the Classic Server is installed as a service, there is no Firebird Control Panel applet. Instead, the Computer Management console has to be used to stop the server manually. The API used to detect the Classic Server is not available under Windows NT and for Windows NT a Classic Server is always automatically stopped regardless of the "Server Manual Stop" setting.
The Lock Down Super Server (fbxxxLDSuperServer.msm)
This variant of the Super Server Merge Module additionally creates a local machine user (FIREBIRDSQL) if it does not already exist and installs the Firebird Server as a service logged in under this user. The FIREBIRDSQL user is also given write permission to the firebird security database and the Firebird installation folder. A Personal Folder (\Documents and Settings\FIREBIRDSQL) is also created for the FIREBIRDSQL user.
The benefit of this approach is that it mimises the risk to the rest of the system from any security holes that may be found in Firebird in the future. The downside is that databases can only be created in folders for which the FIREBIRDSQL user has write permission. On installation, this is only true for "\Documents and Settings\FIREBIRDSQL" and subfolders. On the other hand, these folders should be inaccessible to other users of the system.
This merge module will not install on Windows 9X, NT or Windows XP Home. This is because neither of these versions of Windows support the required security API. Windows XP Home is deliberately crippled in this respect. If an attempt is made to install this merge module on any of these versions of Windows, a meaningful error messasge is displayed and the installed is aborted.
The Lock Down Classic Server (fbxxxLDClassicServer.msm)
This Merge Module is identical to the Lock Down Super Server Merge Module except that it installs the classic server binary instead of the Super Server.
Note that when "Server Manual Stop" is used and the Classic Server is installed as a service, there is no Firebird Control Panel applet. Instead, the Computer Management console has to be used to stop the server manually. The API used to detect the Classic Server is not available under Windows NT and for Windows NT a Classic Server is always automatically stopped regardless of the "Server Manual Stop" setting.
Known Issues and Bugs
When using the Firebird 2.0.3 merge modules for an installation that upgrades a Firebird 2.0.1 installation also installed using these merge modules on Windows XP/SP2 or later, the Windows Firewall may no longer be open for the Firebird Server. This is due to a missing condition in the 2.0.1 Merge Module. To avoid this problem, you must either:
Tell your users to uninstall Firebird 2.0.1 Servers before upgrading to Firebird 2.0.3, or
Ensure that your installation script schedules the "RemoveExistingProducts" action before the DoOpenFirewall action imported from the Merge Module. This is readily achieved by scheduling the "RemoveExistingProducts" action before the "InstallFinalize" action and after an "InstallExecute" action.
Upgrade of Earlier Firebird Installations
With five different (major) versions of Windows out there plus Service Packs, Personal Editions and Professional Editions, and three major versions of Firebird to consider (not to mention the old InterBase versions), upgrading an existing installation has now become something of a black art. In this article, I have attempted to summarise the contortions that my Firebird Server Merge Module goes through in order to provide a smooth upgrade under whatever conditions it finds.
When seamless Upgrade is not Possible
Over-writing an old installation without understanding how it was installed is usually a good way to go about breaking an existing system. For that basic reason you should not upgrade someone else's installation. It's better to just tell the user to uninstall the older application and let it uninstall itself - an activity it knows best. This also gives the user a chance to recognise a perhaps unexpected implication of installing your application and resolve any problems before they trash their system - and at least you gave them due warning.
However, that still leaves open the question as to how do you detect an existing installation.
An installation of the Firebird Server must try and detect: older installations of Firebird done by another installer, any installation of InterBase, as well as later installations of Firebird. We need to check for the latter because sometime in the future, some user may unwittingly try and install an old version of your application on a system on which an up-to-date version of the Firebird Server has already been installed. If you don't trap this then the resulting stealth downgrade will most likely not be appreciated.
The Windows Registry is usually the best place to detect an existing installation. InterBase and Firebird have used a series of well known registry keys that they have used to record their installation folders and we can use these to search for fbserver.exe, ibserver.exe or even fb_inet_server.exe. If we find anyone of these then we know that there is an existing InterBase or Firebird Server present.
It is also possible to search for a file that was installed by a specific Windows Installer component. We can use this to search for an existing installation that was done by our installation script. All components are identified by a globally unique GUID and searching on this for the Firebird Server allows us to identify an earlier installation that we can upgrade.
The Firebird Server Merge Modules thus start with a number of targetted searches. If an InterBase installation or a Firebird installation that we can't upgrade is found, a suitable error message is emitted and the install is aborted.
The one case that isn't trapped is when a later version of InterBase or Firebird installed under a new registry key and not one that we know about. This is a real possibility. InterBase has at least three times changed its registry key and Firebird twice. (from Firebird 1 to 1.5). The only way of avoiding this risk is a whole disk search for fbserver.exe, ibserver.exe or fb_inet_server.exe. This is a lengthy process and still does not avoid all the risks, as it is still possible for someone to change the name of the server executable - and then we will never find it. My judgement call is that it is not worth forcing every installation of Firebird to be a marathon just in case some bright spark thinks it's a good idea to change the registry key yet again. I appeal to the good sense of the Firebird and InterBase developers not to change the registry keys again and, if they do, to do it in a backwards compatible manner.
Upgrading From Firebird 1
Firebird 1 was really a re-branding of InterBase 6 and most of the installation file names reflect this fact. The server is still ibserver.exe and the security database is isc4.gdb, but it did have its own registry key "SOFTWARE\FirebirdSQL\Firebird\CurrentVersion". Upgrading to Firebird 1.5 or Firebird 2 iis largely a matter of uninstalling Firebird 1 and then copying the contents of the security database to the Firebird 1.5 security.fdb or the Firebird 2 security2.fdb. (This is also true if a real InterBase 6 installation is found).
If the upgrade is to Firebird 1.5 then this is as simple as copying the file and renaming it security.fdb. However, the upgrade to Firebird 2 is more complex as the database scheme and ODS have changed. We need to backup and restore the security database and then upgrade the schema.
Upgrading from Firebird 1.5 to Firebird 2
Firebird 1.5 introduces two new user configurable files: firebird.conf and aliases.conf. These should be preserved on upgrade as they may contain important user options - and losing them could cause difficult to diagnose problems. The security database - security.fdb - also needs to be upgraded and moved to security2.fdb. As discussed above, it has to be backed up, restored and then its schema upgraded.
In addition to all this, the default installation folder has changed from \Program Files\Firebird\Firebird_1_5 to \Program Files\Firebird\Firebird_2_0 so the files have to be physically moved or copied. It is not simply a matter of not over-writing critical files.
The Firebird Server Merge Module Upgrade Approach
There are two separate problems to solve. One is moving existing firebird.conf and aliases.conf files from Firebird 1.5 to a Firebird 2.0 installation and the other is upgrading the security database.
Moving existing firebird.conf and aliases.conf files
This problem only applies to a Firebird 2 installation and it is relatively easily solved. The installer first searches for these files using the Firebird registry key and, if they are found, they are copied to the Firebird 2 installation folder. Otherwise new copies are installed. A backup copy of the installation version is always installed with a suffix '.orig' as a reference version. The files are also marked and "permanent" and "never overwrite" so user edits are not lost in future ugprades.
Upgrading the Security Database
Ideally a single strategy would be available for all cases. However, I have not been able to find a single reliable approach that works across all versions of Windows and which also allows file permissions to be correctly set in the lock down versions. Instead, different stategies are used under Windows 9X compared with later versions of Windows.
Under Windows NT4 and later, a vanilla security database is always installed by the installer. However, it does also check for an existing isc4.gdb security database, or, when Firebird 2 is being installed, for a Firebird 1.5 security.fdb security database. If one of these is found then an upgrade script is run.
The upgrade script is embedded in the Merge Module and a self-extracting executable. The Open Source 7-zip is used for this purpose and this creates a self-extractor that extracts its files into a temporary folder, runs a nominated application, and then deletes the temporary folder before terminating. The self-extracting executable contains the embedded Firebird Server, gbak, isql (Firebird 2 only) , a script (.bat) file and the upgrade SQL script (Firebird 2 only). The self-extracting executable is run after the initial installation is complete and the upgrade script will run gbak to backup and restore the database and, if necessary, run isql to upgrade the schema.
Using the embedded server frees us from the problem of persuading Firebird to update its own security database and avoids a need to know the SYDBA password. gbak restores the database directory as security.fdb or security2.fdb using the -REP switch and this ensures that it takes on the correct user access permissions i.e. those set by the installer.
The application run by the self-extractor is "cmd.exe" i.e. the Windows command line interpreter and this executes the batch script. This is better than trying to run the .bat file directly as Windows will use shellex to do this and this has been found to be problematic under NT4 with long file names escaped by double quotes.
This same issues of long file names escaped by double quotes is why the strategy does not work for Windows 9X. command.com, the old MSDOS command line interpreter seems to limit long file name to 32 characters when used as .bat file parameters and this is too short for reliable operation of the backup script. On the other hand, because Firebird always runs as an application under Windows 9X and hence the script can easily stop and start the server, a different approach is possible.
This is to directly script the upgrade process as Windows Installer Custom Actions, running gbak (and isql) as separate steps. This works, however, it uses the newly installed server to perform the operations and hence it is not possible to restore the database to its correct location in one step. Instead, we have to restore it to a temporary location, stop the server, move the database to its correct location, and then restart the server.
This strategy works fine under Windows 9X, but does not easily translate to the other versions of Windows which run the Firebird Server as a Windows Service. Moving the database rather than replacing the existing database also does not allow a easy strategy for setting correct user access permissions in the lock down version. Thus the two strategy approach seems to be the best compromise.
Merge Module Installation
You will need a tool that creates and maintains Windows Installer .msi files to make use of the Merge Modules, such as Installshield Express or Developer (but not Professional), or Wise for Windows Installer. The Windows Installer XML (WiX) platform is also supported by these Merge Moduiles and recommended for intermediate and advanced users.
This page is not necessarily up-to-date and other tools can also make use of the merge modules which are not recorded here.
WiX
No special action is needed to use the Merge Modules with WiX scripts. Simply unzip the Merge Modules into a suitable folder and then reference the path to the Merge Module in a <Merge> tag.
Note that the Classic and Super Server Merge Modules support User Configuration. See the example installation scripts for examples of how to use the configurable interface from WiX scripts.
Installshield Express
With Installshield Express 3., all you need to do is to copy the .msm files into the "objects" subdirectory in the Installshield 3 installation directory. They are then available for use in the list of "Objects/Merge Modules" as soon as you start Installshield.
Later versions of Express (e.g. 3.53) can also be configured like Installshield Developer.
Installshield Developer
For Installshield Developer (and later versions of Installshield Express), it is best to copy the merge modules to a separate directory and to set the Merge Module search path to include this directory. This is done from Installshield (Express or Developer) from the "File Locations" tab in the "Tools->Options" dialog where you must add the path to the directory in which the InterBase merge modules are located to the list of "Merge Module Locations". The next time you view the Merge Module gallery, the Firebird Merge Modules will be available in the list of Merge Modules.
Wise for Windows Installer
For Wise for Windows Installer, the installation process is very similar, except that the search path for Merge Modules is set from the "Directories" tab in the "Edit->Preferences" dialog.
Other tools will have different strategies for incorporating Merge Modules. Please refer to the product documentation.
Using the Merge Modules
Even if you are familiar with our earlier Merge Modules for Firebird, you should read this page.
If you are using the Merge Modules to support an application installation then you will need only to include the Client Merge Module with your installation script. Under Installshield Express, this is done by selecting it from the list of "redistributable". Optionally, you may also include the command line tools Merge Module, if you wish your users to have access to these tools.
If you the Merge Modules to install a Firebird Server then you need to include both the Client and one of the Server Merge Module with your installation script. Optionally, you may also include the command line tools Merge Module, if you wish your users to have access to these tools. Note that the Server Merge Modules are mutually incompatible and only one can be included.
Typically, you will include either the Classic or the Super Server Merge Module and configure it, if required, to prompt the user to allow stopping a running server prior to upgrade or uninstall.
If you are targeting Lock Down environments, then you may prefer to use the lock down versions of the Merge Modules. These install the Firebird Server under a normal user account "FIREBIRDSQL" and it will run with that user's privileges. However, note that the Lock Down versions will not install under Windows 9X, NT4 or a Personal (crippled) version of Windows XP. This is because the required API is not available.
