Registry / database / firebird-driver

firebird-driver

JSON →
library2.0.3pypypi✓ verified 86d ago

firebird-driver is the official Python Database API 2.0-compliant driver for the open-source relational database Firebird®. It provides a pure-Python interface built on top of the native Firebird client library, exposing both the standard DB API features and the new interface-based client API introduced in Firebird 3. The library is currently at version 2.0.2 and maintains an active release cadence with regular updates and bug fixes.

pip install firebird-driver
INSTALL
IMPORT
SIG · FIREBIRD-DRIVER
F
firebird-driver
databasepythonv2.0.3
Install
2.2s avg
Import
441ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.10.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.557s · 21.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.325s · 23MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect
from firebird.driver import connect
import firebird.driver.core as fbd
All important data, functions, classes, and constants are directly available in the `firebird.driver` namespace. Direct imports from sub-modules like `core` are generally not necessary for common usage and can lead to less portable or brittle code.
fdb
from firebird.driver import connect
import fdb
The `fdb` driver is a legacy/deprecated driver for Firebird. `firebird-driver` is its official replacement and the recommended choice for new projects, especially with Firebird 3.0+ and Python 3.8+.

This quickstart demonstrates how to establish a connection to a Firebird database, create a table (if it doesn't exist), insert data, and query data using the `firebird-driver`. It uses environment variables for database path, user, and password for security and flexibility. A local `test.fdb` will be created if `FIREBIRD_DB_PATH` is not set. Ensure the Firebird client library (`fbclient.dll` on Windows, `libfbclient.so` on Linux) is installed and accessible in your system's library path.

import os from firebird.driver import connect, DatabaseError database_path = os.environ.get('FIREBIRD_DB_PATH', 'test.fdb') user = os.environ.get('FIREBIRD_USER', 'sysdba') password = os.environ.get('FIREBIRD_PASSWORD', 'masterkey') # Ensure the Firebird client library is accessible (e.g., in PATH or LD_LIBRARY_PATH) # You might need to set fb_client_library in driver_config for specific paths. try: # Connect to the Firebird database # For a remote server, specify 'host' and 'port' in addition to 'database' # E.g., con = connect('localhost:/path/to/my.fdb', user=user, password=password) con = connect(database_path, user=user, password=password) print("Successfully connected to Firebird database!") # Create a Cursor object cur = con.cursor() # Example: Create a table try: cur.execute("CREATE TABLE languages (name VARCHAR(20), year_released INTEGER)") print("Table 'languages' created.") except DatabaseError as e: if 'Table or view already exists' in str(e): # Specific error for existing table print("Table 'languages' already exists.") else: raise # Re-raise other database errors # Example: Insert data cur.execute("INSERT INTO languages (name, year_released) VALUES (?, ?)", ('Python', 1991)) cur.execute("INSERT INTO languages (name, year_released) VALUES (?, ?)", ('C', 1972)) con.commit() print(f"{cur.rowcount} rows inserted.") # Example: Query data cur.execute("SELECT name, year_released FROM languages ORDER BY year_released") print("\n--- Languages ---") for row in cur.fetchall(): print(f"Name: {row[0]}, Released: {row[1]}") cur.close() con.close() print("Connection closed.") except DatabaseError as e: print(f"Database error: {e}") print("Ensure Firebird server is running and the client library is configured correctly.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingVersion 2.0.0 introduced several breaking changes, including raising the minimal Python version to 3.11, removal of `LoggingIdMixin` usage (requiring `firebird-base v2.0+`), and the `database` parameter for `connect` and `create_database` now accepting `pathlib.Path` objects.
fix
Upgrade Python to 3.11+, ensure `firebird-base` is version 2.0 or higher. Review `connect()` and `create_database()` calls for `pathlib.Path` usage and adapt code relying on `LoggingIdMixin` behavior.
affects: >=2.0.0
gotchaThe `firebird-driver` requires the native Firebird client library (`fbclient.dll` on Windows, `libfbclient.so` on Linux) to be installed on the system and accessible via the system's library path (e.g., `PATH` on Windows, `LD_LIBRARY_PATH` on Linux). The Python driver itself is a wrapper around this native library.
fix
Install the Firebird client tools (which include the client library) for your operating system. Ensure the directory containing `fbclient.dll` or `libfbclient.so` is in your system's `PATH` (Windows) or `LD_LIBRARY_PATH` (Linux), or explicitly configure `fb_client_library` in `driver_config`.
affects: All
gotchaThe `Cursor.close()` method in `firebird-driver` deviates from the Python DB API 2.0 specification. It only releases resources associated with the executed statement (like the result set), but the cursor instance itself remains usable for executing new SQL commands. Relying on this behavior may make code less portable.
fix
For maximum portability and adherence to DB API 2.0, consider a cursor unusable after calling `close()`. Create a new cursor instance if further operations are needed after closing the previous one.
affects: All
breakingThe `firebird-driver` is designed for Firebird 3.0 and newer. Attempting to connect to older Firebird server versions (e.g., Firebird 2.5) may result in compatibility issues or errors.
fix
Ensure your Firebird server instance is version 3.0 or higher. If you need to connect to Firebird 2.5, consider using the older `fdb` driver or upgrade your Firebird server.
affects: All
Errors
Common errors & fixes
AttributeError: object has no attribute 'logging_id' in "__del__" methods
This error typically occurs when using `firebird-driver` versions 2.0.1 or 2.0.2 with an older version of `firebird-base` (specifically, pre-2.0) where `LoggingIdMixin` was removed or changed, leading to incompatible attribute access.
fix
Upgrade `firebird-base` to version 2.0 or higher: `pip install --upgrade firebird-base`.
Database error: ('Error loading Firebird client library "fbclient.dll"', -902, 335544721)
The Firebird client library (`fbclient.dll` on Windows or `libfbclient.so` on Linux) could not be found or loaded by the Python driver. This means it's either not installed, or its location is not in the system's library search path.
fix
Install the Firebird client tools for your OS. Ensure the directory containing `fbclient.dll` (Windows) or `libfbclient.so` (Linux) is added to your system's `PATH` or `LD_LIBRARY_PATH` environment variable, or configure the `fb_client_library` path directly via `firebird.driver.driver_config.set_client_library('/path/to/fbclient.dll')`.
[ODBC Firebird Driver][Firebird]Attempt to reclose a closed cursor
While this specific message often relates to ODBC drivers, the underlying issue of attempting to close a cursor that is already closed can occur with `firebird-driver` due to its non-standard `Cursor.close()` behavior. If you call `close()` multiple times on the same cursor instance or attempt operations after it's logically 'closed' in your application logic, this can arise.
fix
Review your application's cursor management. Ensure that `cursor.close()` is called only once per logical cursor lifecycle. If you need to execute multiple statements sequentially, either reuse the cursor (knowing the `firebird-driver` allows it) or create new cursor instances explicitly for each independent operation or result set.
Database error: ('Dynamic SQL Error\nSQL error code = -104\nToken unknown - line 1, column 7\nSELECT * FORM tablename', 335544569, 335544332)
This is a generic Firebird SQL error (SQLCODE -104) indicating a syntax error in the SQL statement. The example provided shows 'FORM' instead of 'FROM'.
fix
Carefully review the SQL query for typos, incorrect keywords, missing punctuation, or other syntax mistakes. Consult Firebird SQL documentation if unsure about specific syntax elements.
Upgrade
Version history
2.0.3latest on PyPI · released Apr 20, 2026
Audit
Dependencies
firebird-baserequiredCommon modules used by Firebird Project; versions 2.0.0+ of firebird-driver require firebird-base v2.0+ implicitly due to API changes like `LoggingIdMixin` removal.
Agent activity
22 hits · last 30 days
node
22
Resources
firebird-driver — pip install firebird-driver · libregistry