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("select * from table")
row = result.fetchone()
return

Where above, the ResultProxy 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 ResultProxy 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()

kinterbasdb¶

The most common way to connect to a Firebird engine is implemented by kinterbasdb, currently maintained directly by the Firebird people.

The connection URL is of the form firebird[+kinterbasdb]://user:password@host:port/path/to/db[?key=value&key=value...].

Kinterbasedb backend specific keyword arguments are:

• type_conv - select the kind of mapping done on the types: by default SQLAlchemy uses 200 with Unicode, datetime and decimal support (see details).

• concurrency_level - set the backend policy with regards to threading issues: by default SQLAlchemy uses policy 1 (see details).

• 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 ResultProxy 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 execution_options():

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