Jaybird with Firebird embedded example

08 September 2017

I just published a small example program using Firebird 3 Embedded with Jaybird 3. You can find it on https://github.com/mrotteveel/jaybird-embedded-example.

This example is Windows (64 bit) specific, but should easily translate to other platforms (just a matter of including the equivalent libraries in the fb folder).

Running the example

To compile and run the example application from the commandline, use:

gradlew run -Dexec.args="--create"

Or use gradlew build and unzip the distribution in build\distributions and from the unzipped folder execute:

.\bin\embedded-example.bat --create

Specifying the --create option is only necessary on first run to create the (default) database file. See --help for other options.

Details on embedded use

The fb folder of the example program contains all DLL files necessary for Firebird embedded to work:

fb
|--intl
|  |--fbintl.conf
|  \--fbintl.dll
|--plugins
|  |--engine12.dll
|  |--fbtrace.dll
|  |--legacy_auth.dll
|  |--legacy_usermanager.dll
|  |--srp.dll
|  |--udr_engine.conf
|  \--udr_engine.dll
|--fbclient.dll
|--icudt52.dll
|--icudt52l.dll
|--icuin52.dll
\--icuuc52.dll

The fb folder is a trimmed down version of a normal Firebird installation. It is possible that some of the DLLs in the plugins folder are not necessary (this may require tweaking firebird.conf), and error logging suggests it might be necessary to include ib_util.dll as well, but the example program works without it. If you need additional configuration, then you can include a firebird.conf.

By default Jaybird 3 is only able to use the pure Java implementation of the wire protocol. For Jaybird to be able to use Firebird Embedded, you need to do two things:

  1. Include the JNA (Java Native Access) library (version 4.4.0 at time of writing)

  2. Add the fb folder (or equivalent) to the search path for JNA

    1. Either specify the jna.library.path system property with the absolute or relative path to the folder

    2. Or include the folder on the PATH environment variable

    3. Another option is to make the fb folder the current working directory when executing the program, but this has the downside that it would be harder to support both 32 bit and 64 bit.

Supporting both 32 bit and 64 bit should be a matter of having a fb32 and a fb64 and adding both to the search path.

The example application will add the fb folder to the JNA search path itself when the system property jna.library.path hasn’t been specified explicitly:

private static void tryConfigureJNA() {
    String jnaPath = System.getProperty("jna.library.path");
    if (jnaPath == null || jnaPath.isEmpty()) {
        Path path = Paths.get("fb").toAbsolutePath();
        System.out.println("Attempting to set jna.library.path to: " + path);
        System.setProperty("jna.library.path", path.toString());
    }
}

To actually use Firebird Embedded is then just a matter of specifying the right connection URL:

"jdbc:firebirdsql:embedded:" + getDatabasePath()

Be aware that with the default configuration, fbclient.dll will try the embedded engine, but if that doesn’t work (eg engine12.dll cannot be loaded), it will then try the localhost server. This behaviour can be changed by adding a firebird.conf with setting Providers = Engine12 (which will disable the Remote and Loopback providers).