firebirdsql

1.4.5 verified Fri May 01 auth: no python

Python bindings for Firebird RDBMS. Current version 1.4.5. Release cadence is irregular, with maintenance updates as needed.

pip install firebirdsql

Common errors

error TypeError: connect() got an unexpected keyword argument 'dsn' ↓

cause Attempting to pass a DSN string directly to connect(), which does not support a single 'dsn' parameter.

fix

Use individual parameters: connect(host='...', database='...', user='...', password='...')

error ArgumentError: Incorrect parameter count in the command ↓

cause Using %s or :named placeholders instead of ? positional placeholders for SQL parameters.

fix

Replace placeholders with ?: cur.execute('SELECT * FROM users WHERE id = ?', (user_id,))

error ModuleNotFoundError: No module named 'firebirdsql' after pip install ↓

cause Package name is 'firebirdsql', not 'firebird' or 'fdb'. Also ensure you are using the correct Python environment.

fix

Install with: pip install firebirdsql

Warnings

breaking Python 3.12+ support requires version >= 1.4.0. Older versions fail on import due to removed modules. If you are on Python 3.12, upgrade to 1.4.0 or later. ↓

fix Upgrade: pip install --upgrade firebirdsql

gotcha Connection strings (DSN) format differs from other databases. The library expects host, database, user, password as separate arguments, not a single DSN string. Using a DSN string will raise TypeError. ↓

fix Use named parameters: connect(host='...', database='...', user='...', password='...')

gotcha Parameter style: the library uses format parameter style (e.g., ?, ?) for positional parameters, not pyformat (%s) or named (:name). Using %s will produce wrong results or errors. ↓

fix Use ? placeholders: cur.execute('SELECT * FROM table WHERE id = ?', (id,))

deprecated Charset handling: setting charset via connect parameter is deprecated in favor of encoding in the connection string in newer Firebird versions. Check your Firebird version. ↓

fix Use 'lc_ctype' parameter instead of 'charset': connect(..., lc_ctype='UTF8')

Imports

connect
wrong
```
import firebirdsql; firebirdsql.connect()
```
correct
```
from firebirdsql import connect
```
Old pattern still works but is not recommended; the function is also available as firebirdsql.connect if you import the module directly.

Quickstart

Connect to a Firebird database and execute a simple query.

import os
from firebirdsql import connect

# Use environment variables for credentials
host = os.environ.get('FIREBIRD_HOST', 'localhost')
database = os.environ.get('FIREBIRD_DATABASE', '/path/to/database.fdb')
user = os.environ.get('FIREBIRD_USER', 'sysdba')
password = os.environ.get('FIREBIRD_PASSWORD', 'masterkey')

conn = connect(host=host, database=database, user=user, password=password)
cur = conn.cursor()
cur.execute('SELECT 1 FROM RDB$DATABASE')
print(cur.fetchone())
conn.close()