{"id":8161,"library":"firebird-driver","title":"Firebird Driver for Python","description":"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.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/FirebirdSQL/python3-driver","tags":["database","firebird","dbapi","sql","rdbms"],"install":[{"cmd":"pip install firebird-driver","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Common 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.","package":"firebird-base","optional":false}],"imports":[{"note":"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.","wrong":"import firebird.driver.core as fbd","symbol":"connect","correct":"from firebird.driver import connect"},{"note":"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+.","wrong":"import fdb","symbol":"fdb","correct":"from firebird.driver import connect"}],"quickstart":{"code":"import os\nfrom firebird.driver import connect, DatabaseError\n\ndatabase_path = os.environ.get('FIREBIRD_DB_PATH', 'test.fdb')\nuser = os.environ.get('FIREBIRD_USER', 'sysdba')\npassword = os.environ.get('FIREBIRD_PASSWORD', 'masterkey')\n\n# Ensure the Firebird client library is accessible (e.g., in PATH or LD_LIBRARY_PATH)\n# You might need to set fb_client_library in driver_config for specific paths.\n\ntry:\n    # Connect to the Firebird database\n    # For a remote server, specify 'host' and 'port' in addition to 'database'\n    # E.g., con = connect('localhost:/path/to/my.fdb', user=user, password=password)\n    con = connect(database_path, user=user, password=password)\n    print(\"Successfully connected to Firebird database!\")\n\n    # Create a Cursor object\n    cur = con.cursor()\n\n    # Example: Create a table\n    try:\n        cur.execute(\"CREATE TABLE languages (name VARCHAR(20), year_released INTEGER)\")\n        print(\"Table 'languages' created.\")\n    except DatabaseError as e:\n        if 'Table or view already exists' in str(e): # Specific error for existing table\n            print(\"Table 'languages' already exists.\")\n        else:\n            raise # Re-raise other database errors\n\n    # Example: Insert data\n    cur.execute(\"INSERT INTO languages (name, year_released) VALUES (?, ?)\", ('Python', 1991))\n    cur.execute(\"INSERT INTO languages (name, year_released) VALUES (?, ?)\", ('C', 1972))\n    con.commit()\n    print(f\"{cur.rowcount} rows inserted.\")\n\n    # Example: Query data\n    cur.execute(\"SELECT name, year_released FROM languages ORDER BY year_released\")\n    print(\"\\n--- Languages ---\")\n    for row in cur.fetchall():\n        print(f\"Name: {row[0]}, Released: {row[1]}\")\n\n    cur.close()\n    con.close()\n    print(\"Connection closed.\")\n\nexcept DatabaseError as e:\n    print(f\"Database error: {e}\")\n    print(\"Ensure Firebird server is running and the client library is configured correctly.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The `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.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade `firebird-base` to version 2.0 or higher: `pip install --upgrade firebird-base`.","cause":"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.","error":"AttributeError: object has no attribute 'logging_id' in \"__del__\" methods"},{"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')`.","cause":"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.","error":"Database error: ('Error loading Firebird client library \"fbclient.dll\"', -902, 335544721)"},{"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.","cause":"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.","error":"[ODBC Firebird Driver][Firebird]Attempt to reclose a closed cursor"},{"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.","cause":"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'.","error":"Database error: ('Dynamic SQL Error\\nSQL error code = -104\\nToken unknown - line 1, column 7\\nSELECT * FORM tablename', 335544569, 335544332)"}]}