Client and server combined: Firebird Embedded Server

Embedded server on Windows

The Windows Embedded Server is a Superserver engine plus client rolled into one library, called fbembed.dll. It is available as a separate download package. The embedded server (introduced with Firebird 1.5) was specifically designed to facilitate deployment of applications that ship with a Firebird server included. Installation is just a matter of unpacking the DLL and a few other files to the desired location. The security database is not used at all: anyone can connect to any database, as long as the user running the application has filesystem-level access rights to the database(s) in question.

You can have multiple embedded servers running at the same time, and you can have multiple apps connecting to the same embedded server. Having a regular server already running isn't a problem either. However, an embedded server locks a database file for its own exclusive use after successful connection. This means that you cannot access the same database from multiple embedded server processes simultaneously (or from any other servers, once an embedded server has locked the file).

The embedded server has no facility to accept any network connections. Only true local access is possible, with a connect string that doesn't contain a host name (not even localhost).

Needless to say, this is not for your regular client-server database usage, as it bypasses a lot of security features. It's using Firebird as a desktop database system.

Note

A Firebird embedded server DLL can also be used as a network client. That is, if a regular Firebird server is listening for connections on the target computer, you can connect to databases on that system using a network-style connect string like inca:C:\School\Databases\Pupils.fdb.

This also implies that if a regular server is active on your local computer, you can connect to local databases through that regular server with your embedded server as a client using the “localhost:” syntax. This may seem contradictory to what has been said before about the absence of network support, but bear in mind that if you connect to localhost (or any other host), you are not using the embedded server; you're only using the client part of fbembed.dll to connect to another server. You'll have to provide a valid user name and password for this to work.

Embedded server deployment

First, download the Embedded server kit from SourceForge. It's typically named Firebird-n.n.n.xxxx_embed_win32.zip, with n.n.n.xxxx the Firebird version and build number.

After unzipping, you'll find the embedded server fbembed.dll in the root directory of the package, along with some other files. Additionally, there are three subdirectories doc, intl and udf.

To make your application work with the embedded server:

Copy fbembed.dll into your application directory. Rename it to fbclient.dll or gds32.dll, depending on what your application expects as a Firebird client filename. Many applications still look for gds32.dll. Firebird command-line tools like isql and gbak – which you can also run against the embedded server – want fbclient.dll. You can also make copies with both names.
Also copy firebird.msg and ib_util.dll to your application directory. Copy aliases.conf if your application uses aliases to connect. The configuration file firebird.conf is only needed if you want to change the Firebird root directory; this will be discussed later.
For Firebird 2 or higher, copy the icu*.dll libraries too.
From the intl and udf directories, copy whatever your application or databases may need to same-named folders under your application directory.
Now if you run your application it will use the embedded server DLL to connect to any local database you desire, provided that the Windows user who runs the application has sufficient access rights to the database file(s) in question! Any combination of user name and password is accepted, as long as neither is an empty string (a space is OK though).

The most important benefit of all this is that you can easily pack the Firebird Embedded files with your application and have them installed or unzipped at your users' computers without having to perform a separate Firebird install there (with all the additional worries of sufficient privileges, possible interference with already present Firebird or InterBase servers, etc. etc.). You can also have several embedded server versions (say 1.5.3 and 2.0) running on the same computer without the need for special configuration steps to keep them out of each other's way.

Note

Please note that, even though the security database is bypassed, SQL privileges – specified in the database itself – still apply: if you connect as Firebird user ZIGGY and ZIGGY doesn't have access to table STARDUST, you won't get into that table. This is not as worrying as it seems, because you can connect as any user you like, including SYSDBA, with a dummy password.

Placing the Firebird files elsewhere

By default, Firebird Embedded Server considers the folder that fbembed.dll lives in (under whatever name) as the Firebird root directory. In the setup described above, this is your application directory. You may want to place the Firebird files somewhere else, so as not to clutter your application directory. To do this, you must tell the server where to look for them.

Let's say you want the Firebird files to reside in a folder called D:\FbEmbedded:

Copy firebird.conf to your application directory and edit the RootDirectory parameter like this:
```
RootDirectory = D:\FbEmbedded
```
Alternatively, you may set the FIREBIRD environment variable to achieve the same. If both the configuration file parameter and the FIREBIRD envar are present, the latter takes precedence. Warning: the FIREBIRD environment variable will be picked up by every Firebird server on the system (embedded or not) at startup, and override their registry settings and configuration file parameters. So use it with care, if at all.
Copy/move the following items to D:\FbEmbedded:
- firebird.msg
- aliases.conf (if used)
- the intl and udf subdirs plus contents (in so far as needed)
The following files however must be left in your application's directory:
- Any and all copies/renames of fbembed.dll
- firebird.conf
- ib_util.dll
- for Firebird 2 and up: the icu*.dll libraries

Embedded server on Linux?

The Linux Classic server comes with a client library called libfbembed.so which is used for local connections. This library contains a full Firebird engine, which explains why it's so much bigger than the Superserver client library. Local connections through this library are part of the user application process, not of a separate server process. Therefore, the user of the library must have filesystem-level access rights to the database – just as with Windows Embedded. So yes, this is a true embedded server.

There are also some differences. First, Linux Classic doesn't require an exclusive lock on the databases it opens. The database remains accessible from other clients. A further – very important – difference is that Linux Classic validates every login against the security database: no connections with phony user names or passwords here! Finally, you can't just ship libfbembed.so with your application and use it to connect to local databases. Under Linux, you always need a properly installed server, be it Classic or Super.