Release: 1.4.54 | Release Date: September 5, 2024

# SQLAlchemy 1.4 Documentation

# Firebird

Support for the Firebird database.

The following table summarizes current support levels for database release versions.

## DBAPI Support

The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.

- fdb

- kinterbasdb

Note

The Firebird dialect within SQLAlchemy is not currently supported. It is not tested within continuous integration and is likely to have many issues and caveats not currently handled. Consider using the external dialect instead.

Deprecated since version 1.4: The internal Firebird dialect is deprecated and will be removed in a future version. Use the external dialect.

## Firebird Dialects

Firebird offers two distinct dialects (not to be confused with a SQLAlchemy `Dialect`):

dialect 1

  This is the old syntax and behaviour, inherited from Interbase pre-6.0.

dialect 3

  This is the newer and supported syntax, introduced in Interbase 6.0.

The SQLAlchemy Firebird dialect detects these versions and adjusts its representation of SQL accordingly. However, support for dialect 1 is not well tested and probably has incompatibilities.

## Locking Behavior

Firebird locks tables aggressively. For this reason, a DROP TABLE may hang until other transactions are released. SQLAlchemy does its best to release transactions as quickly as possible. The most common cause of hanging transactions is a non-fully consumed result set, i.e.:

    result = engine.execute(text("select * from table"))
    row = result.fetchone()
    return

Where above, the `CursorResult` has not been fully consumed. The connection will be returned to the pool and the transactional state rolled back once the Python garbage collector reclaims the objects which hold onto the connection, which often occurs asynchronously. The above use case can be alleviated by calling `first()` on the `CursorResult` which will fetch the first row and immediately close all remaining cursor/connection resources.

## RETURNING support

Firebird 2.0 supports returning a result set from inserts, and 2.1 extends that to deletes and updates. This is generically exposed by the SQLAlchemy `returning()` method, such as:

    # INSERT..RETURNING
    result = table.insert().returning(table.c.col1, table.c.col2).\
                   values(name='foo')
    print(result.fetchall())

    # UPDATE..RETURNING
    raises = empl.update().returning(empl.c.id, empl.c.salary).\
                  where(empl.c.sales>100).\
                  values(dict(salary=empl.c.salary * 1.1))
    print(raises.fetchall())

## fdb

Support for the Firebird database via the fdb driver.

fdb is a kinterbasdb compatible DBAPI for Firebird.

Changed in version 0.9: - The fdb dialect is now the default dialect under the `firebird://` URL space, as `fdb` is now the official Python driver for Firebird.

### DBAPI

Documentation and download information (if applicable) for fdb is available at: https://pypi.org/project/fdb/

### Connecting

Connect String:

    firebird+fdb://user:password@host:port/path/to/db[?key=value&key=value...]

### Arguments

The `fdb` dialect is based on the `sqlalchemy.dialects.firebird.kinterbasdb` dialect, however does not accept every argument that Kinterbasdb does.

- `enable_rowcount` - True by default, setting this to False disables the usage of “cursor.rowcount” with the Kinterbasdb dialect, which SQLAlchemy ordinarily calls upon automatically after any UPDATE or DELETE statement. When disabled, SQLAlchemy’s CursorResult will return -1 for result.rowcount. The rationale here is that Kinterbasdb requires a second round trip to the database when .rowcount is called - since SQLA’s resultproxy automatically closes the cursor after a non-result-returning statement, rowcount must be called, if at all, before the result object is returned. Additionally, cursor.rowcount may not return correct results with older versions of Firebird, and setting this flag to False will also cause the SQLAlchemy ORM to ignore its usage. The behavior can also be controlled on a per-execution basis using the `enable_rowcount` option with `Connection.execution_options()`:

      conn = engine.connect().execution_options(enable_rowcount=True)
      r = conn.execute(stmt)
      print(r.rowcount)

- `retaining` - False by default. Setting this to True will pass the `retaining=True` keyword argument to the `.commit()` and `.rollback()` methods of the DBAPI connection, which can improve performance in some situations, but apparently with significant caveats. Please read the fdb and/or kinterbasdb DBAPI documentation in order to understand the implications of this flag.

  Changed in version 0.9.0: - the `retaining` flag defaults to `False`. In 0.8 it defaulted to `True`.

  See also

  https://pythonhosted.org/fdb/usage-guide.html#retaining-transactions - information on the “retaining” flag.

## kinterbasdb

Support for the Firebird database via the kinterbasdb driver.

### DBAPI

Documentation and download information (if applicable) for kinterbasdb is available at: https://firebirdsql.org/index.php?op=devel&sub=python

### Connecting

Connect String:

    firebird+kinterbasdb://user:password@host:port/path/to/db[?key=value&key=value...]

### Arguments

The Kinterbasdb backend accepts the `enable_rowcount` and `retaining` arguments accepted by the `sqlalchemy.dialects.firebird.fdb` dialect. In addition, it also accepts the following:

- `type_conv` - select the kind of mapping done on the types: by default SQLAlchemy uses 200 with Unicode, datetime and decimal support. See the linked documents below for further information.

- `concurrency_level` - set the backend policy with regards to threading issues: by default SQLAlchemy uses policy 1. See the linked documents below for further information.

See also

https://sourceforge.net/projects/kinterbasdb

https://kinterbasdb.sourceforge.net/dist_docs/usage.html#adv_param_conv_dynamic_type_translation

https://kinterbasdb.sourceforge.net/dist_docs/usage.html#special_issue_concurrency