{"id":9330,"library":"sqlalchemy-firebird","title":"Firebird for SQLAlchemy","description":"SQLAlchemy-Firebird is an external dialect for SQLAlchemy, enabling Python applications to connect and interact with Firebird relational database servers. It provides a DBAPI 2.0 compliant interface, supporting both the `firebird-driver` (recommended for Python 3.8+ and Firebird 3+) and `fdb` drivers (for Python < 3.8 / SQLAlchemy 1.4+ and Firebird 2.5/3.0+). The library is actively maintained, with its current version being 2.1, and saw its last stable release in January 2024.","status":"active","version":"2.1","language":"en","source_language":"en","source_url":"https://github.com/pauldex/sqlalchemy-firebird","tags":["sqlalchemy","firebird","database","orm","dialect","sql"],"install":[{"cmd":"pip install sqlalchemy-firebird","lang":"bash","label":"Basic Installation (Python 3.8+)"},{"cmd":"pip install sqlalchemy-firebird fdb","lang":"bash","label":"For Firebird 2.5 servers or older Python versions"}],"dependencies":[{"reason":"Core ORM/SQL toolkit functionality.","package":"SQLAlchemy","optional":false},{"reason":"Default Python DBAPI driver for Firebird 3+ (automatically installed for Python 3.8+).","package":"firebird-driver","optional":true},{"reason":"Alternative Python DBAPI driver, required for Firebird 2.5 servers or older Python versions (not automatically installed for Python 3.8+).","package":"fdb","optional":true},{"reason":"Native Firebird client library (e.g., `libfbclient.so` on Linux, `fbclient.dll` on Windows) is required on the system where the application runs, especially for embedded or local connections, or if specified in the connection string.","package":"Firebird Client Library","optional":false}],"imports":[{"symbol":"create_engine","correct":"from sqlalchemy import create_engine"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, text\n\n# Configure Firebird connection details via environment variables\nFB_USER = os.environ.get('FIREBIRD_USER', 'sysdba')\nFB_PASSWORD = os.environ.get('FIREBIRD_PASSWORD', 'masterkey')\nFB_HOST = os.environ.get('FIREBIRD_HOST', 'localhost')\nFB_PORT = os.environ.get('FIREBIRD_PORT', '3050')\nFB_DB_PATH = os.environ.get('FIREBIRD_DB_PATH', '/opt/firebird/data/employee.fdb') # Example for Linux\n# For Windows, path might be 'C:/path/to/my_project.fdb'\n# Optional: Specify client library path if needed, e.g., 'C:/Firebird/Firebird_4_0/bin/fbclient.dll'\nFB_CLIENT_LIB = os.environ.get('FIREBIRD_CLIENT_LIBRARY', '')\n\n# Construct the connection URI. Use 'firebird+firebird' for firebird-driver (Python 3.8+)\n# or 'firebird+fdb' for fdb driver (older Python/Firebird 2.5).\n# The 'firebird' driver is assumed to be firebird-driver for Python 3.8+\ndb_uri_parts = [\n    f\"firebird+firebird://{FB_USER}:{FB_PASSWORD}@{FB_HOST}:{FB_PORT}{FB_DB_PATH}\"\n]\nif FB_CLIENT_LIB:\n    db_uri_parts.append(f\"?fb_client_library={FB_CLIENT_LIB}\")\n\ndb_uri = \"\".join(db_uri_parts)\n\nprint(f\"Attempting to connect to: {db_uri.split(':', 2)[0]}://{FB_USER}:****@{FB_HOST}:{FB_PORT}{FB_DB_PATH}\")\n\ntry:\n    engine = create_engine(db_uri, echo=True)\n\n    with engine.connect() as connection:\n        # Example: Fetch Firebird engine version\n        result = connection.execute(text(\"SELECT RDB$GET_CONTEXT('SYSTEM', 'ENGINE_VERSION') FROM RDB$DATABASE\"))\n        version = result.scalar()\n        print(f\"Successfully connected to Firebird. Engine Version: {version}\")\n        connection.commit()\n\nexcept Exception as e:\n    print(f\"Connection failed: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to a Firebird database using SQLAlchemy-Firebird and the `create_engine` function. It utilizes environment variables for database credentials and paths, making it suitable for various deployments. It includes a basic query to retrieve the Firebird engine version to confirm connectivity. The example defaults to `firebird-driver` (via `firebird+firebird://`) but notes the `fdb` alternative."},"warnings":[{"fix":"Refer to the SQLAlchemy 2.0 Major Migration Guide for detailed steps. Update `select()` calls, replace `baked` queries with standard 2.0-style statements, and adjust ORM configuration imports.","message":"When migrating an existing SQLAlchemy application from 1.x to 2.0 with `sqlalchemy-firebird`, be aware of major API shifts in SQLAlchemy core. This includes changes to `select()` (positional arguments), removal of the `sqlalchemy.ext.baked` extension, and changes to `Query.get()` (now `Session.get()`), and the consolidation of declarative API imports. While `sqlalchemy-firebird` is 2.0 compatible, your application code may require updates.","severity":"breaking","affected_versions":"SQLAlchemy 1.x to 2.x"},{"fix":"Ensure DDL operations are performed when there are no active connections. For queries, always fully consume result sets (e.g., by iterating or calling `.fetchall()`, `.first()`, or ensuring the `ResultProxy` is closed).","message":"Firebird databases can exhibit aggressive locking behavior, especially during Data Definition Language (DDL) operations (e.g., `DROP TABLE`). Transactions may hang if other connections are active. This also applies if result sets are not fully consumed, as the underlying connection resources might not be immediately released.","severity":"gotcha","affected_versions":"All"},{"fix":"Install the correct driver (`pip install fdb` if `firebird-driver` isn't suitable) and adjust your connection URI to `firebird+fdb://` if using `fdb`.","message":"The appropriate Python DBAPI driver must be installed alongside `sqlalchemy-firebird` and chosen correctly in the connection string. For Python 3.8+ and Firebird 3+, `firebird-driver` is generally preferred (`firebird+firebird://`). For older Python versions (e.g., 3.6/3.7) or Firebird 2.5 servers, `fdb` might be necessary (`firebird+fdb://`).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the Firebird client library is installed and its directory is in your system's PATH environment variable, or add `?fb_client_library=/path/to/fbclient.dll` (or `.so`) to your connection URI.","message":"Connecting to a Firebird database, especially for embedded or local server instances, often requires the native Firebird client library (`fbclient.dll` on Windows, `libfbclient.so` on Linux) to be present and discoverable in the system's PATH or explicitly specified in the connection string. Without it, connection attempts will fail.","severity":"gotcha","affected_versions":"All"},{"fix":"Store Firebird database files in paths containing only ASCII characters. If unavoidable, investigate filesystem encoding settings or driver-specific path encoding options, though ASCII paths are the most reliable solution.","message":"Using non-ASCII or non-latin characters in the database file path can lead to connection errors, particularly when using the `fdb` driver. The driver or underlying Firebird client library might not correctly interpret the encoded path.","severity":"gotcha","affected_versions":"All, particularly with `fdb` driver"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the missing driver: `pip install fdb` (or `pip install firebird-driver` if using `firebird+firebird://`).","cause":"The Python DBAPI driver specified in the connection string (e.g., 'fdb') is not installed or not accessible.","error":"sqlalchemy.exc.ArgumentError: Could not determine dialect for 'firebird+fdb'"},{"fix":"Grant appropriate filesystem permissions to the Firebird database file and its containing directory for the user account under which the Firebird server or your application is running.","cause":"The Firebird server process (or the user running an embedded Firebird) lacks sufficient read/write permissions for the specified database file or its directory.","error":"(fdb.fbcore.DatabaseError) ('Error while connecting to database:\\n- SQLCODE: -551\\n- no permission for read-write access - database /path/to/my.fdb'"},{"fix":"Verify the absolute path to your `.fdb` file. Ensure the Firebird client library (`fbclient.dll` or `libfbclient.so`) is in your system's PATH or explicitly passed in the URI (e.g., `?fb_client_library=/path/to/libfbclient.so`). Check for non-latin characters in the path.","cause":"The database file path in the connection string is incorrect, the file does not exist, or the Firebird client library cannot be found/loaded.","error":"(fdb.fbcore.DatabaseError) ('Error while connecting to database:\\n- SQLCODE: -902\\n- I/O error during \"CreateFile (open)\" operation for file \"D:/.../mydb.FDB\"\\n- Error while trying to open file\\n- The system cannot find the path specified. '"},{"fix":"Remove all references to `sqlalchemy.ext.baked`. Rewrite queries using the standard SQLAlchemy 2.0 `select()` construct, which has built-in caching.","cause":"You are attempting to use the `baked` query extension, which was removed in SQLAlchemy 2.0. This error occurs if you upgraded SQLAlchemy while `sqlalchemy-firebird` is installed.","error":"AttributeError: module 'sqlalchemy.ext.baked' has no attribute 'bakery'"}]}