Firebird 2 Migration & Installation

Helen Borrie (Collator/Editor)
17 June 2009 - Document v. mi213_02 - for Firebird 2.1.3

Firebird 2 Migration & Installation
17 June 2009 - Document v. mi213_02 - for Firebird 2.1.3 Helen Borrie (Collator/Editor)

Table of Contents
1. Known Compatibility Issues ............................................................................................................... 1 Changes to Note in V.2.1 ............................................................................................................... 1 The FIREBIRD Variable ................................................................................................................ 1 Security in Firebird 2 (All Platforms) .............................................................................................. 2 Trusted Authentication on Windows ....................................................................................... 2 SQL Migration Issues .................................................................................................................... 3 DDL ...................................................................................................................................... 3 DML ..................................................................................................................................... 4 PSQL .................................................................................................................................... 7 Configuration Parameters ............................................................................................................... 8 Command-line Tools ...................................................................................................................... 8 Change to gbak -R Semantics ................................................................................................. 8 Performance ................................................................................................................................... 8 Firebird API .................................................................................................................................. 9 Windows-Specific Issues .............................................................................................................. 10 Windows Local Connection Protocol with XNet .................................................................... 10 Client Impersonation No Longer Works ................................................................................ 10 Interactive Option Added to instsvc.exe ................................................................................ 10 2. INSTALLATION NOTES ................................................................................................................ 12 Choosing a Server Model ............................................................................................................. 12 Database Compatibility Among Models ................................................................................. 12 Full Servers ......................................................................................................................... 12 Embedded ............................................................................................................................ 13 3. Installing on Windows ...................................................................................................................... 14 Installation Choices ...................................................................................................................... 14 Choosing an Installation Method ........................................................................................... 14 READ THIS FIRST! .................................................................................................................... 15 Naming databases on Windows ............................................................................................. 17 Microsoft C/C++ Runtime Libraries ...................................................................................... 17 Other Pre-installation Issues .................................................................................................. 19 Using the Firebird Installer ........................................................................................................... 21 What Now? .......................................................................................................................... 24 Uninstallation ....................................................................................................................... 24 Installing Firebird from a zip kit ................................................................................................... 25 Superserver .......................................................................................................................... 25 Installing Classic Server from a zip kit .................................................................................. 25 Simplified setup ................................................................................................................... 26 Uninstallation ....................................................................................................................... 26 Windows Embedded ..................................................................................................................... 26 Registry ............................................................................................................................... 26 Database Access ................................................................................................................... 27 Authentication and Security .................................................................................................. 27 Compatibility ....................................................................................................................... 27 Installing an Embedded Server Application ........................................................................... 27 Installation Structure Examples ............................................................................................. 28 Client-only Installs ....................................................................................................................... 29 The firebird.msg File ............................................................................................................ 29 Other Libraries or Files Needed by Clients ............................................................................ 29 iv

................................................................................................................................... What the Linux install scripts will do ....................................................... Debian ............................................. Testing your Linux installation ................................................. Special Topics ............................................................................................................................................................................ READ THIS FIRST .......................................................................... 4................................................ Linux Server Tips ......................................................................................................... Linux Platforms ............... 29 30 30 30 31 31 32 34 34 34 35 36 37 38 39 39 40 40 41 41 41 41 v .................................... MacOSX ................................. Managing MSVC8 Assemblies ............................................................................................. Uninstalling on Linux .............................................................................................................................................................................................................. Known Windows Issues .. Installing Multiple Servers .................................................................................................................................................................................................................................................................................................................................................................................................................................. Solaris ................................................................................................................................. Installing on POSIX Platforms ......... Utility Scripts .................................................................................................................................. FreeBSD ....................................................................................... Running Firebird as a service with a special user name ........................................ Installing on Linux ....................................................................................... Other POSIX Platforms .............................................. Supporting legacy applications and drivers ......................................................................................................................................................................................Firebird 2 Migration & Installation Customising Your Installation ................... Uninstalling on MacOSX ..................................................................................................................................................

there will be situations where the Firebird engine. etc. This loophole has been closed.1.1.5: IMPORTANT A long-standing.2. instead of c:\Program Files\Firebird\Firebird_2_1 .0. it is available everywhere in the scope for which the variable was defined.2.1. components). You no longer need to disable it if you need to run multiple instances of Firebird simultaneously. in addition to the v. legacy loophole in the handling of DPB parameters enabled ordinary users to make connection settings that could lead to database corruptions or give them access to SYSDBA-only operations. Details are in Chapter 3 of the V. Yemanov Please study this chapter before attempting to install any servers.0 issues that you have previously taken care of. will not work as expected. Changes to Note in V. database tools and connectivity layers (drivers. there are a few more issues that need to be attended to in migrating to v.1. in Changes to the Firebird API and ODS.2. It is intended as a set of alerts to those who are migrating Firebird 1.2.1 Metadata Need to be Upgraded If your databases contain text BLOBs storing non-ASCII data then the backup/restore cycle is not enough to upgrade them to ODS 11. Unless you are very clear about the effects of having a wrong value in this variable.2 Release Notes. If the Windows installer program finds a value for %FIREBIRD% it will make that path the default location that it offers.0.conf is now deprecated.x installation.0 or 1. If you leave it defined to point to the root directory of a v.Chapter 1 Known Compatibility Issues D. If it exists..2. 1 .1 installation. Important For those who have already done the migration to v. After doing so. The FIREBIRD variable is NOT removed by scripted uninstalls and it is not updated by the installer scripts. Running Multiple Instances The configuration parameter CreateInternalWindow in firebird. you should also check that the old value is no longer visible in the workspace where you are installing Firebird--use the SET FIREBIRD command in a Windows shell or printenv FIREBIRD in a POSIX shell.2.1.0 and higher. a change that could affect several existing applications.5 databases to Firebird 2. installers. The FIREBIRD Variable FIREBIRD is an optional environment variable that provides a system-level pointer to the root directory of the Firebird installation.2. Please pay attention to the files in the /misc/upgrade/metadata directory of your Firebird 2.5.1. batch files.2 and V. command-line tools. cron scripts. Change to API DPB Parameters in V. you should remove or update it before you begin installing Firebird 2.

2.0 server.1.gdb (from v. The security database is renamed to security2. will be rejected by the remote interface if a correct login is not supplied.1) On Windows.0) using the old server's version of gbak and then restore it using the Firebird 2. you should create a gbak backup of your old security. Also read the file security_database. the Unix user name is used to validate access to database files. the default authentication mode is “Mixed”. • For backing up the security database.txt in the upgrade directory beneath the root directory of your installation. Before you begin the necessary alterations to commission an existing security database on the Firebird 2.5) or isc4. it also isolates the mechanisms of authentication from the implementation. Trusted Authentication on Windows (V. You can employ the se[rvice] hostname:service_mgr switch when invoking the gbak utility for this purpose. be sure to upgrade the security database using the provided script in order to keep your existing user logins. Warning A simple 'cp security. 2 .0 gbak. the Services API is now the only route.fdb If you upgrade an existing installation. On POSIX.fdb' will make it impossible to attach to the firebird server ! For more details see the notes in the chapter on security in the accompanying Release Notes. • Embedded access without login/password works fine. • User accounts can now be configured only by using the Services API or the gsec utility. Important You must make sure that you restore the security database to have a page size of at least 4 Kb.Known Compatibility Issues Security in Firebird 2 (All Platforms) Be aware of the following changes that introduce incompatibilities with how your existing applications interface with Firebird's security: Direct connections to the security database are no longer allowed Apart from the enhancement this offers to server security. On Windows. Remote attachments to the server without a login and password are now prohibited • For attachments to Superserver.1.fdb will not work with a smaller page size. authentication is bypassed. Non-SYSDBA users no longer can see other users' accounts in the security database A non-privileged user can retrieve or modify only its own account and it can change its own password.fdb security2. The new security2.fdb (from v. which allows operating system users with Local Administrator or Domain Administrator group privileges to attach to databases with “blank” Firebird user name and password. even root trying to connect locally without “localhost:” in the database file string.

1. the operation in question is executed once and the table triggers will operate on the outcome of the view's triggers if the view's triggers do not define any DML request on the underlying table then no DML operation will take place in that table Important Some existing code may depend on the assumption that requesting a DML operation on an updatable view with triggers defined would cause the said operation to occur automatically. this “feature” might have been used as a quick way to write records to a log table en route to the “real” update. conf. Now. For example. The result was that. if the view's triggers define a DML operation on the underlying table. it becomes effectively like a non-updatable view that has triggers to make it updatable. it will be necessary to adjust your view trigger code in order to make the update happen at all. SQL Migration Issues DDL Views made updatable via triggers no longer perform direct table operations In former versions. in that a DML request has to be defined on the view to make the operation on the underlying table happen. if you followed the official documentation and used triggers to perform a table update (inserted to. updated or deleted from the underlying table). 3 . if you define triggers for a naturally updatable view. the change the parameter Authentication in firebird. particularly if blobs were involved. a naturally updatable view with triggers passed the DML operation to the underlying table and executed the triggers as well.Known Compatibility Issues Warning If you consider this insecure for your network setup. viz. This situation caused performance problems or exceptions. Now. as it does for an updatable view with no triggers. 2. the operation was done twice: once executing the view's trigger code and again executing the table's trigger code.

extentions/README.2. views. Using the example above: CHECK (DEPTNO IN (10. 20. i.. Use of an alias makes it invalid to use the table identifier to qualify a column. Brinkman In summary.5 and earlier versions: 4 . 30) AND DEPTNO IS NOT NULL) DML Changed Ambiguity Rules in SQL A. Please consult the v. When an alias is present for a table.2. must be used to qualify columns. This query was allowed in FB1. In Firebird 2. 2. Mixed usage of the NONE and other character sets is not recommended as it can lead to to unexpected runtime errors. CHECK constraints were not SQL standard-compliant in regard to the handling of NULL. such identifiers can be redefined using the same words. Columns can now be used without qualifiers in a higher scope level. or no alias is used. In a Dialect 1 database there is no way to retain them: they must be redefined with new. There is a metadata script to enable you to upgrade the stored sources of triggers. the changes are: 1. You must ensure that your DSQL statements and procedure/trigger sources do not contain those keywords as identifiers. The full list is available in a chapter of its own in the accompanying Release Notes and also in Firebird's CVS tree in /doc/sql. Examples a) 1. When an alias is present it must be used or no alias at all must be used. that alias. For example.1 release notes for instructions. and not the table identifier. CHECK Constraint Change Formerly. in UTF8. as long as the identifiers are enclosed in double-quotes. This affects not just user data but also the metadata stored in the system tables.1) Malformed UTF8 strings and text blobs are no longer allowed.keywords. it is essential to ensure that DDL statements are transliterated into the connection character set. stored procedures. etc. (V. CHECK (DEPTNO IN (10.Known Compatibility Issues New Reserved Words (Keywords) A number of new reserved keywords are introduced. The current scope level is checked first and ambiguous field checking is done at scope level. constraints.0. Important In order to have the metadata correctly stored in the database. Note In a Dialect 3 database. you must do so explicitly by extending the constraint. 20. 30)) should allow NULL in the DEPTNO column but it did not. if you need to make NULL invalid in a CHECK constraint. legal words.e.

5 and earlier: SELECT RDB$RELATIONS.FieldID = TableA. Use this (preferred): SELECT R.FieldID) Note Although it is possible in Firebird to provide an alias in an update statement. This would fail in Firebird 1. but in Firebird 2.RDB$RELATION_NAME. b) 1.0: SELECT (SELECT RDB$RELATION_NAME FROM RDB$DATABASE) 5 .FieldB) FROM TableA A WHERE A.RDB $RELATION_NAME” could not be found. but is possible in Firebird 2.0 it will correctly return 90 rows.RDB$RELATION_NAME FROM RDB$RELATIONS R Now. The next statement will now use the appropriate FieldID correctly from the subquery and from the updating table: UPDATE TableA SET FieldA = (SELECT SUM(A. many other database vendors do not support it.RDB$RELATION_NAME) If RDB$RELATIONS contained 90 rows. the engine will correctly report an error that the field “RDB$RELATIONS. R2. This example ran incorrectly in Firebird 1. it would return 90 * 90 = 8100 rows.Known Compatibility Issues SELECT RDB$RELATIONS.RDB$RELATION_NAME FROM RDB$RELATIONS JOIN RDB$RELATIONS R2 ON (R2.RDB$RELATION_NAME = RDB$RELATIONS.5. a) 3.RDB$RELATION_NAME FROM RDB$RELATIONS R or this statement: SELECT RDB$RELATION_NAME FROM RDB$RELATIONS R a) 2. These SQL statement syntaxes provide better interchangeability with other SQL database products.

2. Table T is not referenced in plan. A) . it will be necessary to inspect your procedure and trigger sources and adjust the plans to make them semantically correct..g. B. B = y. even though it was tolerated in InterBase and previous Firebird versions. Thus. Ambiguity checking in subqueries This would run on Firebird 1.RDB$RELATION_NAME)) FROM RDB$DATABASE Important (V. but will report it in Firebird 2. or UPDATE T SET A = x.1) A temporary “relaxation” of the restriction against mixing table identifiers and aliases was made possible in V.Known Compatibility Issues FROM RDB$RELATIONS b) 2.5 without reporting an ambiguity. a statement like INSERT INTO T(A.0: SELECT (SELECT FIRST 1 RDB$RELATION_NAME FROM RDB$RELATIONS R1 JOIN RDB$RELATIONS R2 ON (R2. by the introduction of the configuration parameter RelaxedAliasChecking. A = z will be rejected in Firebird 2. It will be deprecated in future so there is no good reason for anyone to write non-compliant statements in new code! Multiple Hits to Same Column Now Illegal It is no longer allowed to make multiple “hits” on the same column in an INSERT or UPDATE statement. Query Plans Stricter validation of user-specified plans User-specified plans are validated more strictly than they were formerly.RDB$RELATION_NAME = R1. It is not the default behaviour and its sole purpose is to allow a window for people to bring legacy code into line.n.1.. 6 .2. If you encounter an exception related to plans. e.

specify CURRENT_TIMESTAMP(0). referring to "current of <cursor>" outside the scope of the cursor loop was accepted by the PSQL parser. while it truncated subseconds back to seconds in former versions. PSQL Restrictions on assignment to context variables in triggers • Assignments to the OLD context variables are now prohibited for every kind of trigger. • Assignments to NEW context variables in AFTER-triggers are also prohibited. it will be rejected in the procedure or trigger definition.Known Compatibility Issues Important Such errors could also show up during the restore process when you are migrating databases to the new version. Some previous versions would accept plans with missing references. syntax. Thus: • for ascending sorts NULLs are placed at the beginning of the result set • for descending sorts NULLs are placed at the end of the result set Important In former versions. 7 . It will be necessary to correct these conditions in original database before you attempt to perform a backup/restore cycle.5 and earlier. If you need to continue receiving the truncated value. Tip If you get an unexpected error Cannot update a read-only column then violation of one of these restrictions will be the source of the exception.. Reference to "current of <cursor>" outside scope of loop In Firebird 1. you will now need to specify the required accuracy explicitly. when the output list uses SELECT * FROM . Now. If you have client code or PSQL definitions that rely on the legacy NULLs placement.e. NULLs were always at the end. CURRENT_TIMESTAMP now returns milliseconds by default The context variable CURRENT_TIMESTAMP now returns milliseconds by default. the column list will be expanded and taken into account when determining which column the number refers to. but it was a bug. ORDER BY <ordinal-number> now causes SELECT * expansion When columns are referred to by the “ordinal number” (degree) in an ORDER BY clause. it will be necessary to use the NULLS LAST option in your ORDER BY clauses for ascending sorts. Plan must refer to all tables in query Using a plan without a reference to all tables in query is now illegal and will cause an exception.. NULLS are now “lowest” for sorts NULL is now treated as the lowest possible value for ordering purposes and sets ordered on nullable criteria are sorted accordingly. allowing the likelihood of run-time occurring as a result. i.

you have two alternatives: • Specify the full syntax gbak -REPLACE_DATABASE.0. Firebird version 2 efficiently cleans up dead threads straight away. The -R shortcut now represents the R[ECREATE_DATABASE] switch and the OVERWRITE keyword must be present in either the full or the abbreviated form. Configuration Parameters Configuration parameter DeadThreadsCollection is deprecated The parameter DeadThreadsCollection for Superserver in firebird. have produced incorrect results for the logical existence predicates ALL and NOT IN for many years. There is a new shortcut for the REPLACE_DATABASE switch: gbak -REP OR • Use the new command -R[ECREATE_DATABASE] OVERWRITE. T2. Tip This change makes it possible to specify queries like SELECT * FROM TAB ORDER BY 5.conf is deprecated and will be ignored if set. InterBase.COL FROM T1. now. Warning If you use the full syntax. Performance The following changes should be noted as possible sources of performance loss: Existence Predicates NOT IN and ALL May Be Slow Firebird and. T2 ORDER BY 2 sorts on the second column of table T1. That problem has been corrected in Firebird 2.COL. Now the -R switch no longer restores a database by overwriting an existing one. gbak -R was formerly a shortcut for “-REPLACE_DATABASE”. while the previous versions sorted on T2. Command-line Tools Change to gbak -R Semantics An important change has been done to prevent accidental database overwrites as the result of users mistakenly treating “-R” as an abbreviation for “restore”. but instead reports an error. you are expected to know what this restore mode actually means and have some recovery strategy available if the backup subsequently turns out to be unrestorable. before that. If you actually want the former behaviour. but the change means that 8 .*. SELECT T1.Known Compatibility Issues This means that.

In the meantime. Superserver garbage collection changes Formerly.2. viz. it was: typedef void (* isc_callback) (). the index will be ignored. a workaround is to use CAST or specify the explicit data type prefix. It means that some queries may be slower to start to return data if the volume of old record versions in the affected tables is especially high. will be particularly prone to this problem. Resolution of this issue is expected in the first point release. ODS10 and lower databases. The indexed scan is for this predicate is now disallowed since a numeric can be converted to a string in different ways. By contrast.1) Some date/time expressions in Dialect 1 can not benefit from available indices either. curtailing the growth of version chains under high load. DATE_FIELD > TIMESTAMP 'NOW' + 1 . Note NOT EXISTS is approximately equivalent to NOT IN and will allow Firebird to use indexes. index scanning is allowed because the conversion is deterministic.Known Compatibility Issues indexes on the inner tables cannot be used and performance may be slow compared to the same query's performance in V. Events callback routine declaration corrected The new prototype for isc_callback reflects the actual callback signature. The new default behaviour generally guarantees better overall performance as the garbage collection is performed online. Prior versions that appeared to “work” in these cases could return wrong results. DATE_ FIELD > 'NOW' + 1. having ineffective garbage collection on indices.. “Inner tables” are the tables used in the subquery argument inside an ALL or NOT IN expression.g.1. e.conf allows the former behaviour to be reinstated if you have databases exhibiting this problem. Use fb_interpret() instead. The GCPolicy parameter in firebird. for the reverse case.5. INTEGER_FIELD = STRING_ARGUMENT. Indexes Involving Data Type Coercion May Be Ignored (V. Formerly. However..2. Classic performs “cooperative” GC. (V. 9 . Firebird API Note the following changes affecting the API isc_interprete is deprecated isc_interprete() is deprecated as dangerous. Superserver performed only background garbage collection. where multiple connections share the performance hit of GC. Superserver's default behaviour for GC is now to combine cooperative and background modes. A common example would be a predicate like STRING_FIELD = INTEGER_ARGUMENT.1) In cases where an indexed field and an argument have different data types and the implicit conversion cannot be performed consistently.

g. short. configuring and connecting to Windows servers. Client Impersonation No Longer Works WNET (a. it was required (as Allow service to interact with desktop) to run the local IPC protocol. With regard to the local protocol. 10 . For more information. ISC_LONG *. const ISC_SCHAR*. const ISC_UCHAR*).5.1. However.0. ISC_EVENT_CALLBACK. please ensure your server and client binaries have exactly the same version numbers.Known Compatibility Issues ISC_STATUS isc_que_events( ISC_STATUS *. isc_callback. It may cause a compile-time incompatibility.2. If you need to use the local protocol. void *). void* instead of const char* as the last parameter). it is no longer necessary and the server itself does not need this option.k. For v. In the Firebird 2. short. NetBEUI. char *.exe to enable an interactive mode for LocalSystem services. refer to the chapter about new features in the accompanying Release Notes. isc_db_handle *. ISC_LONG*. be aware of the following issues: Windows Local Connection Protocol with XNet The transport internals for the local protocol have been reimplemented (XNET instead of IPServer). ISC_USHORT. Interactive Option Added to instsvc. Yemanov The optional switch -i[nteractive] has been implemented in instsvc. some custom UDFs may use the Win32 messaging facilities and this option allows them to work as expected. In v.exe D. as older event handling programs cannot be compiled if they use a bit different signature for a callback routine (e.0 API it is: typedef void (*ISC_EVENT_CALLBACK) (void*. ISC_STATUS isc_que_events( ISC_STATUS*. as it used a windows message to connect the server. Named Pipes) protocol no longer performs client impersonation. Windows-Specific Issues For installing. the new client library is therefore incompatible with older servers and older client libraries are incompatible with the Firebird 2 servers. isc_db_handle*..a. void*).

instsvc in the doc directory of your Firebird installation. For detailed usage instructions. It does not apply to Windows systems that do not have the ability to run services (Win9x. 11 . WinME).exe is a command-line utility for installing and uninstalling the Firebird service. refer to the document README.Known Compatibility Issues Note instsvc.

On 32-bit systems. Your ultimate choice of which server model to deploy to user sites will be determined by comparing the performance of one with another in your test lab. Superserver is limited to using a maximum of 2 GB of RAM. Superserver's shared page cache. can use up to 2 GB of RAM. It starts (or assigns) one or more threads for each successful connection request. You don't have to do anything to a database in order to make it work under a different server model. your choice is most likely to be whether to use Classic or Superserver.exe on Windows that listens for connection requests from network clients. Unlike Classic. 12 . Classic can be a good choice if the host server has multiple CPUs and plenty of RAM. Like the Classic server stub it also listens for connection requests. the [x]inetd daemon performs this listening role. fbserver on POSIX. Known Compatibility Issues before you set out to install Firebird 2. the embedded server library is named fbembed. On POSIX systems. • In discussions. Its name is libfbembed. a local client and a server are rolled together into one shared object library. Full Servers At install time. there's nothing in it. the choice may be more important. It is a temporary file name that must be changed in order to be used. For development.Chapter 2 INSTALLATION NOTES Please read the previous chapter. properly configured. Superserver for Windows does not “play nice” with multiple CPUs on most rigs and has to be set for affinity with just one CPU.exe on Windows.so and its manner of resource usage is like Classic. The stub process or daemon creates a separate fb_inet_server process for each successful connection. Each process has its own private page cache and. the embedded library is distributed with the Classic kits. In this model. can be beneficial for performance where many users are working concurrently.dll. .On Windows. Superserver is a threaded application. on 32-bit systems.On POSIX.0. . For testing and deployment. • Superserver is a process named fbserver. Classic and Superserver are often referred to as “full servers” because Firebird also supports an embedded server on both Windows and POSIX. The Windows embedded server is an instance of Superserver. On the other hand. Briefly: • Classic runs a stub process named fb_inet_server. The differences are in the ways the server module uses machine and network resources. Database Compatibility Among Models There are no issues that make databases created by one server model incompatible with another server model. Superserver and Embedded are all the same Firebird engine. intended for “stand-alone” deployments. All of these connection threads share a common page cache. Choosing a Server Model Classic.

A more detailed paper on the subject can be found in the IBPhoenix documentation archives.INSTALLATION NOTES Note There is more discussion about the Classic/Superserver decision in the Quick Start Guide. It is intended to be used by one and only one system user exclusively. which makes it impossible to use in many integrated application development environments. Embedded Treat the embedded server as a deployment option. 13 .

Cases when you might wish to consider installing Firebird manually from a zip file include: • You need to run multiple versions of Firebird concurrently • You wish to run the Firebird service as a special user • You need to deploy a specific configuration for your application 14 . document them and to reduce the “weight” of installations. V. This means you have some decisions to make before installing Firebird 2.2.2. The setup instructions for deployment of applications using Embedded are discussed towards the end of this chapter. efforts have been made to improve the options. it is recommended that you regard this model as one you can design for. Choosing an Installation Method Under almost all circumstances you should use the binary installer to install Firebird on Windows.1.2 Installation Improvements The Firebird 2. It does not run on its own. For the V.1 installations for these platform versions.1. Microsoft introduced new rules for distributing the runtimes associated with this compiler on XP and Vista platforms. Please refer to the later section entitled Microsoft Runtime Libraries.0 and 2. If you are new to Firebird.Chapter 3 Installing on Windows Please read the previous chapters before you set out to install Firebird 2. This introduced much more complexity and bloat into Firebird V.x.2.1.1. Installation Choices On Windows. particularly for Windows Embedded deployments. Classic and Embedded Server. using one of the full server models for initial acquaintance and development.1. you have three server models to choose from: Superserver. Note The Embedded Server model is intended for conditions where you want to deploy the server. a database (or databases) and your own application together for use on on a single computer with only one user. It covers all common usage cases and is typically 'click-through' by accepting the default values.x or 2. If you are new to Firebird you should certainly use the binary installer until you are familiar with a standard Firebird server installation.2 release.1.1 series are built using the Microsoft MSVC8 compiler.0.

0. You can restore it later as security2. some platform rules have become progressively complicated.0 you should use gbak to back up your old security database.dll. It is named security.fdb. even if you have been cheerfully running v. or hide it in another directory.fdb for Firebird 1.1.Go to your System directory and make backup copies of fbclient.Installing on Windows READ THIS FIRST! Important Firebird 2.fb103” or something similarly informative.fb15” or “gds32. set up your fall-back position before you begin: . . You might want to name the backup “gds32. you are on your own! 15 .dll and/or gds32.5 or isc4. It is strongly recommended that you study this section before you begin.x support the full range of Windows server platforms from Windows 2000 onward. At install time. 98 or ME. However this detection is not foolproof. although you might get Firebird 2.0 installation.x and 2. .Heed all the warnings and notes about incompatibilities and changes required. Do this before you uninstall the old version. • Make sure you are logged in as Administrator • Check to make sure that there is no FIREBIRD environment variable defined that is visible to Administrator-level users or to the LocalSystem user—see the section called “The FIREBIRD Variable” at the start of the previous chapter.0. using the directions in the chapter entitled “Security” in the Firebird 2.Use the existing version of gbak to back up your database files in transportable format. For a non-installer install. What worked on W2K might not work on later Windows platforms.gdb for a Firebird 1. they are no longer supported platforms for Firebird servers.5 for years! And note.x to install and run on Windows 95. • If you already have an earlier version of Firebird or InterBase® on your server and you think you might want to go back to it. the installer will try to detect if an existing version of Firebird or InterBase is installed and/ or running. Don't start experimenting with new features on your active production databases! • STOP ANY FIREBIRD OR INTERBASE SERVER THAT IS RUNNING.If migrating from a Firebird version earlier than version 2.dll.x Release Notes.dll if you have applications that rely on finding those libraries there. .1. Over the past decade.

conf firebird. The uninstaller will usually stop an existing server as part of the uninstallation process.2. 2. you should review the release notes for Firebird 1.2. certain configuration files in the installation directory will be preserved if you run the installer. if necessary.conf.x. default database will be installed. Ensure that you read the relevant chapter in each release notes volume and. There you will find details of the correlation between settings in ibconfig and firebird.1 it is recommended that you uninstall a previous version of Firebird or InterBase.If firebird. If this document is not in the documentation directory after installation.conf exists the installer will generate a firebird. .the firebird. If it doesn't exist an empty.conf firebird.The default Aliases. you understand how your network works you understand why a client/server system needs both a server and clients 16 .Installing on Windows Important A new installation of Firebird will not work correctly if an old version is still running. use a difference tool to merge existing settings into the new firebird.log file is generated automatically by the server when required. so if it already exists it will be left as it is. The uninstaller for all versions of Firebird will preserve certain configuration files.conf is just a place holder file. • Before installing Firebird 2.log security2.2.5. These files are: aliases. . if you do have problems later this is something to go back and check.If the security2.1.conf. Such parameters are removed eventually. Certain parameters are included from time to time. However. An empty log file is not created at installation time. v. See below for more details.default file with the default values and leave the existing file untouched.0.x or InterBase. etc. to enable legacy applications to continue “working around” legacy bugs for a limited time.fdb . • It is assumed that: 1.0. If it doesn't exist it will be generated. If you have special settings in your existing firebird. • When reinstalling Firebird 2. v. . Note If you are upgrading from Firebird 1.1. for Firebird 1. you can read or download it from the Release Notes section of the Firebird Documentation Index. Important Each release (v.fdb database exists it will be used.conf.conf to work out what can be copied directly and what parameters require new syntax.conf (ibconfig.conf. might change how an older parameter works. potentially. if it exists on your system.conf and.5.0) there may be some values that you want to transfer to equivalent parameters in the new firebird. so you probably need not worry about this if you run an uninstall. Study the notes about firebird.) adds new parameters to firebird.

The issue is described in more detail in Other Win32 Issues at the end of the Windows installation notes. The runtimes were almost always present in the system directory of established host servers and it was relatively rare during the heyday of WinXP and Server2003 for an installation of an older Firebird version not to run "straight out of the box". rather than exceptions that the Firebird binaries themselves could have detected or handled. For Firebird 2. people have a habit of overlooking the fact that Windows servers and clients always need the MS runtimes.1 will be C:\Program Files\Firebird\Firebird_2_1.dll) will work without access to both the C and the C+ + runtime libraries pertaining to the built version of the binary. Superclassic or Embedded) nor client (fbclient. However. each time a new release appears. even if they were found for loading the client library. Classic.gdb" extension that used to be the Borland convention for suffixing InterBase database file names. Microsoft C/C++ Runtime Libraries The problems associated with installing different versions of Microsoft system libraries are so notorious that it has acquired the name 'DLL Hell'.fdb" to avoid possible conflicts with "System Restore" feature of these Windows versions. In reality. Windows cannot load the binary. And as each new generation of Microsoft operating systems is released the policy for dealing with this issue changes. If the appropriate runtime is missing. A "User name or password is not defined" or "Character set X is not defined" error during the connection start-up usually means the server could not load the INTL library. too. 17 . almost every application installed on Windows needs at least the C runtime and many need also the C ++ runtime. What Happens if the Runtimes Are Missing? Both Firebird servers and Firebird clients depend on calls to the C/C++ runtimes. Naming databases on Windows Note that the recommended extension for database files on Windows ME and XP is ". The main source of problems is that. Sometime this can lead to even more hell. Some data access layers that load the Firebird client library dynamically might transform failure to load the binary into feedback such as "Cannot connect to database". • Provided you do not have a FIREBIRD environment variable defined. No Firebird server (be it Superserver. the default root location of Firebird 2. 4. because the INTL library needs them.0 it will be C:\Program Files\Firebird\Firebird_2_0.Installing on Windows 3. Most of the errors you will see in the logs (firebird and system) will be operating system ones. genuine Firebird exceptions due to "losing" the runtimes can still occur. Failure to address this issue on these platforms will give rise to the known problem of delay on first connection to a database whose primary file and/ or secondary files are named using the ". wrongly implying that there is something wrong with the database. since that precedes anything else. you have read the accompanying Release Notes—or at least realise that you need to read them if something seems to have gone wrong you know to go to the Firebird lists index to find a suitable support list if you encounter a problem. It is most likely to happen during the attachment to the security database.

CRT.dll. you need(ed) to download and install the . showed signs of tightened rules for installing DLLs. However.exe utility.0. Server2003 or MS Vista. as well as the DLLs in Firebird's \intl folder. with certain platform exceptions. the required runtimes are those distributed in the vcredist_32/64 pack. msvcp80. the preferred way to do this was to install the vcredist_32 or vcredist_64 Microsoft installer (.manifest). which is used for compiling the Firebird 2. not those that might have been latterly installed as part of a service pack.2.1.manifest—in the same folder as the engine executable or client DLL. respectively.msi) package. Unfortunately.2 onward.0. ATTENTION! Firebird binaries are built against the original version of Visual C++. it has been reported that an "operating system directive" exception occurred and investigation of the system log indicated that "registering" the DLLs was required. Until V. have been taught to search for the private assembly—the two runtime DLLs and the manifest file Microsoft. which has been in release and maintenance since November 2006.x For the Firebird 2. as appropriate for the architecture of your host server. it becomes possible to isolate the runtimes for your Firebird server or client installation in a private assembly.msi Installer software and then install the MSVC8 redistributable pack. it simply writes the two DLLs to the system directory and registers them.1. refer to the special topic by Vlad Khorsun.dll and the manifest (Microsoft. For Windows 2000 and for WinXP and Server2003 prior to Service Pack 1. 18 .x series. The corresponding distributable runtimes are msvcr80. For Windows 2000.Installing on Windows Runtimes for Firebird 2.1. some of the earlier documentation applicable to Firebird 2.VC80. Because of this. it is necessary to install the runtimes correctly as an assembly.5. and possibly also Win2000. It is suggested that you explore this route only if you encounter the operating system directive exception problem on Windows 2000 and see that advice when you follow it up in the system log. Now. The new rules were synchronised with the design-time assemblies of the Microsoft Visual Studio 8 C++ compiler. from Firebird 2. Managing MSVC8 Runtime Assemblies near the end of this chapter.dll. Runtimes for Firebird 2. on a Win2K system with SP4 and all subsequent updates. The result of installing the MSVC8 redistributable is that a shared assembly is installed on WinXP.VC80.0 erroneously cited the names of the older runtimes used by Firebird 1.CRT.dll and msvcp71. from the Microsoft support site. It fixed the problem. The server engine and the client. successive service packs for WinXP/Server2003.dll. For a detailed discussion of this change.1.1 series.dll and msvcp80. The minimal runtime consists of three files: msvcr80. using the regsvr32.x As Microsoft Vista approached. However. the Microsoft C and C++ runtimes are msvcr71. Tip for Windows 2000 It has been assumed that simply copying the DLLs to the system directory is all that is needed. Private Assembly Installing the runtime assembly from the Microsoft redistributable is the easiest and thus the preferred way to get them on board.

dll and msvcr80. at least at the Windows service patch levels current in the first quarter 2009. However. you can copy them from the \bin folder of the Firebird installation. A help screen will be displayed that shows the version.Installing on Windows (msvcrt.dll and msvcp71. Other Pre-installation Issues Microsoft Installer Version The binary installer will determine the host operating system and try to install system libraries appropriately for that O/S.1.2. The Firebird installer executable for v.x actually attempts to install the runtimes on any Windows platform.dll there does work.71. on 64-bit versions of WinXP or Server2003 with the later service packs.0.dll and the MSVC80 manifest for V. 19 . As already alluded to above.dll). Installing under 64-bit versions of Windows The 64-bit binary installer includes a 32-bit client kit so that everything will work 'out of the box'.2.0.. including Vista.dll runtimes are similar to those for older versions (for both the runtimes and the Firebird components): it is enough to copy them to the Windows system directory on Win2000. possibly. Tip If you haven't studied the previous section and are confused.dll and the C++ runtime msvcp60. run msiexec. Microsoft Vista is not so tolerant about post-installing DLLs in its system directory but it appears that copying msvcr71. This should ensure that you have the appropriate installer available before executing the installer for your selected Firebird kit or for installing the assembly yourself when installing Firebird from a zip kit. it is advisable to check after a reboot whether those runtimes are actually there.exe from a console prompt. On the other hand.0.x. early versions of WinXP and Windows 2003 that have not used Windows Update will not have the correct version of the Windows Installer required to install the side-by-side assemblies of the run-time libraries.x) can be copied directly from the Firebird \bin\ directory into the Windows or WINNT \system32\ directory. so don't forget to install the 32-bit MS C runtime msi. then do so now. WinXP and Server2003 servers and clients. Firebird 2. If not. Older Windows Platforms If the host O/S is pre-WinXP runtime libraries (msvcp80. If it is earlier than v. on Vista and.2.3.dll for V. The deployment rules for the . Checking the Windows Installer Version To check the version of the Windows installer installed on your WinXP or later host. or msvcp71. along with the 32-bit client library if you need to use 32-bit applications on the server.dll and msvcr71. the zip kits are platform specific.x will not work if those (or lower) runtimes are the only ones available.0 you must update. In most cases there will be no problems. The only recommended solution is to run Windows Update to bring your XP or Server2003 installation up to the level of Service Pack 2 or higher.

Applications would then be able to enumerate the Registry entries to determine which Server instance they wish to load. Furthermore. Note that under these circumstances the FIREBIRD environment variable must NOT be defined at the system level AT ALL.dll. So. It will be known as "DefaultInstance" and will store the path to the root directory of the default installation. Please refer to the Customising Your Installation section at the end of this chapter. 20 . For those whose local server applications still need to find the client library in the system directory. from Firebird 1. Future versions of Firebird may see other entries under Instances when the installation utilities can be taught to isolate and configure instances reliably. the client library for local use on the server has resided in the \bin directory along with all the other binaries. Note You don't need to commit yourself one way or the other during the initial installation.Installing on Windows Simultaneous installation of 32-bit and 64-bit versions of Firebird is possible.1-compliant applications should use this key if they need to read a Registry key to locate the correct version of Firebird that they wish to use. Your Windows kits come with tools that can be used to customise such things later. Cleaning up release candidate installs It should be noted that the installer removes fbclient.dll is not the “native” name of the client library. The installer also removes any deprecated HKLM\Software\Firebird* Registry keys.dll on the Server Since Firebird 1.dll. It is now called fbclient. as we want to allow multiple engines to run simultaneously we would be creating our own DLL hell if we continued to encourage the practice of using the system directory for the client library.dll. gds32.dll from the <system> directory if the file is found there. if need be. but at least one must be installed and configured manually.5. Registry Key A Registry key is added and all Firebird 2. it would make little sense if we continued to store the Firebird client library in the system directory by default. Installation of fbclient. Considering the problems that Microsoft has had with DLL hell. Those who don't care about particular installations can always use the default instance to locate the fbclient. the installer provides the option (unchecked) to copy the client to the system directory and also to rename it to gds32.5 on. The new key is: HKEY_LOCAL_MACHINE\SOFTWARE\Firebird Project\Firebird Server\Instances Firebird will guarantee that one entry under this key always exists.

dll and msvcr80.Installing on Windows Using the Firebird Installer Important Don't overlook the need to have the Microsoft® Visual C and Visual C++ runtimes (msvcr80.x: msvcp80. Next. MS Visual C/C++ Runtime Libraries To remind you once again. This is really the easy part: the actual install. or you plan to run the server as an application in another Win32 environment.dll and msvcp80. Here you can also opt not to have the installer create Startup Menu icons by checking off the option.dll. respectively) present in the appropriate directory of all Windows servers and clients. you should check first whether later versions of these libraries are already present.dll • for Firebird 2. The path you type in doesn't have to exist: the installer will prompt you and create it if it doesn't exist. If you decide not to use the default root location. Don't overwrite later versions. including Windows Embedded installations.1. If you are installing on Windows 9x or WinMe.1 the installer should be showing “c:\Program Files\Firebird\ Firebird_2_1” by default.0.• for Firebird 2. keep the icons option checked on. Just run the executable and respond to the dialogs. After you have answered a few dialogs about licensing and installation notes. For your convenience. you should see a screen where you choose the installation you want: 21 . browse to a location you have pre-created. the Visual C run-time libraries for Firebird 2 are as follows.dll and msvcr71. copies of these libraries should be present in the \bin directory of the Firebird install. However.x: msvcp71. Refer to the earlier notes in this section if these libraries are missing. or just type in the full path and let the installer find it. you should see one where you decide on the location of the Firebird root directory.dll Installation (Root) directory For Firebird 2.

check off “Server components”. optionally. For a client-only install. Note If you're installing a server. leaving “Client components” and. Leave “Server components” and “Developer and admin tools components” checked on. you should choose Superserver (preselected by the installer) or Classic (as seen in the image above).Installing on Windows Choose the installation you want and hit the "Next" button to carry on responding to dialogs. 22 . The next screen of interest enables you to set up how you want the server to run. There is also a drop-down for a custom installation which new users can safely ignore. “Developer and admin tools components” checked on.

. If it is there and is checked on. you must check it OFF. the Guardian option should not appear. you will be asked to choose whether to run Firebird as a service or as an application.0. choose service. Use Control Panel Applet (Superserver only) 23 . Firebird will start up whenever you boot the host machine. and your OS version supports services. With the manual option you can start the server on demand from the Services applet in the Settings/Control Panel/ Administration Tools selection. you can set the operating system to restart the service instead.. should it crash for any reason. Unless you have a compelling need to run the server as an application. Use the Guardian. If you chose the Classic server. For deployment of Superserver on Win9x. Guardian is a utility than can run "over the top" of Superserver and restart it. Manual or automatic? With the automatic option. Service or application? If you select to install Superserver or Classic. WinME and WinNT 4. using Guardian can avoid the situation where the server stops serving and nobody can find the DBA to restart it. The Guardian is otherwise more or less obsolete now since. which are unsupported platforms now for Firebird.Installing on Windows Choose the options you want. according to your choice of server model. on the supported Windows platforms.

which will not have an entry for the Firebird server if you installed from a zip kit (next section).conf or renames it to aliases. Reboot will be signalled if the installer was unable to update a DLL due to its being already loaded when the installer started up. If you can see this service in combination with the Firebird Classic service. make sure to check it OFF.confnnnn "nnnn" is the build number of the old installation.fbnnnn preserves firebird.fdb or renames it to security2. The Firebird uninstall routine (run from Add/Remove Programs in the Control Panel) preserves and renames the following key files: preserves security2. viz. whose executable name is fbguard.confnnnn preserves aliases. To prepare to uninstall Firebird. Firebird will be running and waiting for something to connect to it. you will see the name of the executable that the service is running. If you decide to inspect the property sheet for the service. you will find information about some tools and techniques at the end of this chapter. Assuming you installed it as a service. you will see an option to “Install Control Panel applet?”. you will press “Install” and the server will either silently start the server (if you requested it) or prompt you for permission to reboot. you can visit the Services applet in your Administration Tools area to inspect its status. it might be handy to keep this as it places an applet in the Control Panel from which you can stop and [re]start the server.conf or renames it to firebird. Uninstallation This note refers to uninstalling a Firebird server that you installed using the Windows Installer kit. What Now? By this point. 24 .exe if you installed Superserver • fb_inet_server. you will see another service there. the dialogs will stop.exe with the remove parameter to get rid of it (only the Guardian service). If it appears on the installer screen display. It hooks into the native Windows Add/Remove Programs database. That's all.log preserves firebird. Don't install the Control Panel applet on Vista! Installing this applet on Vista has the potential to break your system's control panel altogether.exe if you installed Classic If you elected to use the Guardian with Superserver.Installing on Windows If Superserver is being installed.exe. folks! If you want to perform some customisation of your Firebird server. No attempt is made to uninstall files that were not part of the original installation. if you elected to start the server. first shut down all connections to databases and then shut down the server. Unless your operating system is Vista. Eventually. you should stop the Guardian service and run the instsvc. • fbserver.

Ensure that these libraries are appropriately installed before you begin.exe install • optionally.exe: instsvc.exe to copy fbclient. $FIREBIRD refers to the directory where the v. you may need to run instclient.exe: instsvc.exe (Superserver) or fb_inet_server. 25 . Don't try to install and use it. the only difference is the additional switch for instsvc.exe (the parent process for Classic)—installed as a service.2.8 runtimes.dll will be deleted if the share count indicates that no other application is using them. The Registry keys that were created will be removed. the steps are as follows: • unzip the archive into a new directory • change the current directory to $FIREBIRD\bin (here and below.dll or a specially-generated clone as gds32. Installing Firebird from a zip kit The installation of FB 2. The Control Panel applet is not installed with Classic—deliberately.Installing on Windows Shared files such as fbclient.dll to the OS system directory Installing Classic Server from a zip kit To install the CS engine.1 is similiar in principle to previous versions but you need to pay attention to the preceding notes about the MS Visual C/C++ v. Superserver That taken care of.1 files are located) • run instreg.exe: instreg. The concept of “terminating” a service does not apply to the Classic model.dll and gds32. also run instsvc.exe install -classic Important Notice that this means that you may have only one architecture of the engine—either fbserver.exe install It causes the installation path of the directory above to be written into the registry (HKLM\Software\Firebird Project\Firebird Server\Instances\DefaultInstance) • if you want to register a service.

exe utility was conceived primarily so that the client library could be installed and removed from <SYS> while correctly maintaining the shared library count.exe. In this case you should just unzip the archive into a separate directory and run the server as an application: fbserver.e. The root directory of the embedded server is the one where the embedded library binary (fbembed.exe remove fbclient. since it is only a component of the embedded system that you will build around it. the one above \bin\.dll.dll) is located.exe -a It should treat its parent directory.exe remove" • run "instclient. Firebird Embedded for Windows comes only as a zip kit. Registry Any Firebird Registry entries are ignored.Installing on Windows Simplified setup If you don't need a registered service. just as the regular client library does.exe remove" • run "instsvc. you should take care to unpack the kit in the structure under which it was packed. The embedded server acts as a true local server for a single client accessing databases on a local machine.dll" • run "instclient. However. since many parts of an embedded setup rely on finding one another within that directory tree. To remove Firebird 2. usually renamed to fbclient.. then you may avoid running both instreg. i.exe remove gds32.1 without a Windows Uninstaller. Uninstallation Warning You should not delete the client libraries from <SYS> by hand as it has the potential to render the shared library count inaccurate. It has exactly the same features as the usual Superserver and its client part exports the standard Firebird API entrypoints.exe and instsvc.dll. 26 . proceed as follows: • stop the server • run "instreg. as the root directory in this case.dll" • delete installation directory Windows Embedded The embedded server is a fully functional server linked as a dynamic library that is distributed with the name fbembed. The instclient. It can also act as a remote gateway that redirects all network calls to other hosts.

Since both the server and the client run in the same address space.Installing on Windows Database Access Client access can be only via the local (XNET) protocol. Any user is able to attach to any database. regardless of whether they be embedded or full servers. security becomes just an agreement between the accessor and the accessed. The embedded server supports only the local connect to an absolute database file path without a server name. 27 . If you have skipped over the earlier notes concerning the MCVC8 runtime libraries. If another Firebird server already has a client attached to the database.1. Compatibility You may run any number of applications with the embedded server without any conflicts. Note SQL privileges are still checked and enforced. Do not try to connect to a database on any mapped location! The database MUST be on a local partition that is controlled by the machine that is hosting your embedded server and its surrounding application. You can extract copies of these libraries from the zip kit version of the full Firebird build if they are not already present on your system. NOT a TCP/IP local loopback connection string that includes the server name “localhost” or the IP address 127. An embedded server has the SuperServer architecture and hence exclusively locks any database it attaches to. be aware that you cannot access a single database from a number of servers simultaneously. This is intentional.dll and msvcr80.e. i. which can be easily compromised. Users that are assigned privileges in a Firebird database are not dependent on the existence of the user in the security database. The client program gets exclusive access to the database file after successful connect. Having a full Firebird or InterBase server running on the same machine is not a problem. However. Hence it is not required. either.0. it is recommended that you review them now.1. to make their user known to the database's access control list. Installing an Embedded Server Application MS Visual C/C++ Runtimes For v.2.0. the client program will be denied access.fdb) is not used in connecting to the embedded server.x the MS runtime libraries msvcp80. Applications may still validly pass a user name in the database connection attributes and should do so. This is intentional. Authentication and Security The security database (security2.dll must be available in the embedded library's path.

such as INTL support (fbintl. /intl or /udf. create subdirectories beneath the application root for them.dll to either fbclient. Note You will need firebird.dll c:\my_app\icudt30.exe c:\my_app\gds32.conf only if it is necessary to set some non-default configuration parameter for the embedded server. respectively.dll c:\my_app\ib_util. Start your application Now start your application and it will use the embedded server as a both a client library and a server and will be able to access local datasases via the XNET network emulation protocol.dll) in another directory.dll.conf c:\my_app\firebird.dll c:\my_app\icuin30.dll Suppose you want to place the Firebird files (excluding the renamed fbembed.dll c:\my_app\firebird. emulating the Firebird server ones.dll c:\my_app\intl\fbintl.conf (if necessary) to the same directory. Installation Structure Examples c:\my_app\app. Rename fbembed. e.dll or gds32. In that case. If external libraries are required for your application.dll c:\my_app\firebird.conf and set RootDirectory to the Firebird directory tree that is parent to the Firebird files.msg c:\my_app\intl\fbintl. you need to modify your firebird. Example c:\my_app\app.dll c:\my_app\icuin30.conf) or UDF libraries.dll and fbintl. You should also copy firebird.dll c:\my_app\icuuc30.conf c:\my_app\udf\fbudf.dll Rename fbembed.dll into the directory with your application exectable.dll. icudt30.dll c:\my_app\icudt30.dll.dll and icuuc30.conf d:\fb\firebird.Installing on Windows Application Root Just copy fbembed.msg and firebird.dll c:\my_app\icuuc30.dll c:\my_app\ib_util. according to which is required by your database connectivity software.g.exe c:\my_app\gds32. icuin30.msg d:\fb\intl\fbintl.dll 28 .

. It will take care of writing a Registry entry to inform the system where to look for components that applications might need and of locating them in the correct relative locations.dll'. don't forget those MSVC runtimes! Customising Your Installation A number of tools and tricks are available for certain kinds of customisation you might want to make in your installation. The texts for those messages live only in firebird.msg. 29 . a local copy of firebird. The symptom of a missing. it was assumed that just copying fbclient. The option to use the client-only install option in the binary installer kit might be the better approach to take if you are not too concerned about a private assembly.).conf: RootDirectory = d:\fb Client-only Installs In the past. The firebird. give it the legacy name 'gds32.dll In firebird. isql. it can also be set to write a "Borland-compatible" client dll and. where the presence of the C/C++ runtimes was normal and the location was standard. the client library does not contain any text for error messages output to the console by the Firebird command-line utilities distributed with the releases (gbak.conf d:\fb\udf\fbudf.msg is required. etc. It worked for some situations. If any of those utilities is to be used from a client.1 and higher and the more pervasive changes in the Microsoft platform rules. When the client application is using the correct version of fbclient.e. optionally." Other Libraries or Files Needed by Clients Client-only installations do not need any other components from the Firebird distribution.msg. However.Installing on Windows d:\fb\intl\fbintl. more care must be taken.dll and the runtimes to the system directory was enough to get a remote client set up to connect to Firebird. wrongly placed or outdated firebird.dll. i.msg File Each release of the client library contains the compiled message text corresponding to exception codes that its matching Firebird server returns to the client application via the Error Status array. Now.. the client does not need a local copy of firebird.msg file on a client that needs it is an error message of the kind "Cannot format message. Separate documentation is provided for most of these tools. with Firebird 2. However. in the form of text files in your installation's \doc\ folder.

on clients where the operating system still permits user DLLs to load from the system directory.1 makes it a little easier to run multiple servers simultaneously. InstClient. for configuring an alternative service port and accessing from applications.dll to the Windows System directory.x versions ship with a tool named 'instclient.dll client library from the system directory.x releases and is essential reading if you plan to have more than one server running. the file won't be available until after the installation.instsvc. If you want to make use of the secure login feature.exe' tool can also install the FBCLIENT. This clone gets patched on the fly so that its file version information begins with "6. Supporting legacy applications and drivers Traditionally. if required. prompting the executable to display all its valid ones.5.0". Installing Multiple Servers Firebird 2. create a “firebird service user” on the system with any name and password you like. Firebird 2.exe' that can install a clone of fbclient.DLL itself in the Windows system directory. It must have the privileges for a normal user. It doesn't matter which you use: both are invalid. More information is in the document named README.exe Tool This 'instclient. You can read the same document at this URL.exe: instclient i[nstall] [ -f[orce] ] library q[uery] library r[emove] library 30 . This will take care of tools or applications that need to load it from there.DLL file version and can not make sense of a number string such as "2. If you have a zip kit. txt available in the doc directory after installation. Running Firebird as a service with a special user name Firebird can be made more secure on a Windows system if it is run as a service with its own user name. The detailed description in Chapter 9 of the Firebird 1.x release notes. You can read more about this in the file install_windows_manually. The instclient. However the second and subsequent servers must be installed manually. to provide compatibility for old applications that check the GDS32.Installing on Windows Note also that most of these tools have skeleton help available simply by running the executable concerned help or -? arguments. you will find it in the /doc/ directory of the zipfile's root. still holds for the Fb 2. Usage of instclient. local applications that use InterBase or Firebird have expected to load the gds32.txt. or it can be found at this URL. If you don't have a zip kit available.exe utility should be located in the 'bin' directory of your Firebird installation and must be run from there in a command shell.3".

Special Topics In this section we have special topics that provide extra detail about new or changed features affecting your installation of Firebird on Windows. it could break another Firebird or InterBase® version already installed. this is not possible with an application being deployed with Firebird Embedded: it must be installed ready-to-run. Often. In that case.0 installed and the user must have administrative privileges. You may provide the -f[orce] option to override version checks. Installing Runtimes as a Shared Assembly To install the runtimes as a shared assembly. see the document README. Server2003 and Vista platform families.dll—must be distributed as shared or as private assemblies. Caution If you -f[orce] the installation. Use of the \system32 folder for assemblies is now prohibited on the XP.CRT.2 Onward Firebird 2. do not plan to install the runtimes as a shared assembly. Microsoft VC80. • The Microsoft MSI Installer installs shared assemblies into the common special folder SxS for use by multiple applications. they all require run-time libraries. You might have to reboot the machine in order to finalize the copy. prints version.dll and mscvcm80.1. Khorsun Applies from V.\doc.manifest—must be put into every folder where a 31 .dll.Installing on Windows where library is: fbclient | gds32 '-z' can be used with any other option. shared libraries—such as the Visual C++ and Visual C runtimes msvcp80.Win32LibraryInstallation. To avoid the dll-hell issue Microsoft introduced new rules for the distribution of components that may be shared by multiple applications. msvcr80.1 is built by the Microsoft MSVC8 compiler in Visual Studio 2005. Because all the Firebird binaries are built to use dynamic linking.2.txt which is located in . Installing Runtimes as a Private Assembly To install the MSVC8 run-time libraries as a private assembly its contents—the three DLLs mentioned above and the assembly's manifest file. Managing MSVC8 Assemblies V. the deployment system must have MSI 3. From Windows XP forward. Version information and shared library counts are handled automatically. • Private assemblies are distributed with applications and should be put into the application folder.. For more details.

ib_udf. some changes were done for V. an InterBase developer.2 in the way some of the Firebird binaries are built.exe or vcredist_x64. originally recommended deleting the GDB 32 . (On XP and Server 2003 . fbembed. To avoid the issue of bloating the installation. fbintl. except for Win95. there is no System Restore). that causes auto-updating (backup caching?) of all files on the system having a ". Known Windows Issues Over the years.dll. Server 2003 and ME) Windows XP (Home and Professional editions). They are listed here as being of possible interest when things seem to go not so well. All Win32 platforms should have this. A file in the Windows directory of ME.2. The effect is to avoid having the loader search for a MSVC8 assembly in the same folder as corresponding DLL. (See also Tracker entry CORE-2243).1. It is highly recommended to use the Microsoft redistribution package to install the MSVC8 run-time! The executable installer vcredist_x86. To find out how to go about upgrading. visit this link.gdb" suffix. the host process must have already loaded the MSVC8 run-time via manifest before any attempt is made to load these secondary DLL's. When compiling the UDF library.dll are built without any embedded manifest. because of built-in checks for the folders that are the expected location of the runtimes that are equivalent to the compile-time libraries that were used. In this case the MSVC8 assembly must be in the same folder as the UDF library b.gdb" is named there. various Windows issues that affect Firebird have been noted. it can be downloaded from the Microsoft download site.NET Servers. Charlie Caro.dll now has code to create and activate the activation context from its own manifest before loading any secondary DLL that might be required. c:\windows\system\filelist. b. These are the changes that enable Firebird Embedded to work even if the application structure does not incorporate the MSVC8 runtime assembly: a. A typical installation of Firebird Embedded would thus require three complete copies of the MSVC8 run-time assembly: one in the application folder and one each into the \intl and \udf folders.exe (as appropriate to your kit selection) should be present in the zip kits for the full installation and the Embedded version. Notes a. For this to work. The libraries ib_util.dll) resides. Third party UDFs must satisfy one of the following requirements if a MSVC8 run-time assembly is installed as private assembly. The effect is to slow down access to Firebird databases having that suffix to a virtual standstill as the files are backed up every time an I/O operation occurs.xml. ". If it is not found the install will fail. Winsock2 Firebird requires WinSock2.dll.dll. System Restore Utility (XP.Installing on Windows dependent binary (. the MSVC8 runtime EITHER: • is NOT used • is used but the build is done without the embedded manifest • is used and the build is done with the embedded manifest—the default option in the MSVC IDE. Server 2003 and ME have a feature called System Restore. fbudf. If not. contains "protected file types". A test for the Winsock2 library is made during install.exe or .

On ME. Firebird database files. which is ignored by System Restore • switch off System Restore entirely (consult Windows doc for instructions). it is not possible to edit filelist. the permanent workarounds suggested are one of: • use FDB (Firebird DB) as the extension for your primary database files--RECOMMENDED • move databases to C:\My Documents. For larger files (e. for smaller files at least.Installing on Windows extension from the "includes" section of this file. it was later demonstrated that WinME rebuilds this list.g. In XP. so the overhead seen in Windows ME may be less of an issue on XP. Windows XP uses smart copy. However.gdb" files located in the general filesystem. 33 . natch!) there doesn't seem to be a better answer as long as you have ".xml at all. On Windows XP and Server 2003 you can move your databases to a separate partition and set System Restore to exclude that volume.

Linux Platforms (Originally by Mark O'Donohue.5 must be present in your system before you attempt to install Firebird. CentOs. on the same system that you are going to run it on! 34 . • If you are installing Superserver on a Linux that supports the “new POSIX threading library ” (NPTL) then choose the NPTL build of Firebird. although the Classic server is likely to prove a better platform for initially experimenting with Firebird. OpenSuse. some with later 2. while Superserver uses threads.so. and SuperServer.Chapter 4 Installing on POSIX Platforms Please read the first two chapters before you set out to install Firebird 2. For this reason.5. There are various ways to achieve it. the generic binaries are built in a compiler environment that will ensure compatibility with the v. • 64-bit builds are available for both Classic and Superserver. Classic.6 kernel are built with NPTL enabled.0) READ THIS FIRST • You will need to be root user to install Firebird. either will do. For the user just starting out with Firebird. Details for doing this follow below.x or 2.2. which runs as a service.5 kernel. appropriate package type) provided by your distro instead of the generic one provided by the Firebird Project • by compiling Firebird yourself. to enable support for some older distros.5 Installation on Linuxen requires a glibc package installed that is equal to or greater than glibc-2.2. The Firebird packages do not support it. which runs as a background daemon. NPTL support is native on 64-bit Linux. • Do not try to use rpm --update to bring any existing Firebird package installation up to date. revised for 2. Classic is the more traditional UNIX service. However.so. as follows: • by installing a compat-glibc package (RedHat.2. Most distros with the 2.2.0. but it may be wise to prepare to revert to the regular build and set up to export the LD_ASSUME_KERNEL=2. These should be installed only on a 64-bit Linux system. Debian) or a libstdc++5 package (Mandriva) • by using a Firebird rpm (or other. the runtime library libstdc++.1. The Firebird server comes in two forms. rather than processes.x. libstdc++.4 implementation of the NPTL causes problems.5 variable if the 2.4 kernels also enabled it.

For example. have had trouble installing Firebird on Slackware.Installing on POSIX Platforms Setting Linux to Use the Old Threading Model If the NPTL causes problems for SuperServer and locally compiled programs.n-nnnnn.5 export LD_ASSUME_KERNEL That takes care of the server instance.rpm. export it (this is all in one line): export PATH USER LOGNAME MAIL HOSTNAME HISTSIZE INPUT_RC LD_ASSUME_KERNEL Installing on Linux The following instructions describe the Classic installation. you can try to solve the problem by forcing Linux to use the old threading model. Note For those who. 35 .2. To fix. the good news is that the installers in this version do include Slackware support.1.5 On the following line. after HISTSIZE=1000 add LD_ASSUME_KERNEL=2.2.d/firebird LD_ASSUME_KERNEL=2.i686. You need to have the LD_ASSUME_KERNEL environment variable set up within the local environment as well. replace nnnnn with the build number of the kit you actually have. the package FirebirdCS-2.1. For installation of Superserver the "CS" in the package name is replaced by "SS". including utilities such as gbak throwing a Broken Pipe error.n-nnnnn.i686. In the example filenames. Log in as root.1. 2. In /etc/init. in the past. or open a root shell. to ensure every user picks it up for the command line utilities. so add the following to /etc/profile.rpm is replaced by FirebirdSS-2.

localdomain and HOSTNAME to /etc/gds_hosts.Installing on POSIX Platforms RPM Installer For the RPM installer.1. Starts the server/service.n-nnnnn. Firebird should start automatically in runlevel 2. 9. Classic server installs a /etc/xinetd.d script and an /etc/rc. 2. for older inetd systems.1. 10. b.tar. employee.password./install.config Firebird entry is created. SuperServer only installs a /etc/rc.gz" file and type: $tar -xzf FirebirdCS-2. 36 . type: $rpm -ivh FirebirdCS-2.d/init. 3.i686 $.fdb.i686. a new rcfirebird link is created in /usr/bin for the init. place the ". 8. Attempt to stop any currently running server Add the user 'firebird' and the group 'firebird' if they do not already exist. 5.conf for the sample database. 4.d/firebird start script or.tar. adds an entry to the /etc/inetd file Specific to SuSE.1.equiv a. 6.rpm Installing the Tarball To install the tarball. Install the software into the directory /opt/firebird and create links for libraries in /usr/lib and header files in /usr/include Automatically add gds_db for port 3050 to /etc/services if the entry does not already exist Automatically add localhost.n-nnnnn.sh What the Linux install scripts will do The Linux install scripts will 1. 3 or 5 Generates and sets a new random SYSDBA password and stores it in the file /opt/firebird/SYSDBA. Adds an entry to aliases. 7.gz $cd FirebirdCS-2.n-nnnnn.d/firebird server start script.

the service should have a more limited ability to read/delete and create files. then change to root user and create the directory: $su . it requires some special considerations to be taken into account for creating new databases: 1. It can be obtained from the /opt/firebird/SYSDBA. the recommended value of the DatabaseAccess attribute in the /opt/firebird/firebird.password file. While this has always been the recommended configuration. While the new configuration is better from a security perspective. the server had quite wide-ranging ability to read. If a directory that is owned by the user 'firebird' does not exist.root $mkdir -p /var/firebird $chown firebird:firebird /var/firebird 37 . to permit access only through entries in the aliases.Accessing a database In a shell: $cd /opt/firebird/bin $. SQL>select rdb$relation_name from rdb$relations.conf file should be set to None. create and delete database files anywhere on the POSIX filesystem.conf to abstract users from the physical locations of databases.Installing on POSIX Platforms Testing your Linux installation Step 1 . When running as root user.conf file. use entries in aliases. For security reasons. the previous default was for the server to run as 'root' user. Step 2 . 2. the user 'firebird' has to have write permission to the directory in which you want to create the database. 3./isql -user sysdba -password <password>1 SQL>connect localhost:employee. Note 1 A password has been generated for you on installation. located in the Firebird root directory.fdb /* this is an aliased path */ SQL>select * from sales.Creating a database The Firebird server runs by default as the user 'firebird'. SQL>quit. Procedures for creating a new database can vary with different configurations but the following configuration and steps are recommended: 1. SQL>help.

SQL>quit. Create a new physical database and set up an alias entry to point to it. this script will change the init script /etc/ rc.fdb (Usage is: createAliasDB.Installing on POSIX Platforms 2. If you use this configuration. 38 .conf is set to Full or a restricted path value (for example: DatabaseAccess=/var/firebird) another alternative to step 2 is to create the physical database file directly.sh Change the Firebird SYSDBA user password.fdb 4.d/firebird to use the new password as well. As root or firebird user./createAliasDB.conf and add the line at the end of the file: test. using the absolute path with the filename: $/opt/firebird/bin/isql -u sysdba -p <password> SQL>create database '/var/firebird/test.fdb /var/firebird/test.sh script can be performed manually by: $vi /opt/firebird/aliases. SQL>quit. As an alternative (for step 2) the steps in the createAliasDB.fdb'.fdb'.sh <dbname> <pathtodb>) 3.fdb'. If the DatabaseAccess value in /opt/firebird/firebird. SQL>quit. For Superserver.fdb /var/firebird/test.d/init. Utility Scripts In addition to the standard install files the following scripts are provided in the bin directory of this release. 5. run the following script: $cd /opt/firebird/bin $.changeDBAPassword. Then create the database: $/opt/firebird/bin/isql -u sysdba -p <password> SQL>create database 'localhost:test. the database file can also be directly accessed without an entry in the aliases file: $/opt/firebird/bin/isql -u sysdba -p <password> SQL>connect '/var/firebird/test.sh test.

do it as root user. 39 . To operate in this mode. Now that it is the 'firebird' user (not root) that is the default user to run the software. fb_config A script that can be used in makefiles to generate the required include paths and lib include directives for the installed version of Firebird. he can start working with firebird databases. Uninstalling on Linux If you need to uninstall.sh Classic only-Change the client library link for libgds. Linux Server Tips "Embedded" or direct access to database files The Classic install offers an "embedded" mode of access that allows programs to open database files directly.so between the multithreaded libfbclient. Always consult the documentation for your own OS platform and version to check the latest idioms of its syntax.Installing on POSIX Platforms createAliasDB. It is documented in the readme notes.so. The following examples use Classic server but the same holds true for SuperServer by replacing the CS with SS.sh <dbname> <dbpath> This script creates a new physical database and adds an entry in the aliases. To list the groups that a user belongs to. the root user needs to do: $ usermod -a -G firebird skywalker Next time 'skywalker' logs on. We're not attempting to give you a tutorial on Linux shell syntax here. For compatibility with previous installs. you need to know how to get a user into the firebird group to enable direct access to databases.so library that allows an embedded direct open of the db file. a database-enabled user requires privileged access to some of the Firebird configuration and status files.1 Idiosyncrasy On OpenSuse 11.so by default points to libfbembed.sh Usage: createAliasDB. but the following steps should get you where you need to be. changeGdsLibraryCompatibleLink. libgds. To add a user (e. fb_config -help will give a complete list of options.1 it appears the upper case -A switch (not lower case -a) is used to append a group to the groups list that the user belongs to.so and the single threaded libfbembed.conf file. skywalker) to the firebird group. type the following at the command line: $ groups OpenSuse 11.g.

As SU.gds. Follow the instructions (choose disk.tar.plist" ].firebird.firebird.plist fi echo "Remove Framework" rm -fr /Library/Frameworks/Firebird.1. then echo "Remove Launchd" launchctl unload /Library/LaunchDaemons/org. 3. download the compressed pkg kit to a convenient location and decompress it Click on the pkg file to kick off the installation. 2.framework echo "Remove Receipt" 40 .gz install: $/opt/firebird/bin/uninstall. It should work on Tiger as well.plist rm /Library/LaunchDaemons/org. Uninstalling on MacOSX MacOSX has no uninstall utility but the following script will clean up Firebird installs on Leopard.n Uninstalling a tarball installation for the . #!/bin/sh echo "Clean Services" echo "Clean User" dscl localhost -delete /Local/Default/Users/firebird echo "Clean Group" dscl localhost -delete /Local/Default/Groups/firebird if [ -f "/Library/StartupItems/Firebird" ].firebird. enter SU password) and you are done.sh MacOSX Paul Beach Installation on MacOSX is extremely simple: 1.gds.gds.Installing on POSIX Platforms Uninstalling an RPM package For rpm packages: $rpm -e FirebirdCS-2. then echo "Remove SuperServer StartupItem" rm -fr /Library/StartupItems/Firebird fi if [ -f "/Library/LaunchDaemons/org.

Installing on POSIX Platforms rm -fr /Library/Receipts/Firebird*. Debian Not currently available.pkg Other POSIX Platforms Solaris Not currently available. FreeBSD Not currently available. 41 .

Sign up to vote on this title
UsefulNot useful