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:
- The
Server.infoproperty object provides Server Configuration and State information. - The
Server.databaseproperty object provides Database options and Database maintenance. - The
Server.userproperty object provides User maintenance. - The
Server.traceproperty object provides management of Trace sessions.
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,Noneat end of output, orTIMEOUTwhenquery_timeoutexpires.readline_timed()- Queries one line with an explicit timeout for that call.readlines()- Returns the remaining lines, omitting timeout signals.- Iteration over
Serverobject, becauseServerhas built-in support for iterator protocol. - Using
callbackmethod provided by developer. EachServermethod that returns its result asynchronously accepts an optional parametercallback, 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:
SrvInfoCode.LINE: A single line of text.SrvInfoCode.TO_EOF: A block of text up to specified (buffer) size.
Both methods have specific pros and cons:
LINEmeans more roundtrips and thus slower transfer of service output, but each line is sent to client immediately when it's available.TO_EOFmeans 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:
-
get_log()- Request the contents of the server’s log file (firebird.log).This method is so-called
Async servicethat only initiates log transfer. Actual log content could be read by one from many methods for text output from Services thatServerprovides . -
version- Returns Firebird server version as SEMVER string. -
engine_version- Firebird server version as. float value. -
manager_version- Firebird service manager version. -
architecture- Firebird server implementation description. -
home_directory- Firebird server home directory. -
security_database- Security database. -
lock_directory- Directory with lock file(s). -
message_directory- Directory with message file(s). -
capabilities- Firebird server capabilities (asServerCapabilityflags). -
connection_count- Current number of database attachments. -
attached_databases- List of attached databases.
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. -
set_sweep_interval()- Sets database sweep interval. -
set_space_reservation()- Sets space reservation option for database. -
set_write_mode()- Sets database write mode (SYNC/ASYNC). -
set_access_mode()- Sets database access mode (R/W or R/O). -
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.
-
no_linger()- Sets one-off override for database linger.
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 servicethat only initiates report processing. Actual report content could be read by one from many methods for text output from Services thatServerprovides .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 servicethat only initiates the backup process. Output from gbak could be read by one from many methods for text output from Services thatServerprovides .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 servicethat only initiates the restore process. Output from gbak could be read by one from many methods for text output from Services thatServerprovides .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. -
nrestore()- Performs restore from physical (NBACKUP) database backup. -
shutdown()- Database shutdown. -
bring_online()- Bring previously shut down database back online. -
sweep()- Performs database sweep operation. -
validate()- Performs database validation.This method is so-called
Async servicethat only initiates the validation process. Output from validation could be read by one from many methods for text output from Services thatServerprovides . -
repair()- Performs database repair operation. -
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 aconfigstring and optionalname. On Firebird 6 or newer,pluginsaccepts a plugin name or a list of names. Returns the session ID.This method is so-called
Async servicethat only starts the trace session. Output from trace session could be read by one from many methods for text output from Services thatServerprovides .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 aTraceSessioninstance. Itspluginslist contains the plugin names reported by the service manager, when available.