FDB Reference¶

PyDB API 2.0 globals¶

apilevel

String constant stating the supported DB API level (2.0).

threadsafety

Integer constant stating the level of thread safety the interface supports. Curretly 1 = Threads may share the module, but not connections.

paramstyle

String constant stating the type of parameter marker formatting expected by the interface. ‘qmark’ = Question mark style, e.g. ‘…WHERE name=?’

Constants for work with driver hooks¶

• HOOK_API_LOADED

• HOOK_DATABASE_ATTACHED

• HOOK_DATABASE_ATTACH_REQUEST

• HOOK_DATABASE_DETACH_REQUEST

• HOOK_DATABASE_CLOSED

• HOOK_SERVICE_ATTACHED

Helper constants for work with Cursor.description content¶

• DESCRIPTION_NAME

• DESCRIPTION_TYPE_CODE

• DESCRIPTION_DISPLAY_SIZE

• DESCRIPTION_INTERNAL_SIZE

• DESCRIPTION_PRECISION

• DESCRIPTION_SCALE

• DESCRIPTION_NULL_OK

Helper Transaction Parameter Block (TPB) constants¶

ISOLATION_LEVEL_READ_COMMITED_LEGACY

R/W WAIT READ COMMITTED NO RECORD VERSION transaction.

ISOLATION_LEVEL_READ_COMMITED

R/W WAIT READ COMMITTED RECORD VERSION transaction.

ISOLATION_LEVEL_REPEATABLE_READ

Same as ISOLATION_LEVEL_SNAPSHOT.

ISOLATION_LEVEL_SNAPSHOT

R/W WAIT SNAPSHOT transaction.

ISOLATION_LEVEL_SERIALIZABLE

R/W WAIT SERIALIZABLE transaction.

ISOLATION_LEVEL_SNAPSHOT_TABLE_STABILITY

Same as ISOLATION_LEVEL_SERIALIZABLE.

ISOLATION_LEVEL_READ_COMMITED_RO

R/O WAIT READ COMMITTED RECORD VERSION transaction.

MAX_BLOB_SEGMENT_SIZE

charset_map

Python dictionary that maps Firebird character set names (key) to Python character sets (value).

ODS version numbers introduced by Firebird engine version¶

• ODS_FB_20

• ODS_FB_21

• ODS_FB_25

• ODS_FB_30

Translation dictionaries¶

IMPLEMENTATION_NAMES

Dictionary to map Implementation codes to names

PROVIDER_NAMES

Dictionary to map provider codes to names

DB_CLASS_NAMES

Dictionary to map database class codes to names

Firebird API constants and globals¶

connect¶

fdb.connect(dsn='', user=None, password=None, host=None, port=None, database=None, sql_dialect=3, role=None, charset=None, buffers=None, force_write=None, no_reserve=None, db_key_scope=None, isolation_level=b'\x03\t\x06\x0f\x11', connection_class=None, fb_library_name=None, no_gc=None, no_db_triggers=None, no_linger=None, utf8params=False)¶

Establish a connection to database.

Keyword Arguments

• dsn – Connection string in format [host[/port]]:database

• user (str) – User name. If not specified, fdb attempts to use ISC_USER envar.

• password (str) – User password. If not specified, fdb attempts to use ISC_PASSWORD envar.

• host (str) – Server host machine specification.

• port (int) – Port used by Firebird server.

• database (str) – Database specification (file spec. or alias)

• sql_dialect (int) – SQL Dialect for connection (1, 2 or 3).

• role (str) – User role.

• charset (str) – Character set for connection.

• buffers (int) – Page case size override for connection.

• force_writes (int) – Forced writes override for connection.

• no_reserve (int) – Page space reservation override for connection.

• db_key_scope (int) – DBKEY scope override for connection.

• isolation_level (int) – Default transaction isolation level for connection (not used) (0, 1, 2 or 3).

• connection_class (subclass of Connection) – Custom connection class

• fb_library_name (str) – Full path to Firebird client library. See load_api() for details.

• no_gc (int) – No Garbage Collection flag.

• no_db_triggers (int) – No database triggers flag (FB 2.1).

• no_linger (int) – No linger flag (FB3).

• utf8params (bool) – Notify server that database specification and other string parameters are in UTF-8.

Returns

attached database.

Return type

Connection

Raises

• fdb.ProgrammingError – For bad parameter values.

• fdb.DatabaseError – When connection cannot be established.

Important

You may specify the database using either dns or database (with optional host), but not both.

Examples

con = fdb.connect(dsn='host:/path/database.fdb', user='sysdba',
                  password='pass', charset='UTF8')
con = fdb.connect(host='myhost', database='/path/database.fdb',
                  user='sysdba', password='pass', charset='UTF8')

Hooks:

Event HOOK_DATABASE_ATTACH_REQUEST: Executed after all parameters are preprocessed and before Connection is created. Hook must have signature: hook_func(dsn, dpb) where dpb is ParameterBuffer instance.

Hook may return Connection (or subclass) instance or None. First instance returned by any hook will become the return value of this function and other hooks are not called.

Event HOOK_DATABASE_ATTACHED: Executed before Connection (or subclass) instance is returned. Hook must have signature: hook_func(connection). Any value returned by hook is ignored.

create_database¶

fdb.create_database(sql='', sql_dialect=3, dsn='', user=None, password=None, host=None, port=None, database=None, page_size=None, length=None, charset=None, files=None, connection_class=None, fb_library_name=None)¶

Creates a new database. Parameters could be specified either by supplied “CREATE DATABASE” statement, or set of database parameters.

Keyword Arguments

• sql (str) – “CREATE DATABASE” statement.

• sql_dialect (int) – SQL Dialect for newly created database (1 or 3).

• dsn (str) – Connection string in format [host[/port]]:database

• user (str) – User name. If not specified, fdb attempts to use ISC_USER envar.

• password (str) – User password. If not specified, fdb attempts to use ISC_PASSWORD envar.

• host (str) – Server host machine specification.

• port (int) – Port used by Firebird server.

• database (str) – Database specification (file spec. or alias)

• page_size (int) – Database page size.

• length (int) – Database size in pages.

• charset (str) – Character set for connection.

• files (str) – Specification of secondary database files.

• connection_class (subclass of Connection) – Custom connection class

• fb_library_name (str) – Full path to Firebird client library. See load_api() for details.

Returns

the newly created database.

Return type

Connection

Raises

• fdb.ProgrammingError – For bad parameter values.

• fdb.DatabaseError – When database creation fails.

Example

con = fdb.create_database("create database '/temp/db.fdb' user 'sysdba' password 'pass'")
con = fdb.create_database(dsn='/temp/db.fdb',user='sysdba',password='pass',page_size=8192)

Hooks:

Event` HOOK_DATABASE_ATTACHED`: Executed before Connection (or subclass) instance is returned. Hook must have signature: hook_func(connection). Any value returned by hook is ignored.

load_api¶

fdb.load_api(fb_library_name=None)¶

Initializes bindings to Firebird Client Library unless they are already initialized. Called automatically by fdb.connect() and fdb.create_database().

Parameters

• fb_library_name (str) – (optional) Path to Firebird Client Library.

• it's not specified, FDB does its best to locate appropriate client library. (When) –

Returns

fbclient_API instance.

Hooks:

Event HOOK_API_LOADED: Executed after api is initialized. Hook routine must have signature: hook_func(api). Any value returned by hook is ignored.

hook-related functions¶

fdb.add_hook(hook_type, func)¶

Instals hook function for specified hook_type.

Parameters

• hook_type (int) – One from HOOK_* constants

• func (callable) – Hook routine to be installed

Important

Routine must have a signature required for given hook type. However it’s not checked when hook is installed, and any issue will lead to run-time error when hook routine is executed.

fdb.remove_hook(hook_type, func)¶

Uninstalls previously installed hook function for specified hook_type.

Parameters

• hook_type (int) – One from HOOK_* constants

• func (callable) – Hook routine to be uninstalled

If hook routine wasn’t previously installed, it does nothing.

fdb.get_hooks(hook_type)¶

Returns list of installed hook routines for specified hook_type.

Parameters

hook_type (int) – One from HOOK_* constants

Returns

List of installed hook routines.

fdb.is_dead_proxy(obj)¶

Return True if object is a dead weakref.proxy().

Connection¶

class fdb.Connection(db_handle, dpb=None, sql_dialect=3, charset=None, isolation_level=b'x03tx06x0fx11')¶

Represents a connection between the database client (the Python process) and the database server.

Important

DO NOT create instances of this class directly! Use only connect() or create_database() to get Connection instances.

Parameters

db_handle – Database handle provided by factory function.

Keyword Arguments

• dpb – Database Parameter Block associated with database handle.

• sql_dialect (int) – SQL Dialect associated with database handle.

• charset (str) – Character set associated with database handle.

• isolation_level (bytes) – Default TPB

exception DataError¶

Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception DatabaseError¶

Exception raised for errors that are related to the database.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception Error¶

Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single ‘except’ statement. Warnings are not considered errors and thus should not use this class as base.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception IntegrityError¶

Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception InterfaceError¶

Exception raised for errors that are related to the database interface rather than the database itself.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception InternalError¶

Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception NotSupportedError¶

Exception raised in case a method or database API was used which is not supported by the database

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception OperationalError¶

Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception ProgrammingError¶

Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

exception Warning¶

Base class for warning categories.

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args¶

begin(tpb=None)¶

Starts a transaction explicitly. Operates on main_transaction. See Transaction.begin() for details.

Keyword Arguments

tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – Transaction Parameter Buffer for newly started transaction. If not specified, default_tpb is used.

close()¶

Close the connection now (rather than whenever __del__ is called). The connection will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the connection. The same applies to all cursor and transaction objects trying to use the connection.

Also closes all EventConduit, Cursor and Transaction instances associated with this connection.

Raises

fdb.ProgrammingError – When connection is a member of a ConnectionGroup.

Hooks:

Event HOOK_DATABASE_DETACH_REQUEST: Executed before connection is closed. Hook must have signature: hook_func(connection). If any hook function returns True, connection is not closed.

Event HOOK_DATABASE_CLOSED: Executed after connection is closed. Hook must have signature: hook_func(connection). Any value returned by hook is ignored.

commit(retaining=False)¶

Commit pending transaction to the database. Operates on main_transaction. See Transaction.commit() for details.

Keyword Arguments

retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled.

Raises

fdb.ProgrammingError – If Connection is closed.

cursor()¶

Return a new Cursor instance using the connection associated with main_transaction. See Transaction.cursor() for details.

Raises

fdb.ProgrammingError – If Connection is closed.

database_info(info_code, result_type, page_number=None)¶

Wraps the Firebird C API function isc_database_info.

For documentation, see the IB 6 API Guide section entitled “Requesting information about an attachment” (p. 51).

Note that this method is a VERY THIN wrapper around the FB C API function isc_database_info. This method does NOT attempt to interpret its results except with regard to whether they are a string or an integer.

For example, requesting isc_info_user_names will return a string containing a raw succession of length-name pairs. A thicker wrapper might interpret those raw results and return a Python tuple, but it would need to handle a multitude of special cases in order to cover all possible isc_info_* items.

Parameters

• info_code (int) – One of the isc_info_* constants.

• result_type (str) – Must be either ‘b’ if you expect a binary string result, or ‘i’ if you expect an integer result.

Keyword Arguments

page_number (int) – Page number for fb_info_page_contents info code.

Raises

• fdb.DatabaseError – When error is returned from server.

• fdb.OperationalError – When returned information is bigger than SHRT_MAX.

• fdb.InternalError – On unexpected processing condition.

• ValueError – On illegal result_type value.

See also

Extracting data with the database_info function is rather clumsy. See db_info() for higher-level means of accessing the same information.

Note

Some of the information available through this method would be more easily retrieved with the Services API (see submodule fdb.services).

db_info(request)¶

Higher-level convenience wrapper around the database_info() method that parses the output of database_info into Python-friendly objects instead of returning raw binary buffers in the case of complex result types.

Parameters

request – Single fdb.isc_info_* info request code or a sequence of such codes.

Returns

Mapping of (info request code -> result).

Return type

dist

Raises

• ValueError – When requested code is not recognized.

• fdb.OperationalError – On unexpected processing condition.

drop_database()¶

Drops the database to which this connection is attached.

Unlike plain file deletion, this method behaves responsibly, in that it removes shadow files and other ancillary files for this database.

Raises

• fdb.ProgrammingError – When connection is a member of a ConnectionGroup.

• fdb.DatabaseError – When error is returned from server.

event_conduit(event_names)¶

Creates a conduit through which database event notifications will flow into the Python program.

Parameters

event_names (list of str) – A sequence of string event names.

Returns

Return type

EventConduit

execute_immediate(sql)¶

Executes a statement in context of main_transaction without caching its prepared form.

Automatically starts transaction if it’s not already started.

Parameters

sql (str) – SQL statement to execute.

Important

The statement must not be of a type that returns a result set. In most cases (especially cases in which the same statement – perhaps a parameterized statement – is executed repeatedly), it is better to create a cursor using the connection’s cursor method, then execute the statement using one of the cursor’s execute methods.

Raises

• fdb.ProgrammingError – When connection is closed.

• fdb.DatabaseError – When error is returned from server.

get_active_transaction_count()¶

Return count of currently active transactions.

get_active_transaction_ids()¶

Return list of transaction IDs for all currently active transactions.

get_page_contents(page_number)¶

Return content of specified database page as binary string.

Parameters

page_number (int) – Page sequence number.

get_table_access_stats()¶

Return current stats for access to tables.

Returns

of _TableAccessStats instances.

Return type

list

isreadonly()¶

Returns True if database is read-only.

rollback(retaining=False, savepoint=None)¶

Causes the the database to roll back to the start of pending transaction. Operates on main_transaction. See Transaction.rollback() for details.

Keyword Arguments

• retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled.

• savepoint (str) – Causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely.

Raises

fdb.ProgrammingError – If Connection is closed.

savepoint(name)¶

Establishes a named SAVEPOINT for current transaction. Operates on main_transaction. See Transaction.savepoint() for details.

Parameters

name (str) – Name for savepoint.

Raises

fdb.ProgrammingError – If Connection is closed.

Example

con.savepoint('BEGINNING_OF_SOME_SUBTASK')
...
con.rollback(savepoint='BEGINNING_OF_SOME_SUBTASK')

trans(default_tpb=None)¶

Creates a new Transaction that operates within the context of this connection. Cursors can be created within that Transaction via its cursor() method.

Keyword Arguments

default_tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – Transaction Parameter Block for newly created Transaction. If not specified, default_tpb is used.

Raises

fdb.ProgrammingError – If Connection is closed.

trans_info(request)¶

Pythonic wrapper around transaction_info() call. Operates on main_transaction.

See also

Transaction.trans_info() for details.

transaction_info(info_code, result_type)¶

Returns information about active transaction. Thin wrapper around Firebird API isc_transaction_info call. Operates on main_transaction.

See also

Transaction.transaction_info() for details.

property attachment_id¶

(R/O) Internal ID (server-side) for connection.

Type

int

property charset¶

(R/O) Connection Character set name.

Type

str

property closed¶

(R/O) True if connection is closed.

Type

bool

property creation_date¶

(R/O) Database creation date & time.

Type

datetime.datetime

property current_memory¶

(R/O) Amount of server memory (in bytes) currently in use.

Type

int

property database_name¶

(R/O) Database name (filename or alias).

Type

str

property database_sql_dialect¶

(R/O) SQL dialect of attached database.

Type

int

property db_class_id¶

(R/O Database class ID

Type

int

property default_tpb¶

(R/W) Deafult Transaction Parameter Block used for all newly started transactions.

Type

bytes

property engine_version¶

(R/O) Firebird version number of connected server. Only major.minor version.

Type

float

property firebird_version¶

(R/O) Version string returned by server for this connection. This version string contains Firebird engine version number, i.e. version that DOES NOT takes into account inherited IB version number. For example it’s ‘LI-V2.5.2.26540 Firebird 2.5’ for Firebird 2.5.2

Type

str

property forced_writes¶

(R/O) Mode in which database writes are performed (True=sync, False=async).

Type

bool

property group¶

(R/O) ConnectionGroup this Connection belongs to, or None.

property implementation_id¶

(R/O) Server implementation ID

Type

int

property io_stats¶

(R/O) Dictionary with I/O stats (reads,writes,fetches,marks) Keys are isc_info_reads, isc_info_writes, isc_info_fetches and isc_info_marks constants.

Type

dict

property main_transaction¶

Main transaction for this connection. Connection methods begin(), savepoint(), commit() and rollback() are delegated to this transaction object.

Type

Transaction

property max_memory¶

(R/O) Maximum amount of memory (in bytes) used at one time since the first process attached to the database.

Type

int

property monitor¶

Database monitoring object.

Type

Monitor

property next_transaction¶

(R/O) ID of Next Transaction.

Type

int

property oat¶

(R/O) ID of Oldest Active Transaction.

Type

int

property ods¶

(R/O) On-Disk Structure (ODS).

Type

float

property ods_minor_version¶

(R/O) On-Disk Structure (ODS) minor version number.

Type

int

property ods_version¶

(R/O) On-Disk Structure (ODS) major version number.

Type

int

property oit¶

(R/O) ID of Oldest Interesting Transaction.

Type

int

property ost¶

(R/O) ID of Oldest Snapshot Transaction.

Type

int

property page_cache_size¶

(R/O) Size of page cache in pages.

Type

int

property page_size¶

(R/O) Database page size in bytes.

Type

int

property pages_allocated¶

(R/O) Number of database pages allocated.

Type

int

property provider_id¶

(R/O) Server provider ID

Type

int

property query_transaction¶

Special “query” transaction for this connection. This is ReadOnly ReadCommitted transaction that could be active indefinitely without blocking garbage collection. It’s used internally to query metadata, but it’s generally useful.

Type

Transaction

property schema¶

Database metadata object.

Type

Schema

property server_version¶

(R/O) Version string returned by server for this connection. This version string contains InterBase-friendly engine version number, i.e. version that takes into account inherited IB version number. For example it’s ‘LI-V6.3.2.26540 Firebird 2.5’ for Firebird 2.5.2

Type

str

property site_name¶

(R/O) Database site name.

Type

str

property space_reservation¶

(R/O) When True 20% page space is reserved for holding backup versions of modified records.

Type

bool

property sql_dialect¶

(R/O) SQL dialect for this connection.

Type

int

property sweep_interval¶

(R/O) Sweep interval.

Type

int

property transactions¶

Instances associated with this connection.

Type

tuple of Transaction

property version¶

(R/O) Firebird version number string of connected server. Uses Firebird version numbers in form: major.minor.subrelease.build

Type

str

ConnectionWithSchema¶

class fdb.ConnectionWithSchema(db_handle, dpb=None, sql_dialect=3, charset=None, isolation_level=b'x03tx06x0fx11')¶

Connection descendant that exposes all attributes of encapsulated Schema instance directly as connection attributes, except close() and bind(), and those attributes that are already defined by Connection class.

Note

Use connection_class parametr of connect() or create_database() to create connections with direct schema interface.

See also

fdb.schema.Schema for list of methods that extend this class.

Parameters

db_handle – Database handle provided by factory function.

Keyword Arguments

• dpb – Database Parameter Block associated with database handle.

• sql_dialect (int) – SQL Dialect associated with database handle.

• charset (str) – Character set associated with database handle.

• isolation_level (bytes) – Default TPB

Cursor¶

class fdb.Cursor(connection, transaction)¶

Represents a database cursor, which is used to execute SQL statement and manage the context of a fetch operation.

Important

DO NOT create instances of this class directly! Use only Connection.cursor(), Transaction.cursor() and ConnectionGroup.cursor() to get Cursor instances that operate in desired context.

Note

Cursor is actually a high-level wrapper around PreparedStatement instance(s) that handle the actual SQL statement execution and result management.

Tip

Cursor supports the iterator protocol, yielding tuples of values like fetchone().

Important

The association between a Cursor and its Transaction and Connection is set when the Cursor is created, and cannot be changed during the lifetime of that Cursor.

Parameters

• connection (Connection) – instance this cursor should be bound to.

• transaction (Transaction) – instance this cursor should be bound to.

callproc(procname, parameters=None)¶

Call a stored database procedure with the given name.

The result of the call is available through the standard fetchXXX() methods.

Parameters

procname (str) – Stored procedure name.

Keyword Arguments

parameters (iterable) – Sequence of parameters. Must contain one entry for each argument that the procedure expects.

Returns

parameters as required by Python DB API 2.0 Spec.

Raises

• TypeError – When parameters is not List or Tuple.

• fdb.ProgrammingError – When more parameters than expected are suplied.

• fdb.DatabaseError – When error is returned by server.

close()¶

Close the cursor now (rather than whenever __del__ is called).

Closes any currently open PreparedStatement. However, the cursor is still bound to Connection and Transaction, so it could be still used to execute SQL statements.

Warning

FDB’s implementation of Cursor somewhat violates the Python DB API 2.0, which requires that cursor will be unusable after call to close; and an Error (or subclass) exception should be raised if any operation is attempted with the cursor.

If you’ll take advantage of this anomaly, your code would be less portable to other Python DB API 2.0 compliant drivers.

execute(operation, parameters=None)¶

Prepare and execute a database operation (query or command).

Note

Execution is handled by PreparedStatement that is either supplied as operation parameter, or created internally when operation is a string. Internally created PreparedStatements are stored in cache for later reuse, when the same operation string is used again.

Returns

self so call to execute could be used as iterator.

Parameters

operation (str PreparedStatement) – SQL command specification.

Keyword Arguments

parameters (list or tuple) – Sequence of parameters. Must contain one entry for each argument that the operation expects.

Raises

• ValueError – When operation PreparedStatement belongs to different Cursor instance.

• TypeError – When parameters is not List or Tuple.

• fdb.ProgrammingError – When more parameters than expected are suplied.

• fdb.DatabaseError – When error is returned by server.

executemany(operation, seq_of_parameters)¶

Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters.

Note

This function simply calls execute() in a loop, feeding it with parameters from seq_of_parameters. Because execute caches PreparedStatements, calling executemany is equally efective as direct use of prepared statement and calling execute in a loop directly in application.

Returns

self so call to executemany could be used as iterator.

Parameters

• operation (str ot PreparedStatement) – SQL command specification.

• seq_of_parameters (list or tuple) – Sequence of sequences of parameters. Must contain one sequence of parameters for each execution that has one entry for each argument that the operation expects.

Raises

• ValueError – When operation PreparedStatement belongs to different Cursor instance.

• TypeError – When seq_of_parameters is not List or Tuple.

• fdb.ProgrammingError – When there are more parameters in any sequence than expected.

• fdb.DatabaseError – When error is returned by server.

fetchall()¶

Fetch all (remaining) rows of a query result.

Returns

List of tuples, where each tuple is one row of returned values.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

fetchallmap()¶

Fetch all (remaining) rows of a query result like fetchall(), except that it returns a list of mappings of field name to field value, rather than a list of tuples.

Returns

List of fbcore._RowMapping instances, one such instance for each row.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

fetchmany(size=1)¶

Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available. The number of rows to fetch per call is specified by the parameter. If it is not given, the cursor’s arraysize determines the number of rows to be fetched. The method does try to fetch as many rows as indicated by the size parameter. If this is not possible due to the specified number of rows not being available, fewer rows may be returned.

Keyword Arguments

size (int) – Max. number of rows to fetch.

Returns

List of tuples, where each tuple is one row of returned values.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

fetchmanymap(size=1)¶

Fetch the next set of rows of a query result, like fetchmany(), except that it returns a list of mappings of field name to field value, rather than a list of tuples.

Keyword Arguments

size (int) – Max. number of rows to fetch.

Returns

List of fbcore._RowMapping instances, one such instance for each row.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

fetchone()¶

Fetch the next row of a query result set.

Returns

Tuple of returned values, or None when no more data is available.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

fetchonemap()¶

Fetch the next row of a query result set like fetchone(), except that it returns a mapping of field name to field value, rather than a tuple.

Returns

fbcore._RowMapping of returned values, or None when no more data is available.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When underlying PreparedStatement is closed, statement was not yet executed, or unknown status is returned by fetch operation.

iter()¶

Equivalent to the fetchall(), except that it returns iterator rather than materialized list.

Returns

that yields tuple of values like fetchone().

Return type

iterator

itermap()¶

Equivalent to the fetchallmap(), except that it returns iterator rather than materialized list.

Returns

Iterator that yields fbcore._RowMapping instance like fetchonemap().

next()¶

Return the next item from the container. Part of iterator protocol.

Raises

StopIteration – If there are no further items.

prep(operation)¶

Create prepared statement for repeated execution.

Note

Returned PreparedStatement instance is bound to its Cursor instance via strong reference, and is not stored in Cursor’s internal cache of prepared statements.

Parameters

operation (str) – SQL command

Returns

PreparedStatement

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.InternalError – On unexpected processing condition.

set_stream_blob(blob_name)¶

Specify a BLOB column(s) to work in stream mode instead classic, materialized mode for already executed statement.

Parameters

blob_name (str or list) – Single name or sequence of column names. Name must be in format as it’s stored in database (refer to description for real value).

Important

BLOB name is permanently added to the list of BLOBs handled as stream BLOBs by current PreparedStatement instance. If instance is stored in internal cache of prepared statements, the same command executed repeatedly will retain this setting.

Parameters

blob_name (str) – Name of BLOB column.

Raises

fdb.ProgrammingError –

set_stream_blob_treshold(size)¶

Specify max. blob size for materialized blobs. If size of particular blob exceeds this threshold, returns streamed blob (BlobReader) instead string. Value -1 means no size limit (use at your own risk). Default value is 64K

Parameters

size (int) – Max. size for materialized blob.

setinputsizes(sizes)¶

Required by Python DB API 2.0, but pointless for Firebird, so it does nothing.

setoutputsize(size, column=None)¶

Required by Python DB API 2.0, but pointless for Firebird, so it does nothing.

arraysize = 1¶

(R/W) As required by the Python DB API 2.0 spec, the value of this attribute is observed with respect to the fetchmany() method. However, changing the value of this attribute does not make any difference in fetch efficiency because the database engine only supports fetching a single row at a time.

Type

int

property connection¶

(R/O) PEP 249 Extension. Reference to the Connection object on which the cursor was created.

Type

Connection

property description¶

(R/O) List of tuples (with 7-item). Each of these tuples contains information describing one result column: (name, type_code, display_size,internal_size, precision, scale, null_ok)

If cursor doesn’t have a prepared statement, the value is None.

Type

list

property name¶

(R/O) Name for the SQL cursor. This property can be ignored entirely if you don’t need to use it.

Type

str

property plan¶

(R/O) A string representation of the execution plan for last executed statement generated by the database engine’s optimizer. None if no statement was executed.

Type

str

property rowcount¶

(R/O) Specifies the number of rows that the last executeXXX() produced (for DQL statements like select) or affected (for DML statements like update or insert ).

The attribute is -1 in case no executeXXX() has been performed on the cursor or the rowcount of the last operation is not determinable by the interface.

Note

The database engine’s own support for the determination of “rows affected”/”rows selected” is quirky. The database engine only supports the determination of rowcount for INSERT, UPDATE, DELETE, and SELECT statements. When stored procedures become involved, row count figures are usually not available to the client. Determining rowcount for SELECT statements is problematic: the rowcount is reported as zero until at least one row has been fetched from the result set, and the rowcount is misreported if the result set is larger than 1302 rows. The server apparently marshals result sets internally in batches of 1302, and will misreport the rowcount for result sets larger than 1302 rows until the 1303rd row is fetched, result sets larger than 2604 rows until the 2605th row is fetched, and so on, in increments of 1302.

Type

int

property transaction¶

(R/O) Reference to the Transaction object on which the cursor was created.

Type

Transaction

Transaction¶

class fdb.Transaction(connections, default_tpb=None, default_action='commit')¶

Represents a transaction context, which is used to execute SQL statement.

Important

DO NOT create instances of this class directly! Connection and ConnectionGroup manage Transaction internally, surfacing all important methods directly in their interfaces. If you want additional transactions independent from Connection.main_transaction, use Connection.trans() method to obtain such Transaction instance.

Parameters

connections (iterable) – Sequence of (up to 16) Connection instances.

Keyword Arguments

• default_tpb (TPB instance, iterable of isc_tpb_* constants or bytestring) – Transaction Parameter Block for this transaction. If None is specified, uses ISOLATION_LEVEL_READ_COMMITED.

• default_action (str) – Action taken when active transaction is ended automatically (during close() or begin()). Accepted values: ‘commit’ or ‘rollback’

Raises

fdb.ProgrammingError – When zero or more than 16 connections are given.

begin(tpb=None)¶

Starts a transaction explicitly.

Keyword Arguments

tpb (TPB instance, iterable of isc_tpb_* constants or bytestring) – Transaction Parameter Block for newly created Transaction. If not specified, default_tpb is used.

Note

Calling this method directly is never required; a transaction will be started implicitly if necessary.

Important

If the physical transaction is unresolved when this method is called, a commit() or rollback() will be performed first, accordingly to default_action value.

Raises

• fdb.DatabaseError – When error is returned by server.

• fdb.ProgrammingError – When TPB is in usupported format, or transaction is permanently closed.

close()¶

Permanently closes the Transaction object and severs its associations with other objects (Cursor and Connection instances).

Important

If the physical transaction is unresolved when this method is called, a commit() or rollback() will be performed first, accordingly to default_action value.

commit(retaining=False)¶

Commit any pending transaction to the database.

Note

If transaction is not active, this method does nothing, because the consensus among Python DB API experts is that transactions should always be started implicitly, even if that means allowing a commit() or rollback() without an actual transaction.

Keyword Arguments

retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled.

Raises

fdb.DatabaseError – When error is returned by server as response to commit.

cursor(connection=None)¶

Creates a new Cursor that will operate in the context of this Transaction.

Keyword Arguments

connection (Connection) – Required only when Transaction is bound to multiple Connections, to specify to which Connection the returned Cursor should be bound.

Raises

fdb.ProgrammingError – When transaction operates on multiple Connections and: connection parameter is not specified, or specified connection is not among Connections this Transaction is bound to.

execute_immediate(sql)¶

Executes a statement without caching its prepared form on

all connections this transaction is bound to.

Automatically starts transaction if it’s not already started.

Parameters

sql (str) – SQL statement to execute.

Important

The statement must not be of a type that returns a result set. In most cases (especially cases in which the same statement – perhaps a parameterized statement – is executed repeatedly), it is better to create a cursor using the connection’s cursor method, then execute the statement using one of the cursor’s execute methods.

Raises

fdb.DatabaseError – When error is returned from server.

isreadonly()¶

Returns True if transaction is Read Only.

prepare()¶

Manually triggers the first phase of a two-phase commit (2PC).

Note

Direct use of this method is optional; if preparation is not triggered manually, it will be performed implicitly by commit() in a 2PC.

rollback(retaining=False, savepoint=None)¶

Rollback any pending transaction to the database.

Note

If transaction is not active, this method does nothing, because the consensus among Python DB API experts is that transactions should always be started implicitly, even if that means allowing a commit() or rollback() without an actual transaction.

Keyword Arguments

• retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled. Mutually exclusive with ‘savepoint`.

• savepoint (str) – Savepoint name. Causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely. Mutually exclusive with ‘retaining`.

Raises

• fdb.ProgrammingError – If both savepoint and retaining are specified.

• fdb.DatabaseError – When error is returned by server as response to rollback.

savepoint(name)¶

Establishes a savepoint with the specified name.

Note

If transaction is bound to multiple connections, savepoint is created on all of them.

Important

Because savepoint is created not through Firebird API (there is no such API call), but by executing SAVEPOINT <name> SQL statement, calling this method starts the transaction if it was not yet started.

Parameters

name (str) – Savepoint name.

trans_info(request)¶

Pythonic wrapper around transaction_info() call.

Parameters

request – One or more information request codes (see transaction_info() for details). Multiple codes must be passed as tuple.

Returns

Decoded response(s) for specified request code(s). When multiple requests are passed, returns a dictionary where key is the request code and value is the response from server.

transaction_info(info_code, result_type)¶

Return information about active transaction.

This is very thin wrapper around Firebird API isc_transaction_info call.

Parameters

• info_code (int) – One from the isc_info_tra_* constants.

• result_type (str) – Code for result type. Accepted values: ‘b’ for binary string or ‘i’ for integer

Raises

• fdb.ProgrammingError – If transaction is not active.

• fdb.OperationalError – When result is too large to fit into buffer of size SHRT_MAX.

• fdb.InternalError – On unexpected processing condition.

• ValueError – When illegal result type code is specified.

property active¶

(R/O) True if transaction is active.

Type

bool

property closed¶

(R/O) True if transaction is closed.

Type

bool

property cursors¶

(R/O) List of Cursor objects associated with this Transaction.

Type

list

property default_action¶

(R/W) commit or rollback, action to be taken when physical transaction has to be ended automatically. Default is commit.

Type

str

default_tpb = b'\x03\t\x06\x0f\x11'¶

(Read/Write) Transaction Parameter Block.

property isolation¶

property lock_timeout¶

(R/O) Lock timeout (seconds or -1 for unlimited).

Type

int

property oat¶

(R/O) ID of Oldest Active Transaction when this transaction started.

Type

int

property oit¶

(R/O) ID of Oldest Interesting Transaction when this transaction started.

Type

int

property ost¶

(R/O) ID of Oldest Snapshot Transaction when this transaction started.

Type

int

property transaction_id¶

(R/O) Internal ID (server-side) for transaction.

Type

int

PreparedStatement¶

class fdb.PreparedStatement(operation, cursor, internal=True)¶

Represents a prepared statement, an “inner” database cursor, which is used to manage the SQL statement execution and context of a fetch operation.

Important

DO NOT create instances of this class directly! Use only Cursor.prep() to get PreparedStatement instances.

Note

PreparedStatements are bound to Cursor instance that created them, and using them with other Cursor would report an error.

close()¶

Drops the resources associated with executed prepared statement, but keeps it prepared for another execution.

set_stream_blob(blob_spec)¶

Specify a BLOB column(s) to work in stream mode instead classic, materialized mode.

Parameters

• blob_spec (str) –

  Single name or sequence of column names. Name must be in format as it’s stored in database (refer to description for real value).

  Important

  BLOB name is permanently added to the list of BLOBs handled as stream BLOBs by this instance.

• blob_spec – Name of BLOB column.

set_stream_blob_treshold(size)¶

Specify max. blob size for materialized blobs. If size of particular blob exceeds this threshold, returns streamed blob (BlobReader) instead string. Value -1 means no size limit (use at your own risk). Default value is 64K

Parameters

size (int) – Max. size for materialized blob.

NO_FETCH_ATTEMPTED_YET = -1¶

Constant for internal use by this class. Do not change!

RESULT_SET_EXHAUSTED = 100¶

Constant for internal use by this class. Do not change!

property closed¶

(R/O) True if closed. Note that closed means that PS statement handle was closed for further fetching, releasing server resources, but wasn’t dropped, and couldbe still used for another execution.

Type

bool

cursor = None¶

Cursor instance that manages this PreparedStatement. Do not change!

property description¶

Each of these sequences contains information describing one result column - (name, type_code, display_size,internal_size, precision, scale, null_ok)

Type

Sequence of 7-item sequences

n_input_params = 0¶

The number of input parameters the statement requires. Do not change!

n_output_params = 0¶

The number of output fields the statement produces. Do not change!

property name¶

(R/O) Name for the SQL cursor. This property can be ignored entirely if you don’t need to use it.

Type

str

property plan¶

(R/O) A string representation of the execution plan generated for this statement by the database engine’s optimizer.

Type

str

property rowcount¶

(R/O) Specifies the number of rows that the last execution produced (for DQL statements like select) or affected (for DML statements like update or insert ).

The attribute is -1 in case the statement was not yet executed or the rowcount of the operation is not determinable by the interface.

Type

int

property sql¶

(R/O) SQL command this PreparedStatement executes.

Type

str

statement_type = 0¶

(integer) An integer code that can be matched against the statement type constants in the isc_info_sql_stmt_* series. Do not change!

ConnectionGroup¶

class fdb.ConnectionGroup(connections=())¶

Manager for distributed transactions, i.e. transactions that span multiple databases.

Tip

ConnectionGroup supports in operator to check membership of connections.

Parameters

connections (iterable) – Sequence of Connection instances.

See also

See add() for list of exceptions the constructor may throw.

add(con)¶

Adds active connection to the group.

Parameters

con – A Connection instance to add to this group.

Raises

• TypeError – When con is not Connection instance.

• fdb.ProgrammingError – When con is already member of this or another group, or closed. When this group has unresolved transaction or contains 16 connections.

begin(tpb=None)¶

Starts distributed transaction over member connections.

Keyword Arguments

tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – Transaction Parameter Buffer for newly started transaction. If not specified, default_tpb is used.

Raises

fdb.ProgrammingError – When group is empty or has active transaction.

clear()¶

Removes all connections from group.

Raises

fdb.ProgrammingError` When transaction is active. –

commit(retaining=False)¶

Commits distributed transaction over member connections using 2PC.

Note

If transaction is not active, this method does nothing, because the consensus among Python DB API experts is that transactions should always be started implicitly, even if that means allowing a commit() or rollback() without an actual transaction.

Keyword Arguments

retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled.

Raises

fdb.ProgrammingError – When group is empty.

contains(con)¶

Returns True if specified connection belong to this group.

Parameters

con (Connection) – Connection that should be checked for presence.

count()¶

Returns number of Connection objects that belong to this group.

cursor(connection)¶

Creates a new Cursor that will operate in the context of distributed transaction and specific Connection that belongs to this group.

Note

Automatically starts transaction if it’s not already started.

Parameters

connection (Connection) –

Raises

fdb.ProgrammingError – When group is empty or specified connection doesn’t belong to this group.

disband()¶

Forcefully deletes all connections from connection group.

Note

1. If transaction is active, it’s canceled (rollback).

2. Any error during transaction finalization doesn’t stop the disband process, however the exception catched is eventually reported.

execute_immediate(sql)¶

Executes a statement on all member connections without caching its prepared form.

Automatically starts transaction if it’s not already started.

Parameters

sql (str) – SQL statement to execute.

Important

The statement must not be of a type that returns a result set. In most cases (especially cases in which the same statement – perhaps a parameterized statement – is executed repeatedly), it is better to create a cursor using the connection’s cursor method, then execute the statement using one of the cursor’s execute methods.

Raises

fdb.DatabaseError – When error is returned from server.

members()¶

Returns list of connection objects that belong to this group.

prepare()¶

Manually triggers the first phase of a two-phase commit (2PC). Use of this method is optional; if preparation is not triggered manually, it will be performed implicitly by commit() in a 2PC.

remove(con)¶

Removes specified connection from group.

Parameters

con – A Connection instance to remove.

Raises

fdb.ProgrammingError – When con doesn’t belong to this group or transaction is active.

rollback(retaining=False, savepoint=None)¶

Rollbacks distributed transaction over member connections.

Note

If transaction is not active, this method does nothing, because the consensus among Python DB API experts is that transactions should always be started implicitly, even if that means allowing a commit() or rollback() without an actual transaction.

Keyword Arguments

• retaining (bool) – Indicates whether the transactional context of the transaction being resolved should be recycled.

• savepoint (str) – Savepoint name. Causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely. Mutually exclusive with ‘retaining`.

Raises

fdb.ProgrammingError – When group is empty.

savepoint(name)¶

Establishes a named SAVEPOINT on all member connections. See Transaction.savepoint() for details.

Parameters

name (str) – Name for savepoint.

Raises

fdb.ProgrammingError – When group is empty.

property default_tpb¶

(R/W) Deafult Transaction Parameter Block used for transactions.

Type

bytes

TransactionContext¶

class fdb.TransactionContext(transaction)¶

Context Manager that manages transaction for object passed to constructor.

Performs rollback if exception is thrown inside code block, otherwise performs commit at the end of block.

Note

Transaction acts as context manager and supports with statement directly.

Examples

with TransactionContext(my_transaction):
    cursor.execute('insert into tableA (x,y) values (?,?)',(x,y))
    cursor.execute('insert into tableB (x,y) values (?,?)',(x,y))

Parameters

transaction – Any object that supports begin(), commit() and rollback().

transaction = None¶

Transaction-like object this instance manages.

EventConduit¶

class fdb.EventConduit(db_handle, event_names)¶

Represents a conduit through which database event notifications will flow into the Python program.

Important

DO NOT create instances of this class directly! Use only Connection.event_conduit() to get EventConduit instances.

Notifications of any events are not accumulated until begin() method is called.

From the moment the begin() method is called, notifications of any events that occur will accumulate asynchronously within the conduit’s internal queue until the conduit is closed either explicitly (via the close() method) or implicitly (via garbage collection).

EventConduit implements context manager protocol to call method begin() and close() automatically.

Example

with connection.event_conduit( ('event_a', 'event_b') ) as conduit:
    events = conduit.wait()
    process_events(events)

Parameters

• db_handle – Database handle.

• event_names (list) – List of strings that represent event names.

begin()¶

Starts listening for events.

Must be called directly or through context manager interface.

close()¶

Cancels the standing request for this conduit to be notified of events.

After this method has been called, this EventConduit object is useless, and should be discarded.

flush()¶

Clear any event notifications that have accumulated in the conduit’s internal queue.

wait(timeout=None)¶

Wait for events.

Blocks the calling thread until at least one of the events occurs, or the specified timeout (if any) expires.

Keyword Arguments

timeout (int or float) – Number of seconds (use a float to indicate fractions of seconds). If not even one of the relevant events has occurred after timeout seconds, this method will unblock and return None. The default timeout is infinite.

Returns

None if the wait timed out, otherwise a dictionary that maps event_name -> event_occurrence_count.

Example

>>>conduit = connection.event_conduit( ('event_a', 'event_b') )
>>>conduit.begin()
>>>conduit.wait()
{
 'event_a': 1,
 'event_b': 0
}

In the example above event_a occurred once and event_b did not occur at all.

property closed¶

(Read Only) (boolean) True if conduit is closed.

BlobReader¶

class fdb.BlobReader(blobid, db_handle, tr_handle, is_text, charset)¶

BlobReader is a “file-like” class, so it acts much like a file instance opened in rb mode.

Important

DO NOT create instances of this class directly! BlobReader instances are returned automatically in place of output BLOB values when stream BLOB access is requested via PreparedStatement.set_stream_blob().

Tip

BlobReader supports iterator protocol, yielding lines like readline().

close()¶

Closes the Reader. Like file.close().

Raises

fdb.DatabaseError – When error is returned by server.

flush()¶

Flush the internal buffer. Like file.flush(). Does nothing as it’s pointless for reader.

get_info()¶

Return information about BLOB.

Returns

tuple with items: blob_length, segment_size, num_segments, blob_type

Return type

tuple

Meaning of individual values:

Blob_length

Total blob length in bytes

Segment_size

Size of largest segment

Num_segments

Number of segments

Blob_type

isc_bpb_type_segmented or isc_bpb_type_stream

next()¶

Return the next line from the BLOB. Part of iterator protocol.

Raises

StopIteration – If there are no further lines.

read(size=-1)¶

Read at most size bytes from the file (less if the read hits EOF before obtaining size bytes). If the size argument is negative or omitted, read all data until EOF is reached. The bytes are returned as a string object. An empty string is returned when EOF is encountered immediately. Like file.read().

Raises

fdb.ProgrammingError – When reader is closed.

Note

Performs automatic conversion to unicode for TEXT BLOBs, if used Python is v3 or connection charset is defined.

readline()¶

Read one entire line from the file. A trailing newline character is kept in the string (but may be absent when a file ends with an incomplete line). An empty string is returned when EOF is encountered immediately. Like file.readline().

Raises

fdb.ProgrammingError – When reader is closed.

Note

Performs automatic conversion to unicode for TEXT BLOBs, if used Python is v3 or connection charset is defined.

readlines(sizehint=None)¶

Read until EOF using readline() and return a list containing the lines thus read. The optional sizehint argument (if present) is ignored. Like file.readlines().

Note

Performs automatic conversion to unicode for TEXT BLOBs, if used Python is v3 or connection charset is defined.

seek(offset, whence=0)¶

Set the file’s current position, like stdio‘s fseek(). See file.seek() details.

Parameters

offset (int) – Offset from specified position.

Keyword Arguments

whence (int) – Context for offset. Accepted values: os.SEEK_SET, os.SEEK_CUR or os.SEEK_END

Raises

fdb.ProgrammingError – When reader is closed.

Warning

If BLOB was NOT CREATED as stream BLOB, this method raises DatabaseError exception. This constraint is set by Firebird.

tell()¶

Return current position in BLOB, like stdio‘s ftell() and file.tell().

property blob_charset¶

(R/O) BLOB character set

Type

str

property blob_id¶

(R/O) BLOB ID

Type

ISC_QUAD

property charset¶

(R/O) Python character set for BLOB

Type

str

property closed¶

(R/O) True is BlobReader is closed.

Type

bool

property is_text¶

(R/O) True if BLOB is a text BLOB

Type

bool

property mode¶

(R/O) File mode - always “rb”

Type

str

TPB¶

class fdb.TPB¶

Helper class for convenient and safe construction of custom Transaction Parameter Blocks.

clear()¶

copy()¶

Returns a copy of self.

render()¶

Create valid transaction parameter block according to current values of member attributes.

Returns

binary Transaction Parameter Block for FB API calls

Return type

bytes

property access_mode¶

Required access mode (isc_tpb_read or isc_tpb_write). Default: isc_tpb_write

Type

int

property isolation_level¶

Required Transaction Isolation Level. Single integer value equivalent to isc_tpb_concurrency or isc_tpb_consistency, or tuple of exactly two integer values, where the first one is isc_tpb_read_committed and second either isc_tpb_rec_version or isc_tpb_no_rec_version.

When value isc_tpb_read_committed is assigned without suboption, the isc_tpb_rec_version is assigned as default suboption.

Default: isc_tpb_concurrency

Type

int or tuple

property lock_resolution¶

Required lock resolution method. Either isc_tpb_wait or isc_tpb_nowait.

Default: isc_tpb_wait

Type

int

property lock_timeout¶

Required lock timeout or None. Default: None

Type

int

property table_reservation¶

Table reservation specification.

Default: None.

Instead of changing the value of the TableReservation object itself, you must change its elements by manipulating it as though it were a dictionary that mapped “TABLE_NAME”: (sharingMode, accessMode) For example:

tpb.table_reservation["MY_TABLE"] = (fdb.isc_tpb_protected, fdb.isc_tpb_lock_write)

Type

TableReservation

TableReservation¶

class fdb.TableReservation¶

A dictionary-like helper class that maps “TABLE_NAME”: (sharingMode, accessMode). It performs validation of values assigned to keys.

copy()¶

get(key, default=None)¶

items()¶

iteritems()¶

iterkeys()¶

itervalues()¶

keys()¶

render()¶

Create valid table access parameter block according to current key/value pairs.

Returns

Table access definition block.

Return type

str

values()¶

ParameterBuffer¶

class fdb.ParameterBuffer(charset)¶

Helper class for construction of Database (and other) parameter buffers. Parameters are stored in insertion order.

add_byte(byte)¶

Add byte value to buffer.

Parameters

byte (int) – Value to be added.

add_byte_parameter(code, value)¶

Add byte value to parameter buffer.

Parameters

• code (int) – Firebird code for the parameter

• value (int) – Parameter value (0-255)

add_integer_parameter(code, value)¶

Add integer value to parameter buffer.

Parameters

• code (int) – Firebird code for the parameter

• value (int) – Parameter value

add_parameter_code(code)¶

Add parameter code to parameter buffer.

Parameters

code (int) – Firebird code for the parameter

add_string(value)¶

Add string value to buffer.

Parameters

value (bytes) – String to be added.

add_string_parameter(code, value)¶

Add string to parameter buffer.

Parameters

• code (int) – Firebird code for the parameter

• value (str) – Parameter value

add_word(word)¶

Add two byte value to buffer.

Parameters

word (int) – Value to be added.

clear()¶

Clear all parameters stored in parameter buffer.

get_buffer()¶

Get parameter buffer content.

Returns

Byte string with all inserted parameters.

Return type

bytes

get_length()¶

Returns actual total length of parameter buffer.

_RowMapping¶

class fdb.fbcore._RowMapping(description, row)¶

An internal dictionary-like class that wraps a row of results in order to map field name to field value.

Warning

We make ABSOLUTELY NO GUARANTEES about the return value of the fetch(one|many|all) methods except that it is a sequence indexed by field position, and no guarantees about the return value of the fetch(one|many|all)map methods except that it is a mapping of field name to field value.

Therefore, client programmers should NOT rely on the return value being an instance of a particular class or type.

get(field_name, default_value=None)¶

items()¶

iteritems()¶

iterkeys()¶

itervalues()¶

keys()¶

values()¶

EventBlock¶

class fdb.fbcore.EventBlock(queue, db_handle, event_names)¶

Represents Firebird API structure for block of events.

close()¶

Close this block canceling managed events.

count_and_reregister()¶

Count event occurences and reregister interest in futrther notifications.

buf_length = 0¶

length of internal event buffer

Type

int

property closed¶

(R/O)True if block is closed for business

Type

bool

event_buf = None¶

Event buffer

Type

bytes

event_id = 0¶

Event ID

Type

int

event_names = []¶

Registered event names

Type

list

result_buf = None¶

Result buffer

Type

bytes

TableAccessStats¶

class fdb.fbcore._TableAccessStats(table_id)¶

An internal class that wraps results from get_table_access_stats()

shutdown_mode codes for Connection.shutdown() and Connection.bring_online()¶

• SHUT_LEGACY

• SHUT_NORMAL

• SHUT_MULTI

• SHUT_SINGLE

• SHUT_FULL

shutdown_method codes for Connection.shutdown()¶

• SHUT_FORCE

• SHUT_DENY_NEW_TRANSACTIONS

• SHUT_DENY_NEW_ATTACHMENTS

mode codes for Connection.setWriteMode()¶

• WRITE_FORCED

• WRITE_BUFFERED

mode codes for Connection.setAccessMode()¶

• ACCESS_READ_WRITE

• ACCESS_READ_ONLY

Connection.get_server_capabilities() return codes¶

• CAPABILITY_MULTI_CLIENT

• CAPABILITY_REMOTE_HOP

• CAPABILITY_SERVER_CONFIG

• CAPABILITY_QUOTED_FILENAME

• CAPABILITY_NO_SERVER_SHUTDOWN

‘stats’ codes for Connection.backup()/Connection.restore()¶

• STATS_TOTAL_TIME

• STATS_TIME_DELTA

• STATS_PAGE_READS

• STATS_PAGE_WRITES

connect¶

fdb.services.connect(host='service_mgr', user=None, password=None)¶

Establishes a connection to the Services Manager.

Parameters

• host (str) – (optional) Host machine specification. Local by default.

• user (str) – (optional) Administrative user name. Defaults to content of environment variable ISC_USER or SYSDBA.

• password (str) – Administrative user password. Default is content of environment variable ISC_PASSWORD.

Note

By definition, a Services Manager connection is bound to a particular host. Therefore, the database specified as a parameter to methods such as getStatistics MUST NOT include the host name of the database server.

Hooks:

Event HOOK_SERVICE_ATTACHED: Executed before Connection instance is returned. Hook must have signature: hook_func(connection). Any value returned by hook is ignored.

Connection¶

class fdb.services.Connection(host, user, password, charset=None)¶

Represents a sevice connection between the database client (the Python process) and the database server.

Important

DO NOT create instances of this class directly! Use only connect() to get Connection instances.

Tip

Connection supports the iterator protocol, yielding lines of result like readline().

activate_shadow(database)¶

Activate Database Shadow(s).

Parameters

database (str) – Database filename or alias.

add_user(user)¶

Add new user.

Parameters

user (User) – Instance of User with at least its name and password attributes specified as non-empty values. All other attributes are optional.

Note

This method ignores the user_id and group_id attributes of User regardless of their values.

backup(source_database, dest_filenames, dest_file_sizes=(), ignore_checksums=0, ignore_limbo_transactions=0, metadata_only=0, collect_garbage=1, transportable=1, convert_external_tables=0, compressed=1, no_db_triggers=0, callback=None, stats=None)¶

Request logical (GBAK) database backup. (ASYNC service)

Parameters

• source_database (str) – Source database specification.

• dest_filenames (str or tuple(str)) – Backup file(s) specification.

Keyword Arguments

• dest_file_sizes (tuple(int)) – Specification of backup file max. sizes.

• ignore_checksums (int) – 1 to ignore checksums.

• ignore_limbo_transactions (int) – 1 to ignore limbo transactions.

• metadata_only (int) – 1 to create only metadata backup.

• collect_garbage (int) – 0 to skip garbage collection.

• transportable (int) – 0 to do not create transportable backup.

• convert_external_tables (int) – 1 to convert external table to internal ones.

• compressed (int) – 0 to create uncompressed backup.

• no_db_triggers (int) – 1 to disable database triggers temporarily.

• callback (callable) – Function to call back with each output line. Function must accept only one parameter: line of output.

• stats (list) – List of arguments for run-time statistics, see STATS_* constants.

If callback is not specified, backup log could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until backup report is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service will fail with exception.

bring_online(database, online_mode=0)¶

Bring previously shut down database back online.

Parameters

database (str) – Database filename or alias.

Keyword Arguments

online_mode (int) – One from following constants: SHUT_LEGACY, SHUT_SINGLE, SHUT_MULTI or (Default) SHUT_NORMAL.

See also

Method shutdown()

close()¶

Close the connection now (rather than whenever __del__ is called). The connection will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the connection.

commit_limbo_transaction(database, transaction_id)¶

Resolve limbo transaction with commit.

Parameters

• database (str) – Database filename or alias.

• transaction_id (int) – ID of Transaction to resolve.

get_architecture()¶

Get Firebird Server architecture.

Returns

Architecture (example: ‘Firebird/linux AMD64’).

Return type

str

get_attached_database_names()¶

Get list of attached databases.

Returns

Filenames of attached databases.

Return type

list

get_connection_count()¶

Get number of attachments to server.

Returns

Number of attachments.

Return type

int

get_home_directory()¶

Get Firebird Home (installation) Directory.

Returns

Directory path.

Return type

str

get_limbo_transaction_ids(database)¶

Get list of transactions in limbo.

Parameters

database (str) – Database filename or alias.

Returns

Transaction IDs.

Return type

list

Raises

fdb.InternalError – When can’t process the result buffer.

get_lock_file_directory()¶

Get directory location for Firebird lock files.

Returns

Directory path.

Return type

str

get_log(callback=None)¶

Request content of Firebird Server log. (ASYNC service)

Keyword Arguments

callback (callable) – Function to call back with each output line. Function must accept only one parameter: line of output.

If callback is not specified, log content could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until log content is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service will fail with exception.

get_message_file_directory()¶

Get directory with Firebird message file.

Returns

Directory path.

Return type

str

get_security_database_path()¶

Get full path to Firebird security database.

Returns

Path (path+filename) to security database.

Return type

str

get_server_capabilities()¶

Get list of Firebird capabilities.

Returns

Capability info codes for each capability reported by server.

Return type

tuple

Next fdb.services constants define possible info codes returned:

CAPABILITY_MULTI_CLIENT
CAPABILITY_REMOTE_HOP
CAPABILITY_SERVER_CONFIG
CAPABILITY_QUOTED_FILENAME
CAPABILITY_NO_SERVER_SHUTDOWN

Example

>>>fdb.services.CAPABILITY_REMOTE_HOP in svc.get_server_capabilities()
True

get_server_version()¶

Get Firebird version.

Returns

Firebird version (example: ‘LI-V2.5.2.26536 Firebird 2.5’).

Return type

str

get_service_manager_version()¶

Get Firebird Service Manager version number.

Returns

Version number.

Return type

int

get_statistics(database, show_only_db_log_pages=0, show_only_db_header_pages=0, show_user_data_pages=1, show_user_index_pages=1, show_system_tables_and_indexes=0, show_record_versions=0, callback=None, tables=None)¶

Request database statisctics. (ASYNC service)

Parameters

database (str) – Database specification.

Keyword Arguments

• show_only_db_log_pages (int) – 1 to analyze only log pages.

• show_only_db_header_pages (int) – 1 to analyze only database header. When set, all other parameters are ignored.

• show_user_data_pages (int) – 0 to skip user data analysis.

• show_user_index_pages (int) – 0 to skip user index analysis.

• show_system_tables_and_indexes (int) – 1 to analyze system tables and indices.

• show_record_versions (int) – 1 to analyze record versions.

• callback (callable) – Function to call back with each output line. Function must accept only one parameter: line of output.

• tables (str or list) – table name or iterable of table names.

If callback is not specified, statistical report could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until report is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service will fail with exception.

get_users(user_name=None)¶

Get information about user(s).

Keyword Arguments

user_name (str) – When specified, returns information only about user with specified user name.

Returns

List of User instances.

Return type

list

isrunning()¶

Returns True if service is running.

Note

Some services like backup() or sweep() may take time to comlete, so they’re called asynchronously. Until they’re finished, no other async service could be started.

local_backup(source_database, backup_stream, ignore_checksums=0, ignore_limbo_transactions=0, metadata_only=0, collect_garbage=1, transportable=1, convert_external_tables=0, compressed=1, no_db_triggers=0)¶

Request logical (GBAK) database backup into local byte stream. (SYNC service)

Parameters

• source_database (str) – Source database specification.

• backup_stream (stream) – Backup stream.

Keyword Arguments

• ignore_checksums (int) – 1 to ignore checksums.

• ignore_limbo_transactions (int) – 1 to ignore limbo transactions.

• metadata_only (int) – 1 to create only metadata backup.

• collect_garbage (int) – 0 to skip garbage collection.

• transportable (int) – 0 to do not create transportable backup.

• convert_external_tables (int) – 1 to convert external table to internal ones.

• compressed (int) – 0 to create uncompressed backup.

• no_db_triggers (int) – 1 to disable database triggers temporarily.

local_restore(backup_stream, dest_filenames, dest_file_pages=(), page_size=None, cache_buffers=None, access_mode_read_only=0, replace=0, deactivate_indexes=0, do_not_restore_shadows=0, do_not_enforce_constraints=0, commit_after_each_table=0, use_all_page_space=0, no_db_triggers=0, metadata_only=0)¶

Request database restore from logical (GBAK) backup stored in local byte stream. (SYNC service)

Parameters

• backup_stream (stream) – Backup stream.

• dest_filenames (str or tuple(str)) – Database file(s) specification.

Keyword Arguments

• dest_file_pages (tuple(int)) – Specification of database file max. # of pages.

• page_size (int) – Page size.

• cache_buffers (int) – Size of page-cache for this database.

• access_mode_read_only (int) – 1 to create R/O database.

• replace (int) – 1 to replace existing database.

• deactivate_indexes (int) – 1 to do not activate indices.

• do_not_restore_shadows (int) – 1 to do not restore shadows.

• do_not_enforce_constraints (int) – 1 to do not enforce constraints during restore.

• commit_after_each_table (int) – 1 to commit after each table is restored.

• use_all_page_space (int) – 1 to use all space on data pages.

• no_db_triggers (int) – 1 to disable database triggers temporarily.

• metadata_only (int) – 1 to restore only database metadata.

modify_user(user)¶

Modify user information.

Parameters

user (User) – Instance of User with at least its name attribute specified as non-empty value.

Note

This method sets first_name, middle_name and last_name to their actual values, and ignores the user_id and group_id attributes regardless of their values. password is set only when it has value.

nbackup(source_database, dest_filename, nbackup_level=0, no_db_triggers=0)¶

Perform physical (NBACKUP) database backup.

Parameters

• source_database (str) – Source database specification.

• dest_filename (str) – Backup file specification.

Keyword Arguments

• nbackup_level (int) – Incremental backup level.

• no_db_triggers (int) – 1 to disable database triggers temporarily.

Note

Method call will not return until action is finished.

next()¶

Return the next result line from service manager. Part of iterator protocol.

Raises

StopIteration – If there are no further lines.

no_linger(database)¶

Set one-off override for database linger.

Parameters

database (str) – Database filename or alias.

nrestore(source_filenames, dest_filename, no_db_triggers=0)¶

Perform restore from physical (NBACKUP) database backup.

Parameters

• source_filenames (str or tuple(str)) – Backup file(s) specification.

• dest_filename (str) – Database file specification.

Keyword Arguments

no_db_triggers (int) – 1 to disable database triggers temporarily.

Note

Method call will not return until action is finished.

readline()¶

Get next line of textual output from last service query.

Returns

Output line.

Return type

str

readlines()¶

Get list of remaining output lines from last service query.

Returns

Service output.

Return type

list

Raises

fdb.ProgrammingError – When service is not in fetching mode.

remove_user(user)¶

Remove user.

Parameters

user (User) – User name or Instance of User with at least its name attribute specified as non-empty value.

repair(database, read_only_validation=0, ignore_checksums=0, kill_unavailable_shadows=0, mend_database=0, validate_database=1, validate_record_fragments=1)¶

Database Validation and Repair.

Parameters

database (str) – Database filename or alias.

Keyword Arguments

• read_only_validation (int) – 1 to prevent any database changes.

• ignore_checksums (int) – 1 to ignore page checksum errors.

• kill_unavailable_shadows (int) – 1 to kill unavailable shadows.

• mend_database (int) – 1 to fix database for backup.

• validate_database (int) – 0 to skip database validation.

• validate_record_fragments (int) – 0 to skip validation of record fragments.

Note

Method call will not return until action is finished.

restore(source_filenames, dest_filenames, dest_file_pages=(), page_size=None, cache_buffers=None, access_mode_read_only=0, replace=0, deactivate_indexes=0, do_not_restore_shadows=0, do_not_enforce_constraints=0, commit_after_each_table=0, use_all_page_space=0, no_db_triggers=0, metadata_only=0, callback=None, stats=None)¶

Request database restore from logical (GBAK) backup. (ASYNC service)

Parameters

• source_filenames (str or tuple(str)) – Backup file(s) specification.

• dest_filenames (str or tuple(str)) – Database file(s) specification.

Keyword Arguments

• dest_file_pages (tuple(int)) – Specification of database file max. # of pages.

• page_size (int) – Page size.

• cache_buffers (int) – Size of page-cache for this database.

• access_mode_read_only (int) – 1 to create R/O database.

• replace (int) – 1 to replace existing database.

• deactivate_indexes (int) – 1 to do not activate indices.

• do_not_restore_shadows (int) – 1 to do not restore shadows.

• do_not_enforce_constraints (int) – 1 to do not enforce constraints during restore.

• commit_after_each_table (int) – 1 to commit after each table is restored.

• use_all_page_space (int) – 1 to use all space on data pages.

• no_db_triggers (int) – 1 to disable database triggers temporarily.

• metadata_only (int) – 1 to restore only database metadata.

• callback (callable) – Function to call back with each output line. Function must accept only one parameter: line of output.

• stats (list) – List of arguments for run-time statistics, see STATS_* constants.

If callback is not specified, restore log could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until restore report is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service will fail with exception.

rollback_limbo_transaction(database, transaction_id)¶

Resolve limbo transaction with rollback.

Parameters

• database (str) – Database filename or alias.

• transaction_id (int) – ID of Transaction to resolve.

set_access_mode(database, mode)¶

Set Database Access mode: Read Only or Read/Write

Parameters

• database (str) – Database filename or alias.

• mode (int) – One from following constants: ACCESS_READ_WRITE or ACCESS_READ_ONLY

set_default_page_buffers(database, n)¶

Set individual page cache size for Database.

Parameters

• database (str) – Database filename or alias.

• n (int) – Number of pages.

set_reserve_page_space(database, reserve_space)¶

Set data page space reservation policy.

Parameters

• database (str) – Database filename or alias.

• reserve_space (bool) – True to reserve space, False to do not.

set_sql_dialect(database, dialect)¶

Set SQL Dialect for Database.

Parameters

• database (str) – Database filename or alias.

• dialect (int) – 1 or 3.

set_sweep_interval(database, n)¶

Set treshold for automatic sweep.

Parameters

• database (str) – Database filename or alias.

• n (int) – Sweep treshold, or 0 to disable automatic sweep.

set_write_mode(database, mode)¶

Set Disk Write Mode: Sync (forced writes) or Async (buffered).

Parameters

• database (str) – Database filename or alias.

• mode (int) – One from following constants: WRITE_FORCED or WRITE_BUFFERED

shutdown(database, shutdown_mode, shutdown_method, timeout)¶

Database shutdown.

Parameters

• database (str) – Database filename or alias.

• shutdown_mode (int) – One from following constants: SHUT_LEGACY, SHUT_SINGLE, SHUT_MULTI or SHUT_FULL.

• shutdown_method (int) – One from following constants: SHUT_FORCE, SHUT_DENY_NEW_TRANSACTIONS or SHUT_DENY_NEW_ATTACHMENTS.

• timeout (int) – Time in seconds, that the shutdown must complete in.

See also

Method bring_online()

sweep(database)¶

Perform Database Sweep.

Note

Method call will not return until sweep is finished.

Parameters

database (str) – Database filename or alias.

trace_list()¶

Get information about existing trace sessions.

Returns

Mapping SESSION_ID -> SESSION_PARAMS

Return type

dict

Session parameters is another dictionary with next keys:

name

(str) (optional) Session name if specified.

date

(datetime.datetime) Session start date and time.

user

(str) Trace user name.

flags

(list(str)) Session flags.

Raises

fdb.OperationalError – When server can’t perform requested operation.

trace_resume(trace_id)¶

Resume trace session.

Parameters

trace_id (int) – Trace session ID.

Returns

Text with confirmation that session was resumed.

Return type

str

Raises

• fdb.DatabaseError – When trace session is not resumed.

• fdb.OperationalError – When server can’t perform requested operation.

trace_start(config, name=None)¶

Start new trace session. (ASYNC service)

Parameters

config (str) – Trace session configuration.

Keyword Arguments

name (str) – Trace session name.

Returns

Trace session ID.

Return type

integer

Raises

fdb.DatabaseError – When session ID is not returned on start.

Trace session output could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until session output is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service including call to any trace_ method will fail with exception.

trace_stop(trace_id)¶

Stop trace session.

Parameters

trace_id (int) – Trace session ID.

Returns

Text with confirmation that session was stopped.

Return type

str

Raises

• fdb.DatabaseError – When trace session is not stopped.

• fdb.OperationalError – When server can’t perform requested operation.

trace_suspend(trace_id)¶

Suspend trace session.

Parameters

trace_id (int) – Trace session ID.

Returns

Text with confirmation that session was paused.

Return type

str

Raises

• fdb.DatabaseError – When trace session is not paused.

• fdb.OperationalError – When server can’t perform requested operation.

user_exists(user)¶

Check for user’s existence.

Parameters

user (User) – User name or Instance of User with at least its name attribute specified as non-empty value.

Returns

True when the specified user exists.

Return type

bool

validate(database, include_tables=None, exclude_tables=None, include_indices=None, exclude_indices=None, lock_timeout=None, callback=None)¶

On-line database validation.

Parameters

database (str) – Database filename or alias.

Keyword Arguments

• include_tables (str) – Pattern for table names to include in validation run.

• exclude_tables (str) – Pattern for table names to exclude from validation run.

• include_indices (str) – Pattern for index names to include in validation run.

• exclude_indices (str) – Pattern for index names to exclude from validation run.

• lock_timeout (int) – lock timeout, used to acquire locks for table to validate, in seconds, default is 10 secs. 0 is no-wait, -1 is infinite wait.

• callback (callable) – Function to call back with each output line. Function must accept only one parameter: line of output.

Note

Patterns are regular expressions, processed by the same rules as SIMILAR TO expressions. All patterns are case-sensitive, regardless of database dialect. If the pattern for tables is omitted then all user tables will be validated. If the pattern for indexes is omitted then all indexes of the appointed tables will be validated. System tables are not validated.

If callback is not specified, validation log could be retrieved through readline(), readlines(), iteration over Connection or ignored via call to wait().

Note

Until validate report is not fully fetched from service (or ignored via wait()), any attempt to start another asynchronous service will fail with exception.

wait()¶

Wait until running service completes, i.e. stops sending data.

QUERY_TYPE_PLAIN_INTEGER = 1¶

QUERY_TYPE_PLAIN_STRING = 2¶

QUERY_TYPE_RAW = 3¶

property closed¶

(Read Only) True if connection is closed.

property engine_version¶

(Read Only) (float) Firebird version number of connected server. Only major.minor version.

property fetching¶

(Read Only) True if connection is fetching result.

property version¶

(Read Only) (string) Firebird version number string of connected server. Uses Firebird version numbers in form: major.minor.subrelease.build