FDB Reference

Module globals

fdb.__version__

Current driver version, string.

fdb.apilevel

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

fdb.threadsafety

Integer constant stating the level of thread safety the interface supports.

Curretly 1 = Threads may share the module, but not connections.

fdb.paramstyle

String constant stating the type of parameter marker formatting expected by the interface.

‘qmark’ = Question mark style, e.g. ‘...WHERE name=?’

fdb.DESCRIPTION_NAME

fdb.DESCRIPTION_TYPE_CODE

fdb.DESCRIPTION_DISPLAY_SIZE

fdb.DESCRIPTION_INTERNAL_SIZE

fdb.DESCRIPTION_PRECISION

fdb.DESCRIPTION_SCALE

fdb.DESCRIPTION_NULL_OK

Helper constants for work with Cursor.description content.

fdb.ISOLATION_LEVEL_READ_COMMITED_LEGACY

TPB for R/W WAIT READ COMMITTED NO RECORD VERSION transaction.

fdb.ISOLATION_LEVEL_READ_COMMITED

TPB for R/W WAIT READ COMMITTED RECORD VERSION transaction.

fdb.ISOLATION_LEVEL_REPEATABLE_READ

fdb.ISOLATION_LEVEL_SNAPSHOT

TPB’s for R/W WAIT SNAPSHOT transaction.

fdb.ISOLATION_LEVEL_SERIALIZABLE

fdb.ISOLATION_LEVEL_SNAPSHOT_TABLE_STABILITY

TPB’s for R/W WAIT SNAPSHOT TABLE STABILITY transaction.

fdb.ISOLATION_LEVEL_READ_COMMITED_RO

TPB for R/O WAIT READ COMMITTED RECORD VERSION transaction.

fdb.MAX_BLOB_SEGMENT_SIZE

fdb.charset_map

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

fdb.ODS_FB_20

fdb.ODS_FB_21

fdb.ODS_FB_25

ODS version numbers introduced by Firebird engine version.

fdb.IMPLEMENTATION_NAMES

fdb.PROVIDER_NAMES

fdb.DB_CLASS_NAMES

Exceptions

exception fdb.Warning

Bases: exceptions.Exception

Exception raised for important warnings like data truncations while inserting, etc.

exception fdb.Error

Bases: exceptions.Exception

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.

exception fdb.InterfaceError

Bases: fdb.fbcore.Error

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

exception fdb.DatabaseError

Bases: fdb.fbcore.Error

Exception raised for errors that are related to the database.

exception fdb.DataError

Bases: fdb.fbcore.DatabaseError

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

exception fdb.OperationalError

Bases: fdb.fbcore.DatabaseError

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.

exception fdb.IntegrityError

Bases: fdb.fbcore.DatabaseError

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

exception fdb.InternalError

Bases: fdb.fbcore.DatabaseError

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

exception fdb.ProgrammingError

Bases: fdb.fbcore.DatabaseError

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.

exception fdb.NotSupportedError

Bases: fdb.fbcore.DatabaseError

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

exception fdb.TransactionConflict

Bases: fdb.fbcore.DatabaseError

This is the exception inheritance layout:

StandardError
|__Warning
|__Error
   |__InterfaceError
   |__DatabaseError
      |__DataError
      |__OperationalError
      |__IntegrityError
      |__InternalError
      |__ProgrammingError
      |__NotSupportedError

Functions

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='\x03\t\x06\x0f\x11', connection_class=None, fb_library_name=None, no_gc=None, no_db_triggers=None, no_linger=None)

Establish a connection to database.

Parameters:

• dsn – Connection string in format [host[/port]]:database
• user (string) – User name. If not specified, fdb attempts to use ISC_USER envar.
• password (string) – User password. If not specified, fdb attempts to use ISC_PASSWORD envar.
• host (string) – Server host machine specification.
• port (integer) – Port used by Firebird server.
• database (string) – Database specification (file spec. or alias)
• sql_dialect – SQL Dialect for connection.
• role (string) – User role.
• charset (string) – Character set for connection.
• buffers (integer) – Page case size override for connection.
• force_writes (integer) – Forced writes override for connection.
• no_reserve (integer) – Page space reservation override for connection.
• db_key_scope (integer) – DBKEY scope override for connection.
• isolation_level (0, 1, 2 or 3) – Default transaction isolation level for connection (not used).
• connection_class (subclass of Connection) – Custom connection class
• fb_library_name (string) – Full path to Firebird client library. See load_api() for details.
• no_gc (integer) – No Garbage Collection flag.
• no_db_triggers (integer) – No database triggers flag (FB 2.1).
• no_linger (integer) – No linger flag (FB3).

Returns:

Connection to database.

Return type:

Connection instance.

Raises:

• ProgrammingError – For bad parameter values.
• 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')

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.

Parameters:

• sql – “CREATE DATABASE” statement.
• sql_dialect (1 or 3) – SQL Dialect for newly created database.
• dsn – Connection string in format [host[/port]]:database
• user (string) – User name. If not specified, fdb attempts to use ISC_USER envar.
• password (string) – User password. If not specified, fdb attempts to use ISC_PASSWORD envar.
• host (string) – Server host machine specification.
• port (integer) – Port used by Firebird server.
• database (string) – Database specification (file spec. or alias)
• page_size (integer) – Database page size.
• length (integer) – Database size in pages.
• charset (string) – Character set for connection.
• files (string) – Specification of secondary database files.
• connection_class (subclass of Connection) – Custom connection class
• fb_library_name (string) – Full path to Firebird client library. See load_api() for details.

Returns:

Connection to the newly created database.

Return type:

Connection instance.

Raises:

• ProgrammingError – For bad parameter values.
• 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)

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 (string) – (optional) Path to Firebird Client Library. When it’s not specified, FDB does its best to locate appropriate client library. Returns:fdb.ibase.fbclient_API instance.

Classes

Connection

class fdb.Connection(db_handle, dpb=None, sql_dialect=3, charset=None, isolation_level='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.
• dpb – Database Parameter Block associated with database handle.
• sql_dialect (integer) – SQL Dialect associated with database handle.
• charset (string) – Character set associated with database handle.

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.

exception Connection.DatabaseError

Exception raised for errors that are related to the database.

exception Connection.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.

exception Connection.IntegrityError

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

exception Connection.InterfaceError

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

exception Connection.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.

exception Connection.NotSupportedError

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

exception Connection.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.

exception Connection.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.

exception Connection.Warning

Exception raised for important warnings like data truncations while inserting, etc.

Connection.begin(tpb=None)

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

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

Connection.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 ProgrammingError:  When connection is a member of a ConnectionGroup.

Connection.commit(retaining=False)

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

Parameters:retaining (boolean) – (Optional) Indicates whether the transactional context of the transaction being resolved should be recycled. Raises ProgrammingError:  If Connection is closed.

Connection.cursor()

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

Raises ProgrammingError:  If Connection is closed.

Connection.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 (integer) – One of the isc_info_* constants.
• result_type (string) – Must be either ‘s’ if you expect a string result, or ‘i’ if you expect an integer result.
• page_number (integer) – Page number for fb_info_page_contents info code.

Raises:

• DatabaseError – When error is returned from server.
• OperationalError – When returned information is bigger than SHRT_MAX.
• 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).

Connection.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).

Raises:

• ValueError – When requested code is not recognized.
• OperationalError – On unexpected processing condition.

Connection.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:

• ProgrammingError – When connection is a member of a ConnectionGroup.
• DatabaseError – When error is returned from server.

Connection.event_conduit(event_names)

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

Parameters:event_names – A sequence of string event names. Returns:An EventConduit instance.

Connection.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 (string) – 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.

Parameters:

sql (string) – SQL statement to execute.

Raises:

• ProgrammingError – When connection is closed.
• DatabaseError – When error is returned from server.

Connection.get_active_transaction_count()

Return count of currently active transactions.

Connection.get_active_transaction_ids()

Return list of transaction IDs for all currently active transactions.

Connection.get_page_contents(page_number)

Return content of specified database page as binary string.

Parameters:page_number (int) – Page sequence number.

Connection.get_table_access_stats()

Return current stats for access to tables.

Returns:List of fbcore._TableAccessStats instances.

Connection.isreadonly()

Returns True if database is read-only.

Connection.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.

Parameters:

• retaining (boolean) – (Optional) Indicates whether the transactional context of the transaction being resolved should be recycled.
• savepoint (string) – (Optional) Causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely.

Raises ProgrammingError:  

If Connection is closed.

Connection.savepoint(name)

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

Parameters:name (string) – Name for savepoint. Raises ProgrammingError:  If Connection is closed.

Example:

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

Connection.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.

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

Connection.trans_info(request)

Pythonic wrapper around transaction_info() call. Operates on main_transaction. See Transaction.trans_info() for details.

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.

Raises:

• ProgrammingError – When transaction is not active.
• OperationalError – When result is too large to fit into buffer of size SHRT_MAX.
• InternalError – On unexpected processing condition.

Connection.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 Transaction.transaction_info() for details.

Parameters:

• info_code (integer) –

  One from next constants:

  • isc_info_tra_id
  • isc_info_tra_oldest_interesting
  • isc_info_tra_oldest_snapshot
  • isc_info_tra_oldest_active
  • isc_info_tra_isolation
  • isc_info_tra_access
  • isc_info_tra_lock_timeout

  See Firebird API Guide for details.

• result_type (string) –

  String code for result type:

  • ‘i’ for Integer
  • ‘s’ fro String

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.

Raises:

• ProgrammingError – When transaction is not active.
• OperationalError – When result is too large to fit into buffer of size SHRT_MAX.
• InternalError – On unexpected processing condition.
• ValueError – On illegal result_type value.

Connection.attachment_id None

(Read Only) (int) Internal ID (server-side) for connection.

Connection.charset None

(Read Only) (string) Connection Character set name.

Connection.closed None

(Read Only) (bool) True if connection is closed.

Connection.creation_date None

(Read Only) (datetime.datetime) Database creation date & time.

Connection.current_memory None

(Read Only) (int) Amount of server memory (in bytes) currently in use.

Connection.database_name None

(Read Only) (string) Database name (filename or alias).

Connection.database_sql_dialect None

(Read Only) (int) SQL dialect of attached database.

Connection.db_class_id None

(Read Only) (int) Database class ID

Connection.default_tpb None

(Read/Write) Deafult Transaction Parameter Block used for all newly started transactions.

Connection.engine_version None

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

Connection.firebird_version None

(Read Only) (string) 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

Connection.forced_writes None

(Read Only) (bool) Mode in which database writes are performed: True=sync, False=async.

Connection.group None

(Read Only) ConnectionGroup this Connection belongs to, or None.

Connection.implementation_id None

(Read Only) (int) Server implementation ID

Connection.io_stats None

(Read Only) 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.

Connection.main_transaction None

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

Connection.max_memory None

(Read Only) (int) Maximum amount of memory (in bytes) used at one time since the first process attached to the database.

Connection.monitor None

(Read Only) (Monitor) Database monitoring object.

Connection.next_transaction None

(Read Only) (int) ID of Next Transaction.

Connection.oat None

(Read Only) (int) ID of Oldest Active Transaction.

Connection.ods None

(Read Only) (float) On-Disk Structure (ODS).

Connection.ods_minor_version None

(Read Only) (int) On-Disk Structure (ODS) minor version number.

Connection.ods_version None

(Read Only) (int) On-Disk Structure (ODS) major version number.

Connection.oit None

(Read Only) (int) ID of Oldest Interesting Transaction.

Connection.ost None

(Read Only) (int) ID of Oldest Snapshot Transaction.

Connection.page_cache_size None

(Read Only) (int) Size of page cache in pages.

Connection.page_size None

(Read Only) (int) Database page size in bytes.

Connection.pages_allocated None

(Read Only) (int) Number of database pages allocated.

Connection.provider_id None

(Read Only) (int) Server provider ID

Connection.query_transaction None

(Read Only) Special “query” Transaction instance 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.

Connection.schema None

(Read Only) (Schema) Database metadata object.

Connection.server_version None

(Read Only) (string) 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

Connection.site_name None

(Read Only) (string) Database site name.

Connection.space_reservation None

(Read Only) (bool) When True 20% page space is reserved for holding backup versions of modified records.

Connection.sql_dialect None

(Read Only) (int) SQL dialect for this connection.

Connection.sweep_interval None

(Read Only) (int) Sweep interval.

Connection.transactions None

(Read Only) (tuple) Transaction instances associated with this connection.

Connection.version None

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

class fdb.ConnectionWithSchema(db_handle, dpb=None, sql_dialect=3, charset=None, isolation_level='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.

backup_history None

List of all nbackup hisotry records. Items are BackupHistory objects.

character_sets None

List of all character sets in database. Items are CharacterSet objects.

collations None

List of all collations in database. Items are Collation objects.

constraints None

List of all constraints in database. Items are Constraint objects.

default_character_set None

Default CharacterSet for database

dependencies None

List of all dependencies in database. Items are Dependency objects.

description None

Database description or None if it doesn’t have a description.

domains None

List of all user domains in database. Items are Domain objects.

enum_character_set_names None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_determinism_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_field_subtypes None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_field_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_function_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_grant_options None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_index_activity_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_index_unique_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_legacy_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_mechanism_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_object_type_codes None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_object_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_page_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_param_type_from None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_parameter_mechanism_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_parameter_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_privacy_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_procedure_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_relation_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_system_flag_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_transaction_state_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_trigger_activity_flags None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

enum_trigger_types None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

exceptions None

List of all exceptions in database. Items are DatabaseException objects.

files None

List of all extension files defined for database. Items are DatabaseFile objects.

filters None

List of all user-defined BLOB filters. Items are Filter objects.

functions None

List of all user functions defined in database. Items are Function objects.

generators None

List of all user generators in database. Items are Sequence objects.

indices None

List of all user indices in database. Items are Index objects.

linger None

Database linger value.

opt_always_quote None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

opt_generator_keyword None

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

owner_name None

Database owner name.

packages None

List of all packages defined for database. Items are Package objects.

privileges None

List of all privileges defined for database. Items are Privilege objects.

procedures None

List of all user procedures in database. Items are Procedure objects.

roles None

List of all roles in database. Items are Role objects.

security_class None

Can refer to the security class applied as databasewide access control limits.

sequences None

List of all user generators in database. Items are Sequence objects.

shadows None

List of all shadows defined for database. Items are Shadow objects.

sysdomains None

List of all system domains in database. Items are Domain objects.

sysfunctions None

List of all system functions defined in database. Items are Function objects.

sysgenerators None

List of all system generators in database. Items are Sequence objects.

sysindices None

List of all system indices in database. Items are Index objects.

sysprocedures None

List of all system procedures in database. Items are Procedure objects.

syssequences None

List of all system generators in database. Items are Sequence objects.

systables None

List of all system tables in database. Items are Table objects.

systriggers None

List of all system triggers in database. Items are Trigger objects.

sysviews None

List of all system views in database. Items are View objects.

tables None

List of all user tables in database. Items are Table objects.

triggers None

List of all user triggers in database. Items are Trigger objects.

views None

List of all user views in database. Items are View objects.

Note

For list of methods see fdb.schema.Schema.

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 (string) – Stored procedure name.
• parameters (List or Tuple) – (Optional) 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.
• ProgrammingError – When more parameters than expected are suplied.
• 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. Also the cache with prepared statements is left intact.

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 (string or PreparedStatement instance) – SQL command specification.
• parameters (List or Tuple) – (Optional) 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.
• ProgrammingError – When more parameters than expected are suplied.
• 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 (string or PreparedStatement instance) – 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.
• ProgrammingError – When there are more parameters in any sequence than expected.
• 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:

• DatabaseError – When error is returned by server.
• 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:

• DatabaseError – When error is returned by server.
• 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.

Parameters:

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

Returns:

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

Raises:

• DatabaseError – When error is returned by server.
• 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.

Parameters:

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

Returns:

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

Raises:

• DatabaseError – When error is returned by server.
• 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:

• DatabaseError – When error is returned by server.
• 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:

• DatabaseError – When error is returned by server.
• 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:Iterator that yields tuple of values like fetchone().

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 (string) – SQL command

Returns:

PreparedStatement instance.

Raises:

• DatabaseError – When error is returned by server.
• 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 (string or sequence) – 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 (string) – Name of BLOB column. Raises ProgrammingError:  

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

(Read/Write) 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.

connection None

(Read Only) (Connection) PEP 249 Extension. Reference to the Connection object on which the cursor was created.

description None

(Read Only) Sequence of 7-item sequences. Each of these sequences 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.

name None

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

plan None

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

rowcount None

(Read Only) (integer) 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.

transaction None

(Read Only) (Transaction) Reference to the Transaction object on which the cursor was created.

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.
• default_tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – Transaction Parameter Block for this transaction. If None is specified, uses ISOLATION_LEVEL_READ_COMMITED.
• default_action (string ‘commit’ or ‘rollback’) – Action taken when active transaction is ended automatically (during close() or begin()).

Raises ProgrammingError:  

When zero or more than 16 connections are given.

begin(tpb=None)

Starts a transaction explicitly.

Parameters:tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – (optional) 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:

• DatabaseError – When error is returned by server.
• 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.

Parameters:retaining (boolean) – Indicates whether the transactional context of the transaction being resolved should be recycled. Raises 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.

Parameters:connection (Connection instance) – Required only when Transaction is bound to multiple Connections, to specify to which Connection the returned Cursor should be bound. Raises 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 (string) – 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.

Parameters:sql (string) – SQL statement to execute. Raises 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.

Parameters:

• retaining (boolean) – Indicates whether the transactional context of the transaction being resolved should be recycled. Mutually exclusive with ‘savepoint`.
• savepoint (string) – 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:

• ProgrammingError – If both savepoint and retaining are specified.
• 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 (string) – 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 (integer) – One from the isc_info_tra_* constants.
• result_type (string ‘s’ or ‘i’) – Code for result type.

Raises:

• ProgrammingError – If transaction is not active.
• OperationalError – When result is too large to fit into buffer of size SHRT_MAX.
• InternalError – On unexpected processing condition.
• ValueError – When illegal result type code is specified.

active None

(Read Only) True if transaction is active.

closed None

(Read Only) True if transaction is closed.

cursors None

(Read Only) List of Cursor objects associated with this Transaction.

default_action None

(Read/Write) (string) ‘commit’ or ‘rollback’, action to be taken when physical transaction has to be ended automatically. Default is ‘commit’.

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

(Read/Write) Transaction Parameter Block.

isolation None

(Read Only) (int) or (tuple) Isolation level code [isc_info_tra_consistency,

lock_timeout None

(Read Only) (int) Lock timeout (seconds or -1 for unlimited).

oat None

(Read Only) (int) ID of Oldest Active Transaction when this transaction started.

oit None

(Read Only) (int) ID of Oldest Interesting Transaction when this transaction started.

ost None

(Read Only) (int) ID of Oldest Snapshot Transaction when this transaction started.

transaction_id None

(Read Only) (int) Internal ID (server-side) for transaction.

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_name)

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

Parameters:blob_name (string or sequence) – 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.

Parameters:blob_name (string) – Name of BLOB column.

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!

closed None

(Read Only) (boolean) 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.

cursor = None

Cursor instance that manages this PreparedStatement. Do not change!

description None

(Read Only) Sequence of 7-item sequences. Each of these sequences contains information describing one result column: (name, type_code, display_size,internal_size, precision, scale, null_ok)

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!

name None

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

plan None

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

rowcount None

(Read Only) (integer) 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.

sql None

(Read Only) (string) SQL command this PreparedStatement executes.

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.
• 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.

Parameters:tpb (TPB instance, list/tuple of isc_tpb_* constants or bytestring) – (Optional) Transaction Parameter Buffer for newly started transaction. If not specified, default_tpb is used. Raises ProgrammingError:  When group is empty or has active transaction.

clear()

Removes all connections from group.

Raises 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.

Parameters:retaining (boolean) – Indicates whether the transactional context of the transaction being resolved should be recycled. Raises ProgrammingError:  When group is empty.

contains(con)

Returns True if specified connection belong to this group.

Parameters:con – Connection instance.

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 instance. Raises ProgrammingError:  When group is empty or specified connection doesn’t belong to this group.

disband()

Forcefully deletes all connections from connection group.

Note

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

Note

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 (string) – 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.

Parameters:sql (string) – SQL statement to execute. Raises 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 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.

Parameters:retaining (boolean) – Indicates whether the transactional context of the transaction being resolved should be recycled. Raises ProgrammingError:  When group is empty.

savepoint(name)

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

Parameters:name (string) – Name for savepoint. Raises ProgrammingError:  When group is empty.

default_tpb None

(Read/Write) Deafult Transaction Parameter Block used for transactions.

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.

Example:

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 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.

Parameters:timeout (integer 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.

closed None

(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 DatabaseError:  When error is returned by server.

flush()

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

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 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 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 (integer) – Offset from specified position.
• whence (os.SEEK_SET, os.SEEK_CUR or os.SEEK_END) – (Optional) Context for offset.

Raises 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().

closed None

(Read Only) (boolean) True is BlobReader is closed.

mode None

(Read Only) (string) File mode - always “rb”

TPB

class fdb.TPB

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

copy()

Returns a copy of self.

render()

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

Returns:(string) TPB block.

access_mode None

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

isolation_level None

(integer or tuple) 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

lock_resolution None

(integer) Required lock resolution method. Either isc_tpb_wait or isc_tpb_nowait.

Default: isc_tpb_wait

lock_timeout None

(integer) Required lock timeout or None.

Default: None

table_reservation None

(TableReservation) 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)

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:(string) Table access definition block.

values()

Internally used classes exposed to driver users

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(fieldName, defaultValue=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

closed None

(ReadOnly) True if block is closed for business

event_buf = None

Event buffer

event_id = 0

Event ID

event_names = []

List of registered event names

result_buf = None

Result buffer

TableAccessStats

class fdb.fbcore._TableAccessStats(table_id)

An internal class that wraps results from get_table_access_stats()

Services

Module globals

fdb.services.SHUT_LEGACY

fdb.services.SHUT_NORMAL

fdb.services.SHUT_MULTI

fdb.services.SHUT_SINGLE

fdb.services.SHUT_FULL

These constants are to be passed as the shutdown_mode parameter to Connection.shutdown() and Connection.bring_online().

fdb.services.SHUT_FORCE

fdb.services.SHUT_DENY_NEW_TRANSACTIONS

fdb.services.SHUT_DENY_NEW_ATTACHMENTS

These constants are to be passed as the shutdown_method parameter to Connection.shutdown()

fdb.services.WRITE_FORCED

fdb.services.WRITE_BUFFERED

These constants are to be passed as the mode parameter to Connection.setWriteMode()

fdb.services.ACCESS_READ_WRITE

fdb.services.ACCESS_READ_ONLY

These constants are to be passed as the mode parameter to Connection.setAccessMode()

fdb.services.CAPABILITY_MULTI_CLIENT

fdb.services.CAPABILITY_REMOTE_HOP

fdb.services.CAPABILITY_SERVER_CONFIG

fdb.services.CAPABILITY_QUOTED_FILENAME

fdb.services.CAPABILITY_NO_SERVER_SHUTDOWN

These constants are return values of Connection.get_server_capabilities()

fdb.services.STATS_TOTAL_TIME

fdb.services.STATS_TIME_DELTA

fdb.services.STATS_PAGE_READS

fdb.services.STATS_PAGE_WRITES

These constants are options for Connection.backup()/Connection.restore() ‘stats’ parameter.

Functions

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

Establishes a connection to the Services Manager.

Parameters:

• host (string) – (optional) Host machine specification. Local by default.
• user (string) – (optional) Administrative user name. Defaults to content of environment variable ‘ISC_USER’ or ‘SYSDBA’.
• password (string) – 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.

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 (string) – 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_to_internal=0, compressed=1, no_db_triggers=0, callback=None, stats=None)

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

Parameters:

• source_database (string) – Source database specification.
• dest_filenames (string or tuple of strings) – Backup file(s) specification.
• dest_file_sizes (tuple of integers) – (optional) specification of backup file max. sizes.
• ignore_checksums (integer) – 1 to ignore checksums.
• ignore_limbo_transactions (integer) – 1 to ignore limbo transactions.
• metadata_only (integer) – 1 to create only metadata backup.
• collect_garbage (integer) – 0 to skip garbage collection.
• transportable (integer) – 0 to do not create transportable backup.
• convert_external_tables_to_internal (integer) – 1 to convert external table to internal ones.
• compressed (integer) – 0 to create uncompressed backup.
• no_db_triggers (integer) – 1 to disable database triggers temporarily.
• callback (function) – 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 (string) – Database filename or alias.
• online_mode (integer) – (Optional) One from following constants: SHUT_LEGACY, SHUT_SINGLE, SHUT_MULTI or SHUT_NORMAL (Default).

See also

See also shutdown() method.

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 (string) – Database filename or alias.
• transaction_id (integer) – ID of Transaction to resolve.

get_architecture()

Get Firebird Server architecture.

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

get_attached_database_names()

Get list of attached databases.

Returns list:Filenames of attached databases.

get_connection_count()

Get number of attachments to server.

Returns integer:  Directory path.

get_home_directory()

Get Firebird Home (installation) Directory.

Returns string:Directory path.

get_limbo_transaction_ids(database)

Get list of transactions in limbo.

Parameters:database (string) – Database filename or alias. Returns list:Transaction IDs. Raises InternalError:  When can’t process the result buffer.

get_lock_file_directory()

Get directory location for Firebird lock files.

Returns string:Directory path.

get_log(callback=None)

Request content of Firebird Server log. (ASYNC service)

Parameters:callback (function) – 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 string:Directory path.

get_security_database_path()

Get full path to Firebird security database.

Returns string:Path (path+filename) to security database.

get_server_capabilities()

Get list of Firebird capabilities.

Returns tuple:Capability info codes for each capability reported by server.

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 string:Firebird version (example: ‘LI-V2.5.2.26536 Firebird 2.5’).

get_service_manager_version()

Get Firebird Service Manager version number.

Returns integer:  Version number.

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 (string) – Database specification.
• show_only_db_log_pages (integer) – 1 to analyze only log pages.
• show_only_db_header_pages (integer) – 1 to analyze only database header. When set, all other parameters are ignored.
• show_user_data_pages (integer) – 0 to skip user data analysis.
• show_user_index_pages (integer) – 0 to skip user index analysis.
• show_system_tables_and_indexes (integer) – 1 to analyze system tables and indices.
• show_record_versions (integer) – 1 to analyze record versions.
• callback (function) – Function to call back with each output line. Function must accept only one parameter: line of output.
• tables (string_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).

Parameters:user_name (string) – (Optional) When specified, returns information only about user with specified user name. Returns list:User instances.

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.

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 (string) – Source database specification.
• dest_filename – Backup file specification.
• nbackup_level (integer) – Incremental backup level.
• no_db_triggers (integer) – 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 (string) – Database filename or alias.

nrestore(source_filenames, dest_filename, no_db_triggers=0)

Perform restore from physical (NBACKUP) database backup.

Parameters:

• source_filenames (string or tuple of strings) – Backup file(s) specification.
• dest_filename – Database file specification.
• no_db_triggers (integer) – 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 string:Output line.

readlines()

Get list of remaining output lines from last service query.

Returns list:Service output. Raises ProgrammingError:  When service is not in fetching mode.

remove_user(user)

Remove user.

Parameters:user (string or 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 (string) – Database filename or alias.
• read_only_validation (integer) – 1 to prevent any database changes.
• ignore_checksums (integer) – 1 to ignore page checksum errors.
• kill_unavailable_shadows (integer) – 1 to kill unavailable shadows.
• mend_database (integer) – 1 to fix database for backup.
• validate_database (integer) – 0 to skip database validation.
• validate_record_fragments (integer) – 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 (string or tuple of strings) – Backup file(s) specification.
• dest_filenames (string or tuple of strings) – Database file(s) specification.
• dest_file_pages (tuple of integers) – (optional) specification of database file max. # of pages.
• page_size (integer) – (optional) Page size.
• cache_buffers (integer) – (optional) Size of page-cache for this database.
• access_mode_read_only (integer) – 1 to create R/O database.
• replace (integer) – 1 to replace existing database.
• deactivate_indexes (integer) – 1 to do not activate indices.
• do_not_restore_shadows (integer) – 1 to do not restore shadows.
• do_not_enforce_constraints (integer) – 1 to do not enforce constraints during restore.
• commit_after_each_table (integer) – 1 to commit after each table is restored.
• use_all_page_space (integer) – 1 to use all space on data pages.
• no_db_triggers (integer) – 1 to disable database triggers temporarily.
• metadata_only (integer) – 1 to restore only database metadata.
• callback (function) – 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 (string) – Database filename or alias.
• transaction_id (integer) – ID of Transaction to resolve.

set_access_mode(database, mode)

Set Database Access mode: Read Only or Read/Write

Parameters:

• database (string) – Database filename or alias.
• mode (integer) – 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 (string) – Database filename or alias.
• n (integer) – Number of pages.

set_reserve_page_space(database, reserve_space)

Set data page space reservation policy.

Parameters:

• database (string) – Database filename or alias.
• reserve_space (boolean) – True to reserve space, False to do not.

set_sql_dialect(database, dialect)

Set SQL Dialect for Database.

Parameters:

• database (string) – Database filename or alias.
• dialect (integer) – 1 or 3.

set_sweep_interval(database, n)

Set treshold for automatic sweep.

Parameters:

• database (string) – Database filename or alias.
• n (integer) – 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 (string) – Database filename or alias.
• mode (integer) – One from following constants: WRITE_FORCED or WRITE_BUFFERED

shutdown(database, shutdown_mode, shutdown_method, timeout)

Database shutdown.

Parameters:

• database (string) – Database filename or alias.
• shutdown_mode (integer) – One from following constants: SHUT_LEGACY, SHUT_SINGLE, SHUT_MULTI or SHUT_FULL.
• shutdown_method (integer) – One from following constants: SHUT_FORCE, SHUT_DENY_NEW_TRANSACTIONS or SHUT_DENY_NEW_ATTACHMENTS.
• timeout (integer) – Time in seconds, that the shutdown must complete in.

See also

See also bring_online() method.

sweep(database)

Perform Database Sweep.

Note

Method call will not return until sweep is finished.

Parameters:database (string) – Database filename or alias.

trace_list()

Get information about existing trace sessions.

Returns dictionary:  

Mapping SESSION_ID -> SESSION_PARAMS

Session parameters is another dictionary with next keys:

name:(string) (optional) Session name if specified. date:(datetime.datetime) Session start date and time. user:(string) Trace user name. flags:(list of strings) Session flags.

Raises OperationalError:  

When server can’t perform requested operation.

trace_resume(trace_id)

Resume trace session.

Parameters:

trace_id (integer) – Trace session ID.

Returns string:

Text with confirmation that session was resumed.

Raises:

• DatabaseError – When trace session is not resumed.
• OperationalError – When server can’t perform requested operation.

trace_start(config, name=None)

Start new trace session. (ASYNC service)

Parameters:

• config (string) – Trace session configuration.
• name (string) – (optional) Trace session name.

Returns integer:  

Trace session ID.

Raises 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 (integer) – Trace session ID.

Returns string:

Text with confirmation that session was stopped.

Raises:

• DatabaseError – When trace session is not stopped.
• OperationalError – When server can’t perform requested operation.

trace_suspend(trace_id)

Suspend trace session.

Parameters:

trace_id (integer) – Trace session ID.

Returns string:

Text with confirmation that session was paused.

Raises:

• DatabaseError – When trace session is not paused.
• OperationalError – When server can’t perform requested operation.

user_exists(user)

Check for user’s existence.

Parameters:user (string or User) – User name or Instance of User with at least its name attribute specified as non-empty value. Returns boolean:  True when the specified user exists.

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 (string) – Database filename or alias.
• include_tables (string) – Pattern for table names to include in validation run.
• exclude_tables (string) – Pattern for table names to exclude from validation run.
• include_indices (string) – Pattern for index names to include in validation run.
• exclude_indices (string) – Pattern for index names to exclude from validation run.
• lock_timeout (integer) – 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 (function) – 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.

QUERY_TYPE_PLAIN_INTEGER = 1

QUERY_TYPE_PLAIN_STRING = 2

QUERY_TYPE_RAW = 3

closed None

(Read Only) True if connection is closed.

engine_version None

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

fetching None

(Read Only) True if connection is fetching result.

version None

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

User

class fdb.services.User(name=None)

load_information(svc)

Load information about user from server.

Parameters:svc (Connection) – Open service connection. Returns:True if information was successfuly retrieved, False otherwise. Raises ProgrammingError:  If user name is not defined.

first_name = None

First name.

group_id = None

User group ID

last_name = None

Last name

middle_name = None

Middle name

name = None

User login name (username).

password = None

Password. Not returned by user output methods, but must be specified to add a user.

user_id = None

User ID

Database schema

Module globals

fdb.schema.COLUMN_TYPES

fdb.schema.INTEGRAL_SUBTYPES

fdb.schema.BLOB_SUBTYPES

fdb.schema.RESERVED

fdb.schema.NON_RESERVED

Section codes for Schema.get_metadata_ddl():

fdb.schema.SCRIPT_COLLATIONS

fdb.schema.SCRIPT_CHARACTER_SETS

fdb.schema.SCRIPT_UDFS

fdb.schema.SCRIPT_GENERATORS

fdb.schema.SCRIPT_EXCEPTIONS

fdb.schema.SCRIPT_DOMAINS

fdb.schema.SCRIPT_PACKAGE_DEFS

fdb.schema.SCRIPT_FUNCTION_DEFS

fdb.schema.SCRIPT_PROCEDURE_DEFS

fdb.schema.SCRIPT_TABLES

fdb.schema.SCRIPT_PRIMARY_KEYS

fdb.schema.SCRIPT_UNIQUE_CONSTRAINTS

fdb.schema.SCRIPT_CHECK_CONSTRAINTS

fdb.schema.SCRIPT_FOREIGN_CONSTRAINTS

fdb.schema.SCRIPT_INDICES

fdb.schema.SCRIPT_VIEWS

fdb.schema.SCRIPT_PACKAGE_BODIES

fdb.schema.SCRIPT_PROCEDURE_BODIES

fdb.schema.SCRIPT_FUNCTION_BODIES

fdb.schema.SCRIPT_TRIGGERS

fdb.schema.SCRIPT_ROLES

fdb.schema.SCRIPT_GRANTS

fdb.schema.SCRIPT_COMMENTS

fdb.schema.SCRIPT_SHADOWS

fdb.schema.SCRIPT_SET_GENERATORS

fdb.schema.SCRIPT_INDEX_DEACTIVATIONS

fdb.schema.SCRIPT_INDEX_ACTIVATIONS

fdb.schema.SCRIPT_TRIGGER_DEACTIVATIONS

fdb.schema.SCRIPT_TRIGGER_ACTIVATIONS

Functions

fdb.schema.get_grants(privileges, grantors=None)

Get list of minimal set of SQL GRANT statamenets necessary to grant specified privileges.

Parameters:

• privileges (list) – List of Privilege instances.
• grantors (list) – List of standard grantor names. Generates GRANTED BY clause for privileges granted by user that’s not in list.

fdb.schema.isKeyword(ident)

Returns True if ident is Firebird keyword.

fdb.schema.escape_single_quotes(text)

Schema

class fdb.schema.Schema

This class represents database schema.

accept_visitor(visitor)

Visitor Pattern support. Calls visitSchema(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

bind(connection)

Bind this instance to specified Connection.

Parameters:connection – Connection instance. Raises ProgrammingError:  If Schema object was set as internal (via _set_as_internal()).

clear()

Drop all cached metadata objects.

close()

Sever link to Connection.

Raises ProgrammingError:  If Schema object was set as internal (via _set_as_internal()).

get_character_set(name)

Get CharacterSet by name.

Parameters:name (string) – Character set name. Returns:CharacterSet with specified name or None.

get_character_set_by_id(id)

Get CharacterSet by ID.

Parameters:name (integer) – CharacterSet ID. Returns:CharacterSet with specified ID or None.

get_collation(name)

Get Collation by name.

Parameters:name (string) – Collation name. Returns:Collation with specified name or None.

get_collation_by_id(charset_id, collation_id)

Get Collation by ID.

Parameters:

• charset_id (integer) – Character set ID.
• collation_id (integer) – Collation ID.

Returns:

Collation with specified ID or None.

get_constraint(name)

Get Constraint by name.

Parameters:name (string) – Constraint name. Returns:Constraint with specified name or None.

get_domain(name)

Get Domain by name.

Parameters:name (string) – Domain name. Returns:Domain with specified name or None.

get_exception(name)

Get DatabaseException by name.

Parameters:name (string) – Exception name. Returns:DatabaseException with specified name or None.

get_function(name)

Get Function by name.

Parameters:name (string) – Function name. Returns:Function with specified name or None.

get_generator(name)

Get Sequence by name.

Parameters:name (string) – Sequence name. Returns:Sequence with specified name or None.

get_index(name)

Get Index by name.

Parameters:name (string) – Index name. Returns:Index with specified name or None.

get_metadata_ddl(sections=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 21, 23, 24, 25])

Returns list of DDL SQL commands for creation of specified categories of database objects.

param list sections:  List of section identifiers. returns:List with SQL commands.

Sections identifiers are represented by SCRIPT_* contants defined in schema module.

Sections are created in the order of occerence in list. Uses SCRIPT_DEFAULT_ORDER list when sections are not specified.

get_package(name)

Get Package by name.

Parameters:name (string) – Package name. Returns:Package with specified name or None.

get_privileges_of(user, user_type=None)

Get list of all privileges granted to user/database object.

Parameters:

• user – User name or instance of class that represents possible user. Allowed classes are User, Table, View, Procedure, Trigger or Role.
• user_type (int) – Required if user is provided as string name. Numeric code for user type, see Schema.enum_object_types.

Returns:

List of Privilege objects.

Raises ProgrammingError:  

For unknown user_type code.

get_procedure(name)

Get Procedure by name.

Parameters:name (string) – Procedure name. Returns:Procedure with specified name or None.

get_role(name)

Get Role by name.

Parameters:name (string) – Role name. Returns:Role with specified name or None.

get_sequence(name)

Get Sequence by name.

Parameters:name (string) – Sequence name. Returns:Sequence with specified name or None.

get_table(name)

Get Table by name.

Parameters:name (string) – Table name. Returns:Table with specified name or None.

get_trigger(name)

Get Trigger by name.

Parameters:name (string) – Trigger name. Returns:Trigger with specified name or None.

get_view(name)

Get View by name.

Parameters:name (string) – View name. Returns:View with specified name or None.

ismultifile()

Returns true if database has multiple files.

reload(data=None)

Drop all or specified category of cached metadata objects, so they’re reloaded from database on next reference.

Parameters:data (string) – None or name of metadata category.

Recognized (case insensitive) names of metadata categories:

• tables
• views
• domain
• indices
• dependencies
• generators
• sequences
• triggers
• procedures
• constraints
• collations
• character sets
• exceptions
• roles
• functions
• files
• shadows
• privileges
• users
• packages
• backup_history
• filters

Raises ProgrammingError:  For undefined metadata category.

Note

Also commits query transaction.

backup_history None

List of all nbackup hisotry records. Items are BackupHistory objects.

character_sets None

List of all character sets in database. Items are CharacterSet objects.

closed None

True if link to Connection is closed.

collations None

List of all collations in database. Items are Collation objects.

constraints None

List of all constraints in database. Items are Constraint objects.

default_character_set None

Default CharacterSet for database

dependencies None

List of all dependencies in database. Items are Dependency objects.

description None

Database description or None if it doesn’t have a description.

domains None

List of all user domains in database. Items are Domain objects.

enum_character_set_names = {}

Character set names: key = numID, value = charset_name

enum_determinism_flags = {}

Determinism flags: numID, value = flag_name

enum_field_subtypes = {}

Field sub types: key = numID, value = type_name

enum_field_types = {}

Field types: key = numID, value = type_name

enum_function_types = {}

Function types: key = numID, value = type_name

enum_grant_options = {}

Grant option: key = numID, value = option_name

enum_index_activity_flags = {}

Index activity status: key = numID, value = flag_name

enum_index_unique_flags = {}

Index uniqueness: key = numID, value = flag_name

enum_legacy_flags = {}

Legacy flags: numID, value = flag_name

enum_mechanism_types = {}

Mechanism Types: key = numID, value = type_name

enum_object_type_codes = {}

Object type codes: key = type_name, value = numID

enum_object_types = {}

Object types: key = numID, value = type_name

enum_page_types = {}

Page type: key = numID, value = type_name

enum_param_type_from = {0: 'DATATYPE', 1: 'DOMAIN', 2: 'TYPE OF DOMAIN', 3: 'TYPE OF COLUMN'}

Datatype declaration methods for procedure parameters: key = numID, value = name

enum_parameter_mechanism_types = {}

Parameter Mechanism Types: key = numID, value = type_name

enum_parameter_types = {}

Parameter Types: key = numID, value = type_name

enum_privacy_flags = {}

Privacy flags: numID, value = flag_name

enum_procedure_types = {}

Procedure Types: key = numID, value = type_name

enum_relation_types = {}

Relation Types: key = numID, value = type_name

enum_system_flag_types = {}

System Flag Types: key = numID, value = type_name

enum_transaction_state_types = {}

Transaction State Types: key = numID, value = type_name

enum_trigger_activity_flags = {}

Trigger activity status: key = numID, value = flag_name_name

enum_trigger_types = {}

Trigger Types: key = numID, value = type_name

exceptions None

List of all exceptions in database. Items are DatabaseException objects.

files None

List of all extension files defined for database. Items are DatabaseFile objects.

filters None

List of all user-defined BLOB filters. Items are Filter objects.

functions None

List of all user functions defined in database. Items are Function objects.

generators None

List of all user generators in database. Items are Sequence objects.

indices None

List of all user indices in database. Items are Index objects.

linger None

Database linger value.

opt_always_quote = False

option switch: Always quote db object names on output

opt_generator_keyword = 'SEQUENCE'

option switch: Keyword for generator/sequence

owner_name None

Database owner name.

packages None

List of all packages defined for database. Items are Package objects.

privileges None

List of all privileges defined for database. Items are Privilege objects.

procedures None

List of all user procedures in database. Items are Procedure objects.

roles None

List of all roles in database. Items are Role objects.

security_class None

Can refer to the security class applied as databasewide access control limits.

sequences None

List of all user generators in database. Items are Sequence objects.

shadows None

List of all shadows defined for database. Items are Shadow objects.

sysdomains None

List of all system domains in database. Items are Domain objects.

sysfunctions None

List of all system functions defined in database. Items are Function objects.

sysgenerators None

List of all system generators in database. Items are Sequence objects.

sysindices None

List of all system indices in database. Items are Index objects.

sysprocedures None

List of all system procedures in database. Items are Procedure objects.

syssequences None

List of all system generators in database. Items are Sequence objects.

systables None

List of all system tables in database. Items are Table objects.

systriggers None

List of all system triggers in database. Items are Trigger objects.

sysviews None

List of all system views in database. Items are View objects.

tables None

List of all user tables in database. Items are Table objects.

triggers None

List of all user triggers in database. Items are Trigger objects.

views None

List of all user views in database. Items are View objects.

BaseSchemaItem

class fdb.schema.BaseSchemaItem(schema, attributes)

Base class for all database schema objects.

accept_visitor(visitor)

Visitor Pattern support. Calls visitMetadatItem(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

name None

Database object name or None if object doesn’t have a name.

schema = None

Weak reference to parent Schema instance.

Collation

class fdb.schema.Collation(schema, attributes)

Represents collation.

Supported SQL actions:

• User collation: create, drop, comment
• System collation: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitCollation(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

isaccentinsensitive()

Returns True if collation has ACCENT INSENSITIVE attribute.

isbasedonexternal()

Returns True if collation is based on external collation definition.

iscaseinsensitive()

Returns True if collation has CASE INSENSITIVE attribute.

ispadded()

Returns True if collation has PAD SPACE attribute.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

attributes None

Collation attributes.

base_collation None

Base Collation object that’s extended by this one or None.

character_set None

Character set object associated with collation.

description None

Database object description or None if object doesn’t have a description.

function_name None

Not currently used.

id None

Collation ID.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Creator user name.

schema = None

security_class None

Security class name or None.

specific_attributes None

Collation specific attributes.

CharacterSet

class fdb.schema.CharacterSet(schema, attributes)

Represents character set.

Supported SQL actions: alter(collation=Collation instance or collation name), comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitCharacterSet(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_collation(name)

Return Collation object with specified name that belongs to this character set.

get_collation_by_id(id)

Return Collation object with specified id that belongs to this character set.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

bytes_per_character None

Size of characters in bytes.

collations None

List of Collations associated with character set.

default_collate None

Collate object of default collate.

description None

Database object description or None if object doesn’t have a description.

id None

Character set ID.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Creator user name.

schema = None

security_class None

Security class name or None.

DatabaseException

class fdb.schema.DatabaseException(schema, attributes)

Represents database exception.

Supported SQL actions:

• User exception: create, recreate, alter(message=string), create_or_alter, drop, comment
• System exception: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitException(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

id None

System-assigned unique exception number.

message None

Custom message text.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Creator user name.

schema = None

security_class None

Security class name or None.

Sequence

class fdb.schema.Sequence(schema, attributes)

Represents database generator/sequence.

Supported SQL actions:

• User sequence: create, alter(value=number), drop, comment
• System sequence: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitGenerator(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

isidentity()

Returns True for system generators created for IDENTITY columns.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

id None

Internal ID number of the sequence.

increment None

Sequence increment.

inital_value None

Initial sequence value.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Creator user name.

schema = None

security_class None

Security class name or None.

value None

Current sequence value.

Index

class fdb.schema.Index(schema, attributes)

Represents database index.

Supported SQL actions:

• User index: create, activate, deactivate, recompute, drop, comment
• System index: recompute, comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitIndex(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

isenforcer()

Returns True if index is used to enforce a constraint.

isexpression()

Returns True if index is expression index.

isinactive()

Returns True if index is INACTIVE.

issystemobject()

Returns True if this database object is system object.

isunique()

Returns True if index is UNIQUE.

actions None

List of supported SQL operations on metadata object instance.

constraint None

Constraint instance that uses this index or None.

description None

Database object description or None if object doesn’t have a description.

expression None

Source of an expression or None.

id None

Internal number ID of the index.

index_type None

ASCENDING or DESCENDING.

name None

Database object name or None if object doesn’t have a name.

partner_index None

Associated unique/primary key Index instance, or None.

schema = None

segment_names None

List of index segment names.

segment_statistics None

List of index segment statistics (for ODS 11.1 and higher).

segments None

List of index segments as TableColumn instances.

statistics None

Latest selectivity of the index.

table None

The Table instance the index applies to.

TableColumn

class fdb.schema.TableColumn(schema, table, attributes)

Represents table column.

Supported SQL actions:

• User column: alter(name=string,datatype=string_SQLTypeDef,position=number,

  expression=computed_by_expr,restart=None_or_init_value), drop, comment

• System column: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitTableColumn(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_computedby()

Returns (string) extression for column computation or None.

get_dependencies()

Return list of database objects that this object depend on.

get_dependents()

Return list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_default()

Returns True if column has default value.

iscomputed()

Returns True if column is computed.

isdomainbased()

Returns True if column is based on user domain.

isidentity()

Returns True for identity type column.

isnullable()

Returns True if column can accept NULL values.

issystemobject()

Returns True if this database object is system object.

iswritable()

Returns True if column is writable (i.e. it’s not computed etc.).

actions None

List of supported SQL operations on metadata object instance.

collation None

Collation object or None.

datatype None

Comlete SQL datatype definition.

default None

Default value for column or None.

description None

Database object description or None if object doesn’t have a description.

domain None

Domain object this column is based on.

generator None

Internal flags.

identity_type None

Internal flags.

name None

Database object name or None if object doesn’t have a name.

position None

Column’s sequence number in row.

privileges None

List of Privilege objects granted to this object.

schema = None

security_class None

Security class name or None.

table None

The Table object this column belongs to.

ViewColumn

class fdb.schema.ViewColumn(schema, view, attributes)

Represents view column.

Supported SQL actions: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitViewColumn(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Return list of database objects that this object depend on.

get_dependents()

Return list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

isnullable()

Returns True if column is NULLABLE.

issystemobject()

Returns True if this database object is system object.

iswritable()

Returns True if column is writable.

actions None

List of supported SQL operations on metadata object instance.

base_field None

The source column from the base relation. Result could be either TableColumn, ViewColumn or ProcedureParameter instance or None.

collation None

Collation object or None.

datatype None

Comlete SQL datatype definition.

description None

Database object description or None if object doesn’t have a description.

domain None

Domain object this column is based on.

name None

Database object name or None if object doesn’t have a name.

position None

Column’s sequence number in row.

privileges None

List of Privilege objects granted to this object.

schema = None

security_class None

Security class name or None.

view None

View object this column belongs to.

Domain

class fdb.schema.Domain(schema, attributes)

Represents SQl Domain.

Supported SQL actions:

• User domain: create, alter(name=string,default=string_definition_or_None, check=string_definition_or_None,datatype=string_SQLTypeDef), drop, comment
• System domain: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitDomain(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_default()

Returns True if domain has default value.

isarray()

Returns True if domain defines an array.

iscomputed()

Returns True if domain is computed.

isnullable()

Returns True if domain is not defined with NOT NULL.

issystemobject()

Return True if this database object is system object.

isvalidated()

Returns True if domain has validation constraint.

actions None

List of supported SQL operations on metadata object instance.

character_length None

Length of CHAR and VARCHAR column, in characters (not bytes).

character_set None

CharacterSet object for a character or text BLOB column, or None.

collation None

Collation object for a character column or None.

datatype None

Comlete SQL datatype definition.

default None

Expression that defines the default value or None.

description None

Database object description or None if object doesn’t have a description.

dimensions None

List of dimension definition pairs if column is an array type. Always empty for non-array columns.

expression None

Expression that defines the COMPUTED BY column or None.

external_length None

Length of field as it is in an external table. Always 0 for regular tables.

external_scale None

Scale factor of an integer field as it is in an external table.

external_type None

Data type of the field as it is in an external table.

field_type None

Number code of the data type defined for the column.

length None

Length of the column in bytes.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Creator user name.

precision None

Indicates the number of digits of precision available to the data type of the column.

scale None

Negative number representing the scale of NUMBER and DECIMAL column.

schema = None

security_class None

Security class name or None.

segment_length None

For BLOB columns, a suggested length for BLOB buffers.

sub_type None

BLOB subtype.

validation None

CHECK constraint for the domain or None.

Dependency

class fdb.schema.Dependency(schema, attributes)

Maps dependency between database objects.

Supported SQL actions: none

accept_visitor(visitor)

Visitor Pattern support. Calls visitDependency(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns empty list because Dependency object never has dependencies.

get_dependents()

Returns empty list because Dependency object never has dependents.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

ispackaged()

Returns True if dependency is defined in package.

issystemobject()

Returns True as dependency entries are considered as system objects.

actions None

List of supported SQL operations on metadata object instance.

depended_on None

Database object on which dependent depends.

depended_on_name None

Name of db object on which dependent depends.

depended_on_type None

Type of db object on which dependent depends.

dependent None

Dependent database object.

dependent_name None

Dependent database object name.

dependent_type None

Dependent database object type.

description None

Database object description or None if object doesn’t have a description.

field_name None

Name of one column in depended on object.

name None

Database object name or None if object doesn’t have a name.

package None

Package instance if dependent depends on object in package or None.

schema = None

Constraint

class fdb.schema.Constraint(schema, attributes)

Represents table or column constraint.

Supported SQL actions:

• Constraint on user table except NOT NULL constraint: create, drop
• Constraint on system table: none

accept_visitor(visitor)

Visitor Pattern support. Calls visitConstraint(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

ischeck()

Returns True if it’s CHECK constraint.

isdeferrable()

Returns True if it’s DEFERRABLE constraint.

isdeferred()

Returns True if it’s INITIALLY DEFERRED constraint.

isfkey()

Returns True if it’s FOREIGN KEY constraint.

isnotnull()

Returns True if it’s NOT NULL constraint.

ispkey()

Returns True if it’s PRIMARY KEY constraint.

issystemobject()

Returns True if this database object is system object.

isunique()

Returns True if it’s UNIQUE constraint.

actions None

List of supported SQL operations on metadata object instance.

column_name None

For a NOT NULL constraint, this is the name of the column to which the constraint applies.

constraint_type None

primary key/unique/foreign key/check/not null.

delete_rule None

For a FOREIGN KEY constraint, this is the action applicable to when primary key is deleted.

description None

Database object description or None if object doesn’t have a description.

index None

Index instance that enforces the constraint. None if constraint is not primary key/unique or foreign key.

match_option None

For a FOREIGN KEY constraint only. Current value is FULL in all cases.

name None

Database object name or None if object doesn’t have a name.

partner_constraint None

For a FOREIGN KEY constraint, this is the unique or primary key Constraint referred.

schema = None

table None

Table instance this constraint applies to.

trigger_names None

For a CHECK constraint contains trigger names that enforce the constraint.

triggers None

For a CHECK constraint contains Trigger instances that enforce the constraint.

update_rule None

For a FOREIGN KEY constraint, this is the action applicable to when primary key is updated.

Table

class fdb.schema.Table(schema, attributes)

Represents Table in database.

Supported SQL actions:

• User table: create (no_pk=bool,no_unique=bool),

  recreate (no_pk=bool,no_unique=bool), drop, comment

• System table: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitTable(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_column(name)

Return TableColumn object with specified name.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_fkey()

Returns True if table has any FOREIGN KEY constraint.

has_pkey()

Returns True if table has PRIMARY KEY defined.

isexternal()

Returns True if table is external table.

isgtt()

Returns True if table is GLOBAL TEMPORARY table.

ispersistent()

Returns True if table is persistent one.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

columns None

Returns list of columns defined for table. Items are TableColumn objects.

constraints None

Returns list of constraints defined for table. Items are Constraint objects.

dbkey_length None

Length of the RDB$DB_KEY column in bytes.

default_class None

Default security class.

description None

Database object description or None if object doesn’t have a description.

external_file None

Full path to the external data file, if any.

flags None

Internal flags.

foreign_keys None

List of FOREIGN KEY Constraint instances for this table.

format None

Internal format ID for the table.

id None

Internam number ID for the table.

indices None

Returns list of indices defined for table. Items are Index objects.

name None

Database object name or None if object doesn’t have a name.

owner_name None

User name of table’s creator.

primary_key None

PRIMARY KEY Constraint for this table or None.

privileges None

List of Privilege objects granted to this object.

schema = None

security_class None

Security class that define access limits to the table.

table_type None

Table type.

triggers None

Returns list of triggers defined for table. Items are Trigger objects.

View

class fdb.schema.View(schema, attributes)

Represents database View.

Supported SQL actions:

• User views: create, recreate, alter(columns=string_or_list,query=string,check=bool), create_or_alter, drop, comment
• System views: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitView(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_column(name)

Return TableColumn object with specified name.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

get_trigger(name)

Return Trigger object with specified name.

has_checkoption()

Returns True if View has WITH CHECK OPTION defined.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

columns None

Returns list of columns defined for view. Items are ViewColumn objects.

dbkey_length None

Length of the RDB$DB_KEY column in bytes.

default_class None

Default security class.

description None

Database object description or None if object doesn’t have a description.

flags None

Internal flags.

format None

Internal format ID for the view.

id None

Internal number ID for the view.

name None

Database object name or None if object doesn’t have a name.

owner_name None

User name of view’s creator.

privileges None

List of Privilege objects granted to this object.

schema = None

security_class None

Security class that define access limits to the view.

sql None

The query specification.

triggers None

Returns list of triggers defined for view. Items are Trigger objects.

Trigger

class fdb.schema.Trigger(schema, attributes)

Represents trigger.

Supported SQL actions:

• User trigger: create(inactive=bool), recreate, create_or_alter, drop, alter(fire_on=string,active=bool,sequence=int,declare=string_or_list, code=string_or_list), comment
• System trigger: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitTrigger(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

get_type_as_string()

Return string with action and operation specification.

isactive()

Returns True if this trigger is active.

isafter()

Returns True if this trigger is set for AFTER action.

isbefore()

Returns True if this trigger is set for BEFORE action.

isdbtrigger()

Returns True if this trigger is database trigger.

isddltrigger()

Returns True if this trigger is DDL trigger.

isdelete()

Returns True if this trigger is set for DELETE operation.

isinsert()

Returns True if this trigger is set for INSERT operation.

issystemobject()

Returns True if this database object is system object.

isupdate()

Returns True if this trigger is set for UPDATE operation.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

engine_name None

Engine name.

entrypoint None

Entrypoint.

flags None

Internal flags.

name None

Database object name or None if object doesn’t have a name.

relation None

Table or View that the trigger is for, or None for database triggers

schema = None

sequence None

Sequence (position) of trigger. Zero usually means no sequence defined.

source None

PSQL source code.

trigger_type None

Numeric code for trigger type that define what event and when are covered by trigger.

valid_blr None

Trigger BLR invalidation flag. Coul be True/False or None.

ProcedureParameter

class fdb.schema.ProcedureParameter(schema, proc, attributes)

Represents procedure parameter.

Supported SQL actions: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitProcedureParameter(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_definition()

Returns SQL definition for parameter.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_default()

Returns True if parameter has default value.

isinput()

Returns True if parameter is INPUT parameter.

isnullable()

Returns True if parameter allows NULL.

ispackaged()

Returns True if procedure parameter is defined in package.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

collation None

collation for this parameter.

column None

TableColumn for this parameter.

datatype None

Comlete SQL datatype definition.

default None

Default value.

description None

Database object description or None if object doesn’t have a description.

domain None

Domain for this parameter.

mechanism None

Parameter mechanism code.

name None

Database object name or None if object doesn’t have a name.

package None

Package this procedure belongs to. Object is Package instance or None.

procedure None

Name of the stored procedure.

schema = None

sequence None

Sequence (position) of parameter.

type_from None

Numeric code. See Schema.enum_param_type_from.`

Procedure

class fdb.schema.Procedure(schema, attributes)

Represents stored procedure.

Supported SQL actions:

• User procedure: create(no_code=bool), recreate(no_code=bool), create_or_alter(no_code=bool), drop, alter(input=string_or_list,output=string_or_list,declare=string_or_list, code=string_or_list), comment
• System procedure: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitProcedure(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_param(name)

Returns ProcedureParameter with specified name or None

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_input()

Returns True if procedure has any input parameters.

has_output()

Returns True if procedure has any output parameters.

ispackaged()

Returns True if procedure is defined in package.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

engine_name None

Engine name.

entrypoint None

Entrypoint.

id None

Internal unique ID number.

input_params None

List of input parameters. Instances are ProcedureParameter instances.

name None

Database object name or None if object doesn’t have a name.

output_params None

List of output parameters. Instances are ProcedureParameter instances.

owner_name None

User name of procedure’s creator.

package None

Package this procedure belongs to. Object is Package instance or None.

privacy None

Privacy flag.

privileges None

List of Privilege objects granted to this object.

proc_type None

Procedure type code. See fdb.Connection.enum_procedure_types.

schema = None

security_class None

Security class that define access limits to the procedure.

source None

PSQL source code.

valid_blr None

Procedure BLR invalidation flag. Coul be True/False or None.

Role

class fdb.schema.Role(schema, attributes)

Represents user role.

Supported SQL actions:

• User role: create, drop, comment
• System role: comment

accept_visitor(visitor)

Visitor Pattern support. Calls visitRole(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

name None

Database object name or None if object doesn’t have a name.

owner_name None

User name of role owner.

privileges None

List of Privilege objects granted to this object.

schema = None

security_class None

Security class name or None.

FunctionArgument

class fdb.schema.FunctionArgument(schema, function, attributes)

Represets UDF argument.

Supported SQL actions: none.

accept_visitor(visitor)

Visitor Pattern support. Calls visitFunctionArgument(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_definition()

Returns SQL definition for parameter.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_default()

Returns True if parameter has default value.

isbydescriptor(any=False)

Returns True if argument is passed by descriptor.

Parameters:any (bool) – If True, method returns True if any kind of descriptor is used (including BLOB and ARRAY descriptors).

isbyreference()

Returns True if argument is passed by reference.

isbyvalue()

Returns True if argument is passed by value.

isfreeit()

Returns True if (return) argument is declared as FREE_IT.

isnullable()

Returns True if parameter allows NULL.

ispackaged()

Returns True if function argument is defined in package.

isreturning()

Returns True if argument represents return value for function.

issystemobject()

Returns True if this database object is system object.

iswithnull()

Returns True if argument is passed by reference with NULL support.

actions None

List of supported SQL operations on metadata object instance.

argument_mechanism None

Argiment mechanism.

argument_name None

Argument name.

character_length None

Length of CHAR and VARCHAR column, in characters (not bytes).

character_set None

CharacterSet for a character/text BLOB argument, or None.

collation None

collation for this parameter.

column None

TableColumn for this parameter.

datatype None

Comlete SQL datatype definition.

default None

Default value.

description None

Database object description or None if object doesn’t have a description.

domain None

Domain for this parameter.

field_type None

Number code of the data type defined for the argument.

function None

Function to which this argument belongs.

length None

Length of the argument in bytes.

mechanism None

How argument is passed.

name None

Database object name or None if object doesn’t have a name.

package None

Package this function belongs to. Object is Package instance or None.

position None

Argument position.

precision None

Indicates the number of digits of precision available to the data type of the argument.

scale None

Negative number representing the scale of NUMBER and DECIMAL argument.

schema = None

sub_type None

BLOB subtype.

type_from None

Numeric code. See Schema.enum_param_type_from.`

Function

class fdb.schema.Function(schema, attributes)

Represents user defined function.

Supported SQL actions:

• External UDF: declare, drop, comment

• PSQL UDF (FB 3, not declared in package): create(no_code=bool),

  recreate(no_code=bool), create_or_alter(no_code=bool), drop, alter(arguments=string_or_list,returns=string,declare=string_or_list, code=string_or_list)

• System UDF: none

accept_visitor(visitor)

Visitor Pattern support. Calls visitFunction(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_arguments()

Returns True if function has input arguments.

has_return()

Returns True if function returns a value.

has_return_argument()

Returns True if function returns a value in input argument.

isexternal()

Returns True if function is external UDF, False for PSQL functions.

ispackaged()

Returns True if function is defined in package.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

arguments None

List of function arguments. Items are FunctionArgument instances.

description None

Database object description or None if object doesn’t have a description.

deterministic_flag None

Deterministic flag.

engine_mame None

Engine name.

entrypoint None

Entrypoint in module.

id None

Function ID.

legacy_flag None

Legacy flag.

module_name None

Module name.

name None

Database object name or None if object doesn’t have a name.

owner_name None

Owner name.

package None

Package this function belongs to. Object is Package instance or None.

private_flag None

Private flag.

returns None

Returning FunctionArgument or None.

schema = None

security_class None

Security class.

source None

Function source.

valid_blr None

BLR validity flag.

DatabaseFile

class fdb.schema.DatabaseFile(schema, attributes)

Represents database extension file.

Supported SQL actions: create

accept_visitor(visitor)

Visitor Pattern support. Calls visitDatabaseFile(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

filename None

File name.

length None

File length in pages.

name None

Database object name or None if object doesn’t have a name.

schema = None

sequence None

File sequence number.

start None

File start page number.

Shadow

class fdb.schema.Shadow(schema, attributes)

Represents database shadow.

Supported SQL actions: create, drop(preserve=bool)

accept_visitor(visitor)

Visitor Pattern support. Calls visitShadow(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

isconditional()

Returns True if it’s CONDITIONAL shadow.

isinactive()

Returns True if it’s INACTIVE shadow.

ismanual()

Returns True if it’s MANUAL shadow.

issystemobject()

Returns False.

SHADOW_CONDITIONAL = 16

SHADOW_INACTIVE = 2

SHADOW_MANUAL = 4

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

files None

List of shadow files. Items are DatabaseFile instances.

flags None

Shadow flags.

id None

Shadow ID number.

name None

Database object name or None if object doesn’t have a name.

schema = None

Privilege

class fdb.schema.Privilege(schema, attributes)

Represents priviledge to database object.

Supported SQL actions: grant(grantors),revoke(grantors,grant_option)

accept_visitor(visitor)

Visitor Pattern support. Calls visitPrivilege(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_grant()

Returns True if privilege comes with GRANT OPTION.

isdelete()

Returns True if this is DELETE privilege.

isexecute()

Returns True if this is EXECUTE privilege.

isinsert()

Returns True if this is INSERT privilege.

ismembership()

Returns True if this is ROLE membership privilege.

isreference()

Returns True if this is REFERENCE privilege.

isselect()

Returns True if this is SELECT privilege.

issystemobject()

Returns True.

isupdate()

Returns True if this is UPDATE privilege.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

field_name None

Field name.

grantor None

Grantor User object.

grantor_name None

Grantor name.

name None

Database object name or None if object doesn’t have a name.

privilege None

Privilege code.

schema = None

subject None

Priviledge subject. Either Role, Table, View or Procedure object.

subject_name None

Subject name.

subject_type None

Subject type.

user None

Grantee. Either User, Role, Procedure, Trigger or View object.

user_name None

User name.

user_type None

User type.

Package

class fdb.schema.Package(schema, attributes)

Represents PSQL package.

Supported SQL actions: create(body=bool), recreate(body=bool), create_or_alter,

alter(header=string_or_list), drop(body=bool),alter

accept_visitor(visitor)

Visitor Pattern support. Calls visitProcedure(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

has_valid_body()

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

body None

Package body source.

description None

Database object description or None if object doesn’t have a description.

functions None

List of package functions. Items are Function instances.

header None

Package header source.

name None

Database object name or None if object doesn’t have a name.

owner_name None

User name of package creator.

procedures None

List of package procedures. Items are Procedure instances.

schema = None

security_class None

Security class name or None.

BackupHistory

class fdb.schema.BackupHistory(schema, attributes)

Represents entry of history for backups performed using the nBackup utility.

Supported SQL actions: None

accept_visitor(visitor)

Visitor Pattern support. Calls visitBackupHistory(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True.

actions None

List of supported SQL operations on metadata object instance.

backup_id None

The identifier assigned by the engine.

created None

Backup date and time.

description None

Database object description or None if object doesn’t have a description.

filename None

Full path and file name of backup file.

guid None

Unique identifier.

level None

Backup level.

name None

Database object name or None if object doesn’t have a name.

schema = None

scn None

System (scan) number.

Filter

class fdb.schema.Filter(schema, attributes)

Represents userdefined BLOB filter.

Supported SQL actions:

• BLOB filter: declare, drop, comment
• System UDF: none

accept_visitor(visitor)

Visitor Pattern support. Calls visitFilter(self) on parameter object.

Parameters:visitor – Visitor object of Vistior Pattern.

get_dependencies()

Returns list of database objects that this object depend on.

get_dependents()

Returns list of all database objects that depend on this one.

get_quoted_name()

Returns quoted (if necessary) name.

get_sql_for(action, **params)

Returns SQL command for specified action on metadata object.

Supported actions are defined by actions list.

Raises ProgrammingError:  For unsupported action or wrong parameters passed.

issystemobject()

Returns True if this database object is system object.

actions None

List of supported SQL operations on metadata object instance.

description None

Database object description or None if object doesn’t have a description.

entrypoint None

The exported name of the BLOB filter in the filter library.

input_sub_type None

The BLOB subtype of the data to be converted by the function.

module_name None

The name of the dynamic library or shared object where the code of the BLOB filter is located.

name None

Database object name or None if object doesn’t have a name.

output_sub_type None

The BLOB subtype of the converted data.

schema = None

SchemaVisitor

class fdb.schema.SchemaVisitor

Helper class for implementation of schema Visitor.

Implements all visit* methods supported by schema classes as calls to default_action().

default_action(obj)

Does nothing.

visitCharacterSet(character_set)

visitCollation(collation)

visitConstraint(constraint)

visitDatabaseFile(dbfile)

visitDependency(dependency)

visitDomain(domain)

visitException(exception)

visitFunction(function)

visitFunctionArgument(arg)

visitGenerator(generator)

visitIndex(index)

visitMetadataItem(item)

visitPackage(package)

visitProcedure(procedure)

visitProcedureParameter(param)

visitRole(role)

visitSchema(schema)

visitShadow(shadow)

visitTable(table)

visitTableColumn(column)

visitTrigger(trigger)

visitView(view)

visitViewColumn(column)

Monitoring information

Constants

fdb.monitor.SHUTDOWN_MODE_ONLINE

fdb.monitor.SHUTDOWN_MODE_MULTI

fdb.monitor.SHUTDOWN_MODE_SINGLE

fdb.monitor.SHUTDOWN_MODE_FULL

Shutdown modes for DatabaseInfo.shutdown_mode.

fdb.monitor.BACKUP_STATE_NORMAL

fdb.monitor.BACKUP_STATE_STALLED

fdb.monitor.BACKUP_STATE_MERGE

Backup states for DatabaseInfo.backup_state.

fdb.monitor.STATE_IDLE

fdb.monitor.STATE_ACTIVE

States for AttachmentInfo.state, TransactionInfo.state. and StatementInfo.state.

fdb.monitor.ISOLATION_CONSISTENCY

fdb.monitor.ISOLATION_CONCURRENCY

fdb.monitor.ISOLATION_READ_COMMITTED_RV

fdb.monitor.ISOLATION_READ_COMMITTED_NO_RV

Isolation modes for TransactionInfo.isolation_mode.

fdb.monitor.INFINITE_WAIT

fdb.monitor.NO_WAIT

Special timeout values for TransactionInfo.lock_timeout.

fdb.monitor.STAT_DATABASE

fdb.monitor.STAT_ATTACHMENT

fdb.monitor.STAT_TRANSACTION

fdb.monitor.STAT_STATEMENT

fdb.monitor.STAT_CALL

Group codes for IOStatsInfo.group.

Monitor

class fdb.monitor.Monitor

Class for access to Firebird monitoring tables.

bind(connection)

Bind this instance to specified Connection.

Parameters:connection – Connection instance. Raises ProgrammingError:  If Monitor object was set as internal (via _set_as_internal()) or database has ODS lower than 11.1.

clear()

Drop all cached information objects. Force reload of fresh monitoring information on next reference.

close()

Sever link to Connection.

Raises ProgrammingError:  If Monitor object was set as internal (via _set_as_internal()).

get_attachment(id)

Get AttachmentInfo by ID.

Parameters:id (int) – Attachment ID. Returns:AttachmentInfo with specified ID or None.

get_call(id)

Get CallStackInfo by ID.

Parameters:id (int) – Callstack ID. Returns:CallStackInfo with specified ID or None.

get_statement(id)

Get StatementInfo by ID.

Parameters:id (int) – Statement ID. Returns:StatementInfo with specified ID or None.

get_transaction(id)

Get TransactionInfo by ID.

Parameters:id (int) – Transaction ID. Returns:TransactionInfo with specified ID or None.

refresh()

Reloads fresh monitoring information.

attachments None

List of all attachments. Items are AttachmentInfo objects.

callstack None

List with complete call stack. Items are CallStackInfo objects.

closed None

True if link to Connection is closed.

db None

DatabaseInfo object for attached database.

iostats None

List of all I/O statistics. Items are IOStatsInfo objects.

statements None

List of all statements. Items are StatementInfo objects.

tablestats None

List of all table record I/O statistics. Items are TableStatsInfo objects.

this_attachment None

AttachmentInfo object for current connection.

transactions None

List of all transactions. Items are TransactionInfo objects.

variables None

List of all context variables. Items are ContextVariableInfo objects.

BaseInfoItem

class fdb.monitor.BaseInfoItem(monitor, attributes)

Base class for all database monitoring objects.

monitor = None

Weak reference to parent Monitor instance.

stat_id None

Internal ID.

DatabaseInfo

class fdb.monitor.DatabaseInfo(monitor, attributes)

Information about attached database.

backup_state None

Current state of database with respect to nbackup physical backup.

cache_size None

Number of pages allocated in the page cache.

created None

Creation date and time, i.e., when the database was created or last restored.

crypt_page None

Number of page being encrypted.

forced_writes None

True if database uses synchronous writes.

iostats None

IOStatsInfo for this object.

monitor = None

name None

Database pathname or alias.

next_transaction None

Transaction ID of the next transaction that will be started.

oat None

Transaction ID of the oldest active transaction.

ods None

On-Disk Structure (ODS) version number.

oit None

Transaction ID of the oldest [interesting] transaction.

ost None

Transaction ID of the Oldest Snapshot, i.e., the number of the OAT when the last garbage collection was done.

owner None

User name of database owner.

page_size None

Size of database page in bytes.

pages None

Number of pages allocated on disk.

read_only None

True if database is Read Only.

reserve_space None

True if database reserves space on data pages.

security_database None

TYpe of security database (Default, Self or Other).

shutdown_mode None

Current shutdown mode.

sql_dialect None

SQL dialect of the database.

stat_id None

Internal ID.

sweep_interval None

The sweep interval configured in the database header. Value 0 indicates that sweeping is disabled.

tablestats None

Dictionary of TableStatsInfo instances for this object.

AttachmentInfo

class fdb.monitor.AttachmentInfo(monitor, attributes)

Information about attachment (connection) to database.

isactive()

Returns True if attachment is active.

isgcallowed()

Returns True if Garbage Collection is enabled for this attachment.

isidle()

Returns True if attachment is idle.

isinternal()

Returns True if attachment is internal system attachment.

terminate()

Terminates client session associated with this attachment.

Raises ProgrammingError:  If database has ODS lower than 11.2 or this attachement is current session.

auth_method None

Authentication method.

character_set None

CharacterSet for this attachment.

client_version None

Client library version.

id None

Attachment ID.

iostats None

IOStatsInfo for this object.

monitor = None

name None

Database pathname or alias.

remote_address None

Remote address.

remote_host None

Name of remote host.

remote_os_user None

OS user name of client process.

remote_pid None

Remote client process ID.

remote_process None

Remote client process pathname.

remote_protocol None

Remote protocol name.

remote_version None

Remote protocol version.

role None

Role name.

server_pid None

Server process ID.

stat_id None

Internal ID.

state None

Attachment state (idle/active).

statements None

List of statements associated with attachment. Items are StatementInfo objects.

tablestats None

Dictionary of TableStatsInfo instances for this object.

timestamp None

Attachment date/time.

transactions None

List of transactions associated with attachment. Items are TransactionInfo objects.

user None

User name.

variables None

List of variables associated with attachment. Items are ContextVariableInfo objects.

TransactionInfo

class fdb.monitor.TransactionInfo(monitor, attributes)

Information about transaction.

isactive()

Returns True if transaction is active.

isautocommit()

Returns True for autocommited transaction.

isautoundo()

Returns True for transaction with automatic undo.

isidle()

Returns True if transaction is idle.

isreadonly()

Returns True if transaction is Read Only.

attachment None

AttachmentInfo instance to which this transaction belongs.

id None

Transaction ID.

iostats None

IOStatsInfo for this object.

isolation_mode None

Transaction isolation mode code.

lock_timeout None

Lock timeout.

monitor = None

oldest None

Oldest transaction (local OIT).

oldest_active None

Oldest active transaction (local OAT).

stat_id None

Internal ID.

state None

Transaction state (idle/active).

statements None

List of statements associated with transaction. Items are StatementInfo objects.

tablestats None

Dictionary of TableStatsInfo instances for this object.

timestamp None

Transaction start date/time.

top None

Top transaction.

variables None

List of variables associated with transaction. Items are ContextVariableInfo objects.

StatementInfo

class fdb.monitor.StatementInfo(monitor, attributes)

Information about executed SQL statement.

isactive()

Returns True if statement is active.

isidle()

Returns True if statement is idle.

terminate()

Terminates execution of statement.

Raises ProgrammingError:  If this attachement is current session.

attachment None

AttachmentInfo instance to which this statement belongs.

callstack None

List with call stack for statement. Items are CallStackInfo objects.

id None

Statement ID.

iostats None

IOStatsInfo for this object.

monitor = None

plan None

Explained execution plan.

sql_text None

Statement text, if appropriate.

stat_id None

Internal ID.

state None

Statement state (idle/active).

tablestats None

Dictionary of TableStatsInfo instances for this object.

timestamp None

Statement start date/time.

transaction None

TransactionInfo instance to which this statement belongs or None.

CallStackInfo

class fdb.monitor.CallStackInfo(monitor, attributes)

Information about PSQL call (stack frame).

caller None

Call stack entry (CallStackInfo) of the caller.

column None

SQL source column number.

dbobject None

PSQL object. Procedure or Trigger instance.

id None

Call ID.

iostats None

IOStatsInfo for this object.

line None

SQL source line number.

monitor = None

package_name None

Package name.

stat_id None

Internal ID.

statement None

Top-level StatementInfo instance to which this call stack entry belongs.

timestamp None

Request start date/time.

IOStatsInfo

class fdb.monitor.IOStatsInfo(monitor, attributes)

Information about page and row level I/O operations, and about memory consumption.

backouts None

Number of records where a new primary record version or a change to an existing primary record version is backed out due to rollback or savepoint undo.

backversion_reads None

Number of record backversion reads.

conflits None

Number of record conflits.

deletes None

Number of deleted records.

expunges None

Number of records where record version chain is being deleted due to deletions by transactions older than OAT.

fetches None

Number of page fetches.

fragment_reads None

Number of record fragment reads.

group None

Object group code.

idx_reads None

Number of records read via an index.

inserts None

Number of inserted records.

locks None

Number of record locks.

marks None

Number of pages with changes pending.

max_memory_allocated None

Maximum number of bytes allocated from the operating system by this object.

max_memory_used None

Maximum number of bytes used by this object.

memory_allocated None

Number of bytes currently allocated at the OS level.

memory_used None

Number of bytes currently in use.

monitor = None

owner None

Object that owns this IOStats instance. Could be either DatabaseInfo, AttachmentInfo, TransactionInfo, StatementInfo or CallStackInfo instance.

purges None

Number of records where record version chain is being purged of versions no longer needed by OAT or younger transactions.

reads None

Number of page reads.

repeated_reads None

Number of repeated record reads.

seq_reads None

Number of records read sequentially.

stat_id None

Internal ID.

updates None

Number of updated records.

waits None

Number of record waits.

writes None

Number of page writes.

ContextVariableInfo

class fdb.monitor.ContextVariableInfo(monitor, attributes)

Information about context variable.

isattachmentvar()

Returns True if variable is associated to attachment context.

istransactionvar()

Returns True if variable is associated to transaction context.

attachment None

AttachmentInfo instance to which this context variable belongs or None.

monitor = None

name None

Context variable name.

stat_id None

Internal ID.

transaction None

TransactionInfo instance to which this context variable belongs or None.

value None

Value of context variable.

Utilities

Functions

fdb.utils.update_meta(self, other)

Helper function for LateBindingProperty class.

fdb.utils.iter_class_properties(cls)

Iterator that yields name, property pairs for all properties in class.

Parameters:cls (class) – Class object.

fdb.utils.iter_class_variables(cls)

Iterator that yields names of all non-callable attributes in class.

Parameters:cls (class) – Class object.

fdb.utils.embed_attributes(from_class, attr)

Class decorator that injects properties and non-callable attributes from another class instance embedded in class instances.

param class from_class:  Class that should extend decorated class. param string attr:  Attribute name that holds instance of embedded class within decorated class instance.

LateBindingProperty

class fdb.utils.LateBindingProperty

Peroperty class that binds to getter/setter/deleter methods when instance of class that define the property is created. This allows you to override these methods in descendant classes (if they are not private) without necessity to redeclare the property itself in descendant class.

Recipe from Tim Delaney, 2005/03/31 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/408713

class C(object):

    def getx(self):
        print 'C.getx'
        return self._x

    def setx(self, x):
        print 'C.setx'
        self._x = x

    def delx(self):
        print 'C.delx'
        del self._x

    x = LateBindingProperty(getx, setx, delx)

class D(C):

    def setx(self, x):
        print 'D.setx'
        super(D, self).setx(x)

    def delx(self):
        print 'D.delx'
        super(D, self).delx()

c = C()
c.x = 1
c.x
c.x
del c.x

print

d = D()
d.x = 1
d.x
d.x
del d.x

This has the advantages that:

1. You get back an actual property object (with attendant memory savings, performance increases, etc);
2. It’s the same syntax as using property(fget, fset, fdel, doc) except for the name;
3. It will fail earlier (when you define the class as opposed to when you use it).
4. It’s shorter ;)
5. If you inspect the property you will get back functions with the correct __name__, __doc__, etc.

Iterator

class fdb.utils.Iterator(method, sentinel=None)

Generic iterator implementation.

Parameters:

• method – Callable without parameters that returns next item.
• sentinel – Value that when returned by method indicates the end of sequence.

next()

EmbeddedProperty

class fdb.utils.EmbeddedProperty(obj, prop)

Property class that forwards calls to getter/setter/deleter methods to respective property methods of another object. This class allows you to “inject” properties from embedded object into class definition of parent object.

Parameters:

• obj (string) – Attribute name with embedded object.
• prop (property) – Property instance from embedded object.

EmbeddedAttribute

class fdb.utils.EmbeddedAttribute(obj, attr)

Property class that gets/sets attribute of another object. This class allows you to “inject” attributes from embedded object into class definition of parent object.

Parameters:

• obj (string) – Attribute name with embedded object.
• attr (string) – Attribute name from embedded object.

ctypes interface to Firebird client library

ctypes interface to fbclient.so/dll is defined in submodule fdb.ibase and fdb.blr.

class fdb.ibase.fbclient_API(fb_library_name=None)

Firebird Client API interface object. Loads Firebird Client Library and exposes API functions as member methods. Uses ctypes for bindings.