Skip to content

Working with Services

Database server maintenance tasks such as user management, load monitoring, and database backup have traditionally been automated by scripting the command-line tools gbak, gfix, gsec, and gstat.

The API presented to the client programmer by these utilities is inelegant because they are, after all, command-line tools rather than native components of the client language. To address this problem, Firebird has a facility called the Services API, which exposes a uniform interface to the administrative functionality of the traditional command-line tools.

The native Services API, though consistent, is much lower-level than a Pythonic API. If the native version were exposed directly, accomplishing a given task would probably require more Python code than scripting the traditional command-line tools. For this reason, the firebird-driver presents its own abstraction over the native API.

Services API Connections

All Services API operations are performed in the context of a connection to a specific database server, represented by the Server class. Similarly to database connections, firebird-driver provides connect_server() constructor function to create such connections.

This constructor has one positional and several keyword parameters.

The value of server positional parameter must be one of:

  • name of registered server configuration
  • server host name or address

Keyword parameters are intended to override selected configuration options, or to specify options that are not configurable.

A simple server connection is typically established with code such as this:

from firebird.driver import connect_server

# Attach to 'embedded' server
srv = connect_server('', user='SYSDBA', password='masterkey')

# Attach to 'local' server
srv = connect_server('localhost', user='SYSDBA', password='masterkey')

# Set 'user' and 'password' via configuration
from firebird.driver import driver_config
driver_config.server_defaults.user.value = 'SYSDBA'
driver_config.server_defaults.password.value = 'masterkey'
srv = connect_server('localhost')

However, it's recommended to use specific configuration for servers. It's possible to register servers directly in code like this:

from firebird.driver import connect_server, driver_config

# Register Firebird server
srv_cfg = """[main_server]
host = 192.168.0.15
user = SYSDBA
password = Xyzzy
"""
driver_config.register_server('main_server', srv_cfg)

# Attach to 'main' server
con = connect('main_server')

But more convenient approach is using single configuration file:

# file: myapp.cfg

[firebird.driver]
servers = main_server
databases = employee

[main_server]
host = 192.168.0.15
user = SYSDBA
password = Xyzzy
from firebird.driver import connect_server, driver_config

driver_config.read('myapp.cfg')

# Attach to 'main' server
con = connect('main_server')

Note

Like database connections, it's important to properly close() them when you don't need them anymore.

Server object provides main infrastructure for communication with Firebird server services, and manages number of objects that provide actual server services:

Info

connect_server() and Server for details.

Text output from Services

Some services like ServerDbServices.backup() may return significant amount of text. Rather than return the whole text as single string value by methods that provide access to these services, firebird-driver isolated the transfer process to separate methods:

  • readline() - Returns the next line, None at end of output, or TIMEOUT when query_timeout expires.
  • readline_timed() - Queries one line with an explicit timeout for that call.
  • readlines() - Returns the remaining lines, omitting timeout signals.
  • Iteration over Server object, because Server has built-in support for iterator protocol.
  • Using callback method provided by developer. Each Server method that returns its result asynchronously accepts an optional parameter callback, which must be a function that accepts one string parameter. This method is then called with each output line coming from service.
  • wait() - Waits for Sevice to finish, ignoring rest of the output it may produce.

Important

The Firebird server sends text output from services as packets, that could have two forms. The method for packet construction used for text transfer is controlled by Server.mode attribute with next possible values:

  1. SrvInfoCode.LINE : A single line of text.
  2. SrvInfoCode.TO_EOF : A block of text up to specified (buffer) size.

Both methods have specific pros and cons:

  1. LINE means more roundtrips and thus slower transfer of service output, but each line is sent to client immediately when it's available.
  2. TO_EOF means fewer roundtrips so large output is transferred quickly, but service output is not sent until the transfer buffer is not full, or service stops.

The default mode is TO_EOF with 64K buffer.

Warning

Until output is not fully fetched from service, any attempt to start another asynchronous service will fail with exception! This constraint is set by Firebird Service API.

You may check the status of asynchronous Services using Server.is_running() method.

In cases when you're not interested in output produced by Service, call wait() to wait for service to complete.

Important

Server.query_timeout defaults to -1, so readline() and iteration wait for output indefinitely. Set it to a positive number of seconds for a service that may be quiet, such as trace. On timeout, readline() and iteration return the TIMEOUT sentinel without ending the stream; the next read can still receive output. readlines() skips timeout signals and continues until the service output ends. readline_timed(timeout) remains available when a single line query needs its own timeout.

from firebird.driver import TIMEOUT

srv.query_timeout = 2
line = srv.readline()
if line is TIMEOUT:
    # No output arrived yet; the stream remains open.
    pass
elif line is None:
    # End of output.
    pass
else:
    print(line)

Examples:

from firebird.driver import connect_server
with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    print("Fetch materialized")
    print("==================")
    print("Start backup")
    srv.database.backup(database='employee', backup='employee.fbk')
    print("srv.running is", srv.is_running())
    report = srv.readlines()
    print(f"{len(report)} lines returned")
    print("First 5 lines from output:")
    for i in range(min(5, len(report))):
        print(i,report[i])
    print("srv.running is", srv.is_running())
    print()
    print("Iterate over result")
    print("===================")
    srv.database.backup(database='employee', backup='employee.fbk')
    output = []
    for line in srv:
        output.append(line)
    print(f"{len(output)} lines returned")
    print("Last 5 lines from output:")
    for line in output[-5:]:
        print(line)
    print()
    print("Callback")
    print("========")

    output = []

    # Callback function
    def fetchline(line):
        output.append(line)

    srv.database.backup(database='employee', backup='employee.fbk', callback=fetchline)
    print(f"{len(output)} lines returned")
    print("Last 5 lines from output:")
    for line in output[-5:]:
        print(line)

Output:

Fetch materialized
==================
Start backup
srv.running is True
558 lines returned
First 5 lines from output:
0 gbak:readied database employee for backup
1 gbak:creating file employee.fbk
2 gbak:starting transaction
3 gbak:database employee has a page size of 4096 bytes.
4 gbak:writing domains
srv.running is False

Iterate over result
===================
558 lines returned
Last 5 lines from output:
gbak:writing referential constraints
gbak:writing check constraints
gbak:writing SQL roles
gbak:writing names mapping
gbak:closing file, committing, and finishing. 74752 bytes written

Callback
========
558 lines returned
Last 5 lines from output:
gbak:writing referential constraints
gbak:writing check constraints
gbak:writing SQL roles
gbak:writing names mapping
gbak:closing file, committing, and finishing. 74752 bytes written

Server Configuration and State information

Important

Because the scope and type of service information depends on the version of the Firebird server, this information is made available through a separate class ServerInfoProvider. The Server.info property provides access to instance of ServerInfoProvider or it's ancestor class according to attached Firebird server version.

ServerInfoProvider methods and properties:

Example:

from firebird.driver import driver_config, connect, connect_server

srv_cfg = """[local]
host = localhost
user = SYSDBA
password = masterkey
"""
driver_config.register_server('local', srv_cfg)
db_cfg = """[employee]
server = local
database = employee.fdb
protocol = inet
"""
driver_config.register_database('employee', db_cfg)
with connect('employee', user='SYSDBA', password='masterkey'), connect_server('local', user='SYSDBA', password='masterkey') as srv:
    print(f'{srv.info.version=}')
    print(f'{srv.info.engine_version=}')
    print(f'{srv.info.manager_version=}')
    print(f'{srv.info.architecture=}')
    print(f'{srv.info.home_directory=}')
    print(f'{srv.info.security_database=}')
    print(f'{srv.info.lock_directory=}')
    print(f'{srv.info.message_directory=}')
    print(f'{srv.info.capabilities=!s}')
    print(f'{srv.info.connection_count=}')
    print(f'{srv.info.attached_databases=}')

Sample output for 64-bit Linux Firebird 4.0 Beta 2:

srv.info.version='4.0.0.1963'
srv.info.engine_version=4.0
srv.info.manager_version=2
srv.info.architecture='Firebird/Linux/AMD/Intel/x64'
srv.info.home_directory='/opt/firebird/'
srv.info.security_database='/opt/firebird/security4.fdb'
srv.info.lock_directory='/tmp/firebird/'
srv.info.message_directory='/opt/firebird/'
srv.info.capabilities=ServerCapability.REMOTE_HOP|MULTI_CLIENT
srv.info.connection_count=1
srv.info.attached_databases=['/opt/firebird/examples/empbuild/employee.fdb']

Database options

Database options could be set using ServerDbServices instance accessible via Server.database property.

  • set_default_cache_size() - Sets individual page cache size for database.

    >>> from firebird.driver import connect_server
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_default_cache_size(database='employee.fdb', size=5000)
    
  • set_sweep_interval() - Sets database sweep interval.

    >>> from firebird.driver import connect_server
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_sweep_interval(database='employee.fdb', interval=100000)
    
  • set_space_reservation() - Sets space reservation option for database.

    >>> from firebird.driver import connect_server, DbSpaceReservation
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_space_reservation(database='employee.fdb', mode=DbSpaceReservation.USE_FULL)
    
  • set_write_mode() - Sets database write mode (SYNC/ASYNC).

    >>> from firebird.driver import connect_server, DbWriteMode
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_write_mode(database='employee.fdb', mode=DbWriteMode.ASYNC)
    
  • set_access_mode() - Sets database access mode (R/W or R/O).

    >>> from firebird.driver import connect_server, DbAccessMode
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_access_mode(database='employee.fdb', mode=DbAccessMode.READ_ONLY)
    
  • set_sql_dialect() - Sets database SQL dialect.

    Warning

    Changing SQL dialect on existing database is not recommended. Only newly created database objects would respect new dialect setting, while objects created with previous dialect remain unchanged. That may have dire consequences.

    >>> from firebird.driver import connect_server
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.set_sql_dialect(database='employee.fdb', dialect=1)
    
  • no_linger() - Sets one-off override for database linger.

    >>> from firebird.driver import connect_server
    >>> with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
    >>>     srv.database.no_linger(database='employee.fdb')
    

Database maintenance

Important

Because available database-related actions depends on the version of the Firebird server, they are made available through a separate class ServerDbServices. The Server.database property provides access to instance of ServerDbServices or it's ancestor class according to attached Firebird server version.

  • get_statistics() - Returns database statistics produced by gstat utility.

    This method is so-called Async service that only initiates report processing. Actual report content could be read by one from many methods for text output from Services that Server provides .

    from firebird.driver import connect_server, SrvStatFlag
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.get_statistics(database='employee.fdb',
                                    flags=SrvStatFlag.DATA_PAGES | SrvStatFlag.RECORD_VERSIONS),
                                    tables=['EMPLOYEE','PROJECT'])
        stats = srv.readlines()
    
  • backup() - Performs logical (GBAK) database backup.

    This method is so-called Async service that only initiates the backup process. Output from gbak could be read by one from many methods for text output from Services that Server provides .

    from firebird.driver import connect_server, SrvBackupFlag
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.backup(database='employee.fdb',
                            backup='/backup/employee.fbk',
                            flags=SrvBackupFlag.IGNORE_CHECKSUMS | SrvBackupFlag.NO_GARBAGE_COLLECT,
                            stats='TD', verbose=True)
        report = srv.readlines()
    
  • local_backup() - Performs logical (GBAK) database backup into local byte stream.

    from firebird.driver import connect_server, SrvBackupFlag
    f = open('/backup/employee.fbk',mode='wb')
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.local_backup(database='employee.fdb', backup_stream=f,
                                  flags=SrvBackupFlag.IGNORE_CHECKSUMS | SrvBackupFlag.NO_GARBAGE_COLLECT)
    f.close()
    
  • restore() - Performs database restore from logical (GBAK) backup.

    This method is so-called Async service that only initiates the restore process. Output from gbak could be read by one from many methods for text output from Services that Server provides .

    from firebird.driver import connect_server, SrvRestoreFlag
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.restore(backup='/backup/employee.fbk',
                             database='/data/employee.fdb',
                             flags=SrvRestoreFlag.REPLACE,
                             stats='TD', verbose=True, page_size=8192)
        report = srv.readlines()
    
  • local_restore() - Performs database restore from logical (GBAK) backup stored in local byte stream.

    from firebird.driver import connect_server, SrvRestoreFlag
    f = open('/backup/employee.fbk',mode='rb')
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.local_restore(backup_stream=f, database='/data/employee.fdb',
                                   flags=SrvRestoreFlag.REPLACE, page_size=8192)
    f.close()
    
  • nbackup() - Performs physical (NBACKUP) database backup.

    from firebird.driver import connect_server
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.nbackup(database='employee.fdb', backup='/backup/employee.bkp1', level=1)
    
  • nrestore() - Performs restore from physical (NBACKUP) database backup.

    from firebird.driver import connect_server
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.nrestore(backups=['/backup/employee.bkp0', '/backup/employee.bkp1'],
                              database='/data/employee.fdb')
    
  • shutdown() - Database shutdown.

    from firebird.driver import connect_server, ShutdownMode, ShutdownMethod
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.shutdown(database='employee.fdb', mode=ShutdownMode.SINGLE,
                              method=ShutdownMethod.FORCED, timeout=10)
    
  • bring_online() - Bring previously shut down database back online.

    from firebird.driver import connect_server, OnlineMode
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.bring_online(database='employee.fdb', mode=OnlineMode.MULTI)
    
  • sweep() - Performs database sweep operation.

    from firebird.driver import connect_server
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.sweep(database='employee.fdb')
    
  • validate() - Performs database validation.

    This method is so-called Async service that only initiates the validation process. Output from validation could be read by one from many methods for text output from Services that Server provides .

    from firebird.driver import connect_server
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.validate(database='employee.fdb')
        report = srv.readlines()
    
  • repair() - Performs database repair operation.

    from firebird.driver import connect_server, SrvRepairFlag
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        srv.database.repair(database='employee.fdb',
                            flags=SrvRepairFlag.REPAIR | SrvRepairFlag.KILL_SHADOWS)
    
  • get_limbo_transaction_ids() - Returns list of transactions in limbo.

  • commit_limbo_transaction() - Resolves limbo transaction with commit.

  • rollback_limbo_transaction() - Resolves limbo transaction with rollback.

  • nfix_database - Fixup database after filesystem copy.

  • set_replica_mode - Manage replica database.

User maintenance

Important

Because user maintenance functionality may depend on the version of the Firebird server, this functionality is made available through a separate class ServerUserServices. The Server.user property provides access to instance of ServerUserServices or it's ancestor class according to attached Firebird server version.

Tip

Since Firebird 2.5 you can use SQL commands (CREATE/ALTER/DROP USER) to manage users in a security database from a regular database attachment.

The SQL set of DDL commands for managing user accounts has been further enhanced in Firebird 3, thus improving the DDL capabilities in a way that exceeds capabilities of user management services.

  • get_all() - Returns information about all users.

  • get() - Returns information about specified users.

  • add() - Add new user.

  • update() - Update user information.

  • delete() - Delete user.

  • exists() - Returns True if user exists.

Trace sessions

Important

Because trace functionality may depend on the version of the Firebird server, this functionality is made available through a separate class ServerTraceServices. The Server.trace property provides access to instance of ServerTraceServices or its ancestor class according to attached Firebird server version.

  • ServerTraceServices.start() - Start a trace session with a config string and optional name. On Firebird 6 or newer, plugins accepts a plugin name or a list of names. Returns the session ID.

    This method is so-called Async service that only starts the trace session. Output from trace session could be read by one from many methods for text output from Services that Server provides .

    from firebird.driver import connect_server
    
    trace_config = """database = %[\\/]employee.fdb
    {
        enabled = true
        log_statement_finish = true
        print_plan = true
        include_filter = %%SELECT%%
        exclude_filter = %%RDB$%%
        time_threshold = 0
        max_sql_length = 2048
    }
    """
    
    with connect_server('localhost', user='SYSDBA', password='masterkey') as srv:
        trace_id = srv.trace.start(config=trace_config, name='test_trace_1')
        trace_log = []
        # Get first 10 lines of trace output
        for i in range(10):
            trace_log.append(srv.readline())
        # Stop trace session
        # Because trace session blocks the connection, we need another one to stop trace session!
        with connect_server('localhost', user='SYSDBA', password='masterkey') as srv_aux:
            srv_aux.trace.stop(trace_id)
    
  • ServerTraceServices.stop() - Stop trace session.

  • ServerTraceServices.suspend() - Suspend trace session.

  • ServerTraceServices.resume() - Resume trace session.

  • ServerTraceServices.sessions - Dictionary with active trace sessions. The key is session ID, value is a TraceSession instance. Its plugins list contains the plugin names reported by the service manager, when available.