Firebird embedded on Linux HOWTO


I've found two guides [1][2] on the Internet, but they were brief and left some questions open. They also assume you know how to work with full Firebird server version. I decided to write one for complete beginners who don't have much Firebird knowledge.

Important: This HOWTO is meant for machines that don't even have Firebird installed. If you do have Firebird installed, you probably won't have to go through all these steps. You also don't need to have access to root account.



Step 1: download the Classic Server .tar.gz package


Firebird comes in two flavors: Super Server and Classic Server. Classic server can be used as embedded.
This HOWTO is created while using ClassicServer version 1.5.3.
There are .rpm and .tar.gz binary packages. Download the .tar.gz as it is easier to unpack

Step 2: unpack it and copy files


Inside the FirebirdCS-1.5.3.4870.i686.tar.gz file, you'll find buildroot.tar.gz file which you need to unpack as well. Now, go to directory opt/firebird in unpacked archive and copy the following files to some folder of your choice. This is the folder from which your app. will be run. Let's assume it's /home/milanb/fbembed. Also create subdirectories bin and intl for files that go there:

libfbembed.so
libfbembed.so.1
libfbembed.so.1.5.3
firebird.msg 
security.fdb 
bin/fb_lock_mgr
bin/isql
intl/fbintl

The files libfbembed.so... are found in lib directory, but don't create lib subdirectory in your tree. See the final directory structure for more info.

Create a file firebird.conf and put the following line into it:

RootDirectory = /home/milanb/fbembed

To work any further you need to setup two environment variables:

export LD_LIBRARY_PATH=/home/milanb/fbembed
export FIREBIRD=/home/milanb/fbembed


Step 3: create a database


Just to make sure everything is working, we'll create the test database. There is a default username SYSDBA with password masterkey:

milanb@xx:~/fbembed$ bin/isql -user sysdba -pass masterkey
Use CONNECT or CREATE DATABASE to specify a database
SQL> create database 'test.fdb';
lock manager: couldn't set uid to superuser
SQL> exit;

It is normal to get that error on the first run. The trick is to simply log out, and lock manager would happily run under your username (milanb in my case). You can check that with ps auxw | grep fb_lock_mgr. Now we connect back to the database:

milanb@xx:~/fbembed$ bin/isql -user sysdba -pass masterkey test.fdb
Database:  test.fdb, User: sysdba
SQL> show tables;
There are no tables in this database
SQL> create table table1
CON> (
CON>   x integer,
CON>   s varchar(20)
CON> );
SQL> exit;

Well, that's about it. Everything is setup and now you should put your executable into this directory and run it.


Step 4: compiling a test IBPP application

You can download IBPP library from www.ibpp.org. Only source version is available, and that is exactly what we need. I took ibpp-2.5.2.2-src.zip. Unpack the file (be careful, there are few files that unpack into current directory). We only need files from core directory. Create directory ibpp inside fbembed and copy the files from core there. In my example I have /home/milanb/fbembed/ibpp. Take a look at final directory structure to get the idea.

Now we'll write a simple program that connects to that test.fdb database we created in step 3, insert some values into table table1, and read them back.

test.cpp
 
#include <iostream>
#include "ibpp/ibpp.h"

using namespace std;

int main()
{
    cout << "Testing Firebird embedded with IBPP library" << endl;

    try
    {
        cout << "Connecting to database test.fdb" << endl;
        IBPP::Database db1 = IBPP::DatabaseFactory("", "test.fdb",
            "SYSDBA", "masterkey");
        db1->Connect();

        cout << "Starting transaction" << endl;
        IBPP::Transaction tr1 = IBPP::TransactionFactory(db1);
        tr1->Start();

        cout << "Preparing statement" << endl;
        IBPP::Statement st1 = IBPP::StatementFactory(db1, tr1);
        st1->Prepare("insert into table1 (x,s) values (1, 'milan')");
        st1->Execute();

        cout << "Reading data" << endl;
        st1->Prepare("select x,s from table1");
        st1->Execute();
        while (st1->Fetch())
        {
            int x;
            string s;
            st1->Get(1, x);
            st1->Get(2, s);
            cout << "X = " << x << ", S = " << s << endl;
        }
        tr1->Commit();
    }
    catch (IBPP::Exception& e)
    {
        cout << e.what() << endl;
    }
    return 0;
}


To compile, run:

g++ -DIBPP_LINUX -L. -lfbembed test.cpp ibpp/all_in_one.cpp -o test

You should have executable "test" in current directory. Now run it:

milanb@xx:~/fbembed$ ./test
Testing Firebird embedded with IBPP library
Connecting to database test.fdb
Starting transaction
Preparing statement
Reading data
X = 1, S = milan

Of course, for your application with many source files, you'll create a makefile. In that makefile, you need to add ibpp/all_in_one.cpp to your source files, and -lfbembed to linker flags. In order to find libfbembed, linker needs to look into directory with that .so file, so you need to give -L/home/milanb/fbembed or whatever is the path on your system (I used -L. in the above example, which means to look in current directory, but that is bad idea for makefiles which might change the current working directory). IBPP_LINUX has to be defined for all files that include ibpp.h, so you best add -DIBPP_LINUX to compiler options.

Final notes


As you can see, it's quite possible to create, develop and run an application that uses embedded Firebird on Linux, without having access to root account or having full Firebird package installed. However, quick development assumes that you have administration tool concurrently accessing the database with application (you change things in admin. tool and observe have application behaves, or you monitor what is application doing). So I recommend that you install the full Firebird server for development, and only use embedded variant when you deploy the application. As for administration tools, if you are a Linux user (as is assumed audience of this HOWTO) you should look into FlameRobin.

If you have problems with this setup or you have questions about Firebird usage, please join the firebird-support mailing list. I read it on a daily basis (except when on vacation), and there are many others who are very helpful.


Getting more info on Firebird

Here are the links shown in top-left corner of Firebird website:

Novice Guide
http://www.firebirdsql.org/index.php?op=guide

FAQ
http://www.firebirdsql.org/index.php?op=faq

Firebird 1.5 Quick Start Guide
http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf


Final directory structure


Here's the list of files I had after completing this HOWTO on a clean machine:

/home/milanb/fbembed
|-- bin
|   |-- fb_lock_mgr
|   `-- isql
|-- firebird.conf
|-- firebird.msg
|-- ibpp
|   |-- _dpb.cpp
|   |-- _ibpp.cpp
|   |-- _ibpp.h
|   |-- _ibs.cpp
|   |-- _rb.cpp
|   |-- _spb.cpp
|   |-- _tpb.cpp
|   |-- all_in_one.cpp
|   |-- array.cpp
|   |-- blob.cpp
|   |-- database.cpp
|   |-- date.cpp
|   |-- dbkey.cpp
|   |-- events.cpp
|   |-- exception.cpp
|   |-- ibase.h
|   |-- iberror.h
|   |-- ibpp.h
|   |-- row.cpp
|   |-- service.cpp
|   |-- statement.cpp
|   |-- time.cpp
|   |-- transaction.cpp
|   `-- user.cpp
|-- intl
|   `-- fbintl
|-- libfbembed.so -> libfbembed.so.1
|-- libfbembed.so.1 -> libfbembed.so.1.5.3
|-- libfbembed.so.1.5.3
|-- security.fdb
|-- test
|-- test.cpp
`-- test.fdb


Copyright © 2006. Milan Babuskov