Null External Engine for Firebird RDBMS

A special plugin for Firebird that helps restore databases with missing user modules.

The problem

Firebird has featured the ability to add custom user-developed external functions since version 3.0. This is achieved by installing modules for the stock UDR subsystem or by developing a custom External Engine plugin.

In case a database backup is performed on one server and there is a need to restore it on another server, the latter must have the same user modules installed, or the restore process will fail.

The Firebird core distinguishes External Engines by their names. All UDR user modules are accessed through a stock 'UDR' External Engine. Any additional External Engines will have unique names, e.g. 'FOO'.

The Firebird code was updated to ignore missing user UDR modules, but only for UDR, and only for versions 5.0+ (the feature was backported to version 4.0.2 also).

To summarize: for server versions less than 5.0, and also for any custom non-UDR External Engine the database restore process will fail if the required user modules are not installed on the server.

Null Engine

The Null Engine developed here eliminates the problem by providing the ability to masquerade as any External Engine name. The simplified procedure is as follows: place the null_engine module into the Firebird plugins directory; rename it to a specific name; and edit plugins.conf to target this new module. The detailed instructions are given below.

How it works

For a general discussion of the internals and implementation of the Firebird External Engine please refer to this paper.

The Null Engine exploits the fact that the Firebird core does not check the validity of the metadata (arguments and returned values) of external functions, procedures and triggers. When a restore process encounters a reference to an external function, it loads the corresponding External Engine and asks whether the given function name exists. The Null Engine returns "true" for any name it is asked.

Building

Currently, only Linux builds are supported. Note that you must build for your server target architecture.

The Null Engine has no external dependencies. A single target is produced: libnull_engine.so

git clone https://github.com/mxck438/null_engine
cd null_engine
mkdir build && cd build
cmake ..
make

Installation

For UDR engine

• Copy libnull_engine.so to the Firebird plugins directory.
• Rename the module to libUDR.so
• Edit plugins.conf to match the following:

#Plugin = UDR {
#	Module = $(dir_plugins)/udr_engine
#	Config = UDR_config
#}

#Config = UDR_config {
#	path = $(dir_plugins)/udr
#}

Plugin = UDR {
	Module = $(dir_plugins)/libUDR.so
}

• Restart the Firebird server.

For any External Engine

To replace an External Engine named 'FOO':

• Copy libnull_engine.so to the Firebird plugins directory.
• Rename the module to libFOO.so
• Edit plugins.conf to match the following:

#Plugin = FOO {
#	Module = $(dir_plugins)/foo_engine
#	Config = UDR_config
#}

Plugin = FOO {
	Module = $(dir_plugins)/libFOO.so
}

• Restart the Firebird server.

You may have as many substituted External Engines as you like.

Runtime behaviour

You should receive no errors or warnings while restoring a database. The database metadata will still contain all external function declarations. If an attempt is made to call an external function, a Firebird exception will be returned saying, "not implemented and won't ever be".

Testing

The Null Engine was successfully tested on Debian 11 Bullseye and Ubuntu 22.04.01 LTS Jammy on server versions 3.0.7 and 5.0.3.