Embedded Firebird 3
Embedded Firebird 3
Embedded Firebird 3
Embedded in Firebird 3
Everything you need for deploying Firebird 3 embedded with your application is present
in the .zip (Windows) or .tar.gz (Linux) kit that you download from the Firebird website.
We'll work with mainly with the Windows zip kit here, but the principle is the same for
the Linux kit: unzip the Windows kit into its own folder or decompress and untar the
Linux one into its own directory. There are differences between structures of the file
systems now, specifically in the location of the binary files: Linux retains them in the
/bin directory beneath the Firebird root, whereas Windows has them all directly in the
Firebird root.
The following screenshot shows the Firebird root directory with the files and sub-
directories we might want at this point:
#Providers = Remote,Engine12,Loopback
Embedded Server in Firebird 3 Page 4 of 6
The engine12 plug-in is used for all deployment models on all platforms. Remote
additionally enables connections from the LAN or WAN; Loopback additionally enables
connections through the TCP/IP local loopback interface. If all are present in the
configuration, the server can accept connections from any of the interfaces. Connection
style is governed by the connection path.
For a simple embedded setup that mimics the pre-V.3 one, there is no need to modify the
default configuration for Providers on a machine that is not running a Firebird network
server. When the Dispatcher encounters a hostless connection path, it first tries the
Remote provider and, as expected, fails in the absence of the networked service. Next, it
tries the Engine12 provider, which should succeed if the database is not exclusively locked
by a Superserver process or another embedded engine instance. The Dispatcher's last
resort would be to call on the Loopback provider to attempt an XNET or INET connection,
which would fail in the absence of login credentials.
If the system does have a Firebird network server running, you can eliminate it from the
scope of your application by simply uncommenting the Providers parameter and deleting
the Remote and Loopback options:
Providers = Engine12
Note that it is now possible for the application to pass some configuration elements via the
DPB or SPB of the connection request as a string argument on the connection tag
isc_dbp_config or isc_spb_config, as the case may be. It could pass "Providers = Engine12"
in the attach database call, if practicable, avoiding the need to configure it specifically.
The form is:
isc_dbp_config | isc_spb_config <string-length> "<config-fragment>"
E.g.,
isc_dbp_config 21 "Providers = Engine12"
When multiple parameters are configured via the isc_xxx_config tag, use the \n (newline)
symbol to separate the parameters within the string, counting each \n as one character.
Illustration
To illustrate our embedded application at work, we will use isql to connect to the employee
database, which the default installation aliases in databases.conf as employee. An
Embedded Server in Firebird 3 Page 5 of 6
embedded connection does not authenticate, so a user name and password are not
required.
C:\Programs64\Firebird_3_0_embedded>isql employee
Database: employee, User: HELEN
SQL> show tables;
COUNTRY CUSTOMER
DEPARTMENT EMPLOYEE
EMPLOYEE_PROJECT JOB
PROJECT PROJ_DEPT_BUDGET
SALARY_HISTORY SALES
SQL> exit;
User HELEN is just an ordinary, serverwide user on Windows, which the engine requests
from the operating system if user name not passed explicitly, or obtained implicitly from
the environment variables (ISC_USER, et al.).
Although no authentication is required, we still might need to log in explicitly as SYSDBA
or another user with non-public privileges. In that case, we need to supply the user name.
The password is not required, since authentication still does not apply. The user name
will be associated with privileges and mappings in the specified database.
#ServerMode = Super
As such, it needs to acquire an exclusive lock on the database file to connect and, while
connected, it prevents shared connections from other engine instances. With this
Embedded Server in Firebird 3 Page 6 of 6
The solution is to run your embedded engine as a [Super]Classic process in concert with
your Superclassic or Classic server. Uncomment the ServerMode parameter in the
firebird.conf of your embedded structure and set it to Classic or Superclassic:
ServerMode = Classic
Note, for the embedded engine, Classic and Superclassic are equivalent.
Conclusion
That's all it takes to construct a framework for your embedded engine application in
Firebird 3. You can set it up with as much or as little functionality as you want. Just add
your application, stir gently, and you are good to go.
.