firebird.driver.config

This module defines the configuration system for the firebird-driver. It uses an INI-style format managed via the DriverConfig class, which allows defining settings for the driver itself, default server/database parameters, and named configurations for specific servers and databases.

Configuration can be loaded from files, strings, or dictionaries, and supports environment variable interpolation. The primary interaction point is usually the global driver_config instance.

Classes

class firebird.driver.config.DriverConfig(name: str)

Bases: Config

Main configuration object for the Firebird driver. Holds global settings, default configurations, and lists of registered servers and databases.

Settings loaded from specific server/database sections override those in the db_defaults and server_defaults sections. When reading multiple files, options from later files override those from earlier ones.

Parameters:

name (str) –

get_database(name: str) → DatabaseConfig

Returns database configuration.

Parameters:

name (str) –

Return type:

DatabaseConfig

get_server(name: str) → ServerConfig

Returns server configuration.

Parameters:

name (str) –

Return type:

ServerConfig

read(filenames: str | Iterable, encoding: str | None = None)

Read configuration from a filename or an iterable of filenames.

Files that cannot be opened are silently ignored; this is designed so that you can specify an iterable of potential configuration file locations (e.g. current directory, user’s home directory, systemwide directory), and all existing configuration files in the iterable will be read. A single filename may also be given.

Return list of successfully read files.

Parameters:

• filenames (str | Iterable) –

• encoding (str | None) –

read_dict(dictionary: dict[str, str]) → None

Read configuration from a dictionary.

Keys are section names, values are dictionaries with keys and values that should be present in the section. If the used dictionary type preserves order, sections and their keys will be added in order.

All types held in the dictionary are converted to strings during reading, including section names, option names and keys.

Parameters:

dictionary (dict[str, str]) –

Return type:

None

read_file(f)

Read configuration from a file-like object.

The f argument must be iterable, returning one line at a time.

read_string(string: str) → None

Read configuration from a given string.

Parameters:

string (str) –

Return type:

None

register_database(name: str, config: str | None = None) → DatabaseConfig

Register database.

Parameters:

• name (str) – Database name.

• config (str | None) – Optional database configuration string in ConfigParser format in [name] section.

Returns:

For newly registered database

Return type:

DatabaseConfig

Raises:

ValueError – If database is already registered.

register_server(name: str, config: str | None = None) → ServerConfig

Register server.

Parameters:

• name (str) – Server name.

• config (str | None) – Optional server configuration string in ConfigParser format in [name] section.

Returns:

For newly registered server

Return type:

ServerConfig

Raises:

ValueError – If server is already registered.

databases: ConfigListOption

Registered databases

db_defaults: DatabaseConfig

Default database configuration (‘firebird.db.defaults’)

fb_client_library: StrOption

Path to Firebird client library

server_defaults: ServerConfig

Default server configuration (‘firebird.server.defaults’)

servers: ConfigListOption

Registered servers

stream_blob_threshold: IntOption

BLOB size threshold. Bigger BLOB will be returned as stream BLOBs.

class firebird.driver.config.ServerConfig(name: str, *, optional: bool = False, description: str | None = None)

Bases: Config

Represents configuration options specific to a named Firebird server entry.

Parameters:

• name (str) –

• optional (bool) –

• description (str | None) –

auth_plugin_list: StrOption

List of authentication plugins override

config: StrOption

Configuration override

encoding: StrOption

Encoding used for text data exchange with server

encoding_errors: StrOption

Handler used for encoding errors. See codecs error handlers for details.

host: StrOption

Server host machine specification

password: StrOption

Default user password, default is envar ISC_PASSWORD or None if not specified

port: StrOption

Port used by Firebird server

trusted_auth: BoolOption

False

Type:

Use trusted authentication, default

user: StrOption

Defaul user name, default is envar ISC_USER or None if not specified

class firebird.driver.config.DatabaseConfig(name: str, *, optional: bool = False, description: str | None = None)

Bases: Config

Represents configuration options specific to a named Firebird database entry, including connection and creation parameters.

Parameters:

• name (str) –

• optional (bool) –

• description (str | None) –

auth_plugin_list: StrOption

List of authentication plugins override

cache_size: IntOption

Page cache size override for database connection

charset: StrOption

Character set for database connection

config: StrOption

Configuration override

database: StrOption

Database file specification or alias

db_cache_size: IntOption

Database create option. Page cache size override for database.

db_charset: StrOption

Database create option. Character set for the database.

db_sql_dialect: IntOption

Database create option. SQL dialect for the database.

decfloat_round: EnumOption

Set DECFLOAT ROUND [Firebird 4], value is DecfloatRound

decfloat_traps: ListOption

Specifies which DECFLOAT exceptional conditions should cause a trap (raise an error) [Firebird 4]. Accepts a list of .DecfloatTraps enum members.

dsn: StrOption

Database connection string

dummy_packet_interval: IntOption

Dummy packet interval for this database connection

forced_writes: BoolOption

Database create option. Write mode (True = sync/False = async).

no_linger: BoolOption

Do not use linger for database connection

page_size: IntOption

Database create option. Page size to be used.

parallel_workers

Number of parallel workers

password: StrOption

Default user password, default is envar ISC_PASSWORD or None if not specified

protocol: EnumOption

Network protocol to use for the connection. Value must be a member of the .NetProtocol enum.

reserve_space: BoolOption

Database create option. Data page space usage (True = reserve space, False = Use all space).

role: StrOption

User role

server: StrOption

Name of server where database is located

session_time_zone: StrOption

Session time zone [Firebird 4]

set_bind: StrOption

Set BIND [Firebird 4]

sql_dialect: IntOption

3

Type:

SQL Dialect for database connection, default

sweep_interval: IntOption

Database create option. Sweep interval for the database.

timeout: IntOption

Connection timeout

trusted_auth: BoolOption

False

Type:

Use trusted authentication, default

user: StrOption

Defaul user name, default is envar ISC_USER or None if not specified

utf8filename: BoolOption

Specifies whether the database parameter (filename) is encoded in UTF-8 when passed to the server.

Globals

firebird.driver.config.driver_config: DriverConfig

Global driver configuration instance. Load settings from files/strings/dicts into this object before connecting, or modify its attributes directly for programmatic configuration.