Firebird Database Driver (fdb)

Common errors

• fdb.fbcore.FdbError: ('Error loading plugin FBA_AUTH', -902, 335544451)

  cause The Firebird client library is either not installed, not discoverable in the system's library paths, or is an incompatible version for your Firebird server.
  fix Install the correct Firebird client library for your OS/architecture. Ensure the library's directory is in your system's PATH (Windows) or LD_LIBRARY_PATH (Linux) or other relevant linker paths.

• fdb.fbcore.FdbError: database connection is not available

  cause The Firebird server is not running, is inaccessible (e.g., firewall blocking port 3050), or the database file specified in the DSN does not exist or is corrupted.
  fix Verify that the Firebird server service is running. Check your firewall settings. Confirm the database file path in your DSN is correct and the file exists on the server machine.

• fdb.fbcore.FdbError: no user name for connection

  cause The `user` or `password` parameters were omitted or incorrect in the `fdb.connect()` call.
  fix Always provide valid `user` and `password` arguments to `fdb.connect()`. Common defaults are `user='sysdba', password='masterkey'` (case-sensitive) for initial setup, but these should be changed for production.

Warnings

• gotcha The `fdb` library requires the native Firebird client library (e.g., `fbclient.dll` on Windows, `libfbclient.so` on Linux/macOS) to be installed and discoverable by your system's dynamic linker (e.g., in PATH on Windows, LD_LIBRARY_PATH on Linux, or standard system library paths). The Python package itself does not bundle this dependency.
  Fix: Download and install the appropriate Firebird client package for your operating system and architecture from the official FirebirdSQL website. Ensure its installation directory is added to your system's dynamic linker search paths.
• gotcha While `fdb` is actively maintained for Python compatibility (e.g., up to Python 3.13), its PyPI description refers to it as a 'Legacy Python driver for Firebird 2.5'. Users connecting to modern Firebird server versions (4.0, 5.0 and above) might encounter specific features or data types that are not fully supported or require workarounds. Always test thoroughly with your specific Firebird server version.
  Fix: Consult the FirebirdSQL documentation for specific server versions and cross-reference with `fdb` capabilities. For critical applications, consider thoroughly testing all database interactions or exploring alternative drivers if available for newer Firebird versions.
• gotcha Firebird database names (DSN) and connection parameters are case-sensitive on some operating systems and depend on how the database was created. Incorrect case or path separators can lead to connection failures.
  Fix: Double-check your database path, especially on Linux/Unix systems. Ensure `user` and `password` match exactly. For the DSN, `hostname:/path/to/database.fdb` is a common format; ensure the path is correct and accessible by the Firebird server.

Install

• pip install fdb Install latest version

Imports

• fdb

  import fdb

  The main module for accessing connection and error classes.
• fdb.Error

  import fdb
  try:
      # ...
  except fdb.Error as e:
      print(f"Database error: {e}")

  The base exception class for DB-API errors.
• fdb.connect

  import fdb
  conn = fdb.connect(...)

Quickstart

This quickstart demonstrates how to establish a connection to a Firebird database, execute a simple query to list user-defined tables, and fetch the results using the `fdb` driver. It includes basic error handling and uses environment variables for sensitive connection details, which should be replaced with actual values or more secure methods in production.

import fdb
import os

# Ensure the Firebird client library (fbclient.dll/.so) is installed and discoverable.
# Replace with your Firebird database path and credentials.
DB_DSN = os.environ.get('FDB_DSN', 'localhost:/opt/firebird/data/test.fdb')
DB_USER = os.environ.get('FDB_USER', 'sysdba')
DB_PASSWORD = os.environ.get('FDB_PASSWORD', 'masterkey')

try:
    # Establish a connection to the Firebird database
    con = fdb.connect(dsn=DB_DSN,
                      user=DB_USER, 
                      password=DB_PASSWORD)
    print("Successfully connected to Firebird database.")

    # Create a cursor object
    cur = con.cursor()

    # Execute a SQL query
    cur.execute("SELECT RDB$RELATION_NAME FROM RDB$RELATIONS WHERE RDB$SYSTEM_FLAG = 0")

    # Fetch and print results
    print("\nUser-defined tables:")
    for row in cur:
        print(f"- {row[0].strip()}") # RDB$RELATION_NAME is CHAR, needs stripping

    # Close the cursor and connection
    cur.close()
    con.close()
    print("\nConnection closed.")

except fdb.Error as e:
    print(f"Failed to connect or query Firebird database: {e}")
    print("Please ensure Firebird server is running, the client library is installed,")
    print("and the DSN/credentials are correct.")