New Firebird driver for Python – preview release

There is now an official preview release – v0.5.0 – available on PyPI:

All core driver functionality works, except handling of limbo
transactions due to error discovered in Firebird (should be fixed in
soon to be released Firebird 3.0.6).

This preview version was released because the driver architecture is
evolving rapidly, and I would like get some feedback before the initial
release planned for end of June.

Some important notes about the driver architecture:

  1. It uses namespace package “firebird”, and the driver is distributed
    as “firebird.driver” package. There are other packages that share the
    same namespace: “firebird.base” and “firebird.butler”. In future I’d
    like introduce “firebird.lib” package for extension libraries (former
    schema, monitor and other extension modules in FDB).
  2. Although the initial driver design was close to FDB, there are
    significant differences and the driver architecture and API will diverge
    further from FDB or KInterbasDB. The sole backward “compatibility” is
    defined as compliance to Python DB API 2.0. So the new driver is not and
    will not be a drop-in replacement for FDB.

Here are some main decisions related to implementation and architecture:

a) Safe use. This translates to extensive use of type hints and
annotations, including Protocols etc. Also many arguments are defined as
keyword only to avoid ambiguity and improve code readability. This is
one from main reasons why Python 3.8 is minimal version required.

b) Wrong run-time conditions (like not closed connection) and some
arguments are checked ONLY as asserts. So optimized Python code does not
performs any such checks. Note that used trace/audit could be also
affected by optimization (depends on how you use it, see firebird-base
documentation for details).

c) Compact code. It often means that latest Python features are used
anywhere it makes sense (that includes := operator etc.).

d) Simplicity. This for example also means minimal number of names
defined, so all various constants and flags used by Firebird API are
defined as Python enums/flags. That same apply to number of function
parameters (with few exceptions).

  1. The driver uses “firebird.base” package, which is a collection of
    modules that have general applicability, like extended configuration,
    context-driven logging and trace/audit, hooks, work with structured
    binary buffers, extended data structures etc. See:
    and raw documentation at
    This package is a shared base for current and future Python development
    projects under Firebird Project umbrella (currently the driver, soon the
    Saturnin and QA suite etc.)

The driver uses almost all features provided by “base” package, but
specifically the use of hook mechanism and context-driven logging and
trace/audit are potentially the most valuable improvements, so any
usability feedback would be appreciated. I also plan to take advantage
of extended configuration, so any ideas or suggestions about driver’s
configuration options would be appreciated.

  1. With release of Firebird 4.0 beta 2, I started to adapt the driver to
    new Firebird version. Part of this adaptation is new architecture that
    moves some functionality into separate “inner” classes, so it could be
    switched at run-time according to used Firebird version (or ODS). So
    far, all information-related functionality (methods and properties) in
    Connection and Transaction was moved out into “Info” objects, accessible
    through “info” property (i.e. etc.). The
    Services class was renamed to Server, and over next month I’ll move out
    all services-related functionality into series of separate
    domain-specific inner objects like “backup”, “config”, “trace”, “users” etc.

The reference documentation is here:

  1. Please note, that FDB is now considered as legacy driver, and its
    development will be discontinued together with 2.5 once Firebird 4.0
    will be released later this year. However, one FDB maintenance release
    is planned before that, so if you have any pending issues or pull
    requests for FDB, please let me know.

best regards
Pavel Cisar

1 Star2 Stars3 Stars4 Stars5 Stars (4 votes, average: 5.00 out of 5)

Leave a Reply