firebird.lib.gstat

Enums

class firebird.lib.gstat.DbAttribute(value)

Bases: Enum

Database attributes stored in header page clumplets.

ACTIVE_SHADOW = 'active shadow'

BACKUP_LOCK = 'backup lock'

BACKUP_MERGE = 'backup merge'

BACKUP_WRONG = 'wrong backup state'

NO_RESERVE = 'no reserve'

NO_SHARED_CACHE = 'shared cache disabled'

READ_ONLY = 'read only'

SHUTDOWN_FULL = 'full shutdown'

SHUTDOWN_MULTI = 'multi-user maintenance'

SHUTDOWN_SINGLE = 'single-user maintenance'

WRITE = 'force write'

Dataclasses

class firebird.lib.gstat.FillDistribution(d20: int, d40: int, d60: int, d80: int, d100: int)

Bases: object

Data/Index page fill distribution statistics.

Stores the count of pages falling into specific fill percentage ranges.

Parameters:

• d20 (int)

• d40 (int)

• d60 (int)

• d80 (int)

• d100 (int)

class firebird.lib.gstat.Encryption(pages: int, encrypted: int, unencrypted: int)

Bases: object

Page encryption status.

Parameters:

• pages (int)

• encrypted (int)

• unencrypted (int)

Classes

class firebird.lib.gstat.StatDatabase

Bases: object

Parses and holds Firebird database statistics produced by the gstat utility.

This is the main class for interacting with gstat output. Instantiate it and use the parse() or push() methods to feed it gstat output lines. Parsed statistics are stored in the instance’s attributes and the tables and indices collections.

has_encryption_stats() → bool

Returns True if instance contains information about database encryption.

Return type:

bool

has_index_stats() → bool

Returns True if instance contains information about indices.

Return type:

bool

has_row_stats() → bool

Returns True if instance contains information about table rows.

Return type:

bool

has_system() → bool

Returns True if instance contains information about system tables.

Return type:

bool

has_table_stats() → bool

Returns True if instance contains information about tables.

Important

This is not the same as check for empty tables list. When gstat is run with -i without -d option, tables list contains instances that does not have any other information about table but table name and its indices.

Return type:

bool

parse(lines: Iterable[str]) → None

Parses gstat output from an iterable source.

Processes all lines from the iterable and finalizes parsing.

Parameters:

lines (Iterable[str]) – Iterable that returns lines from database analysis produced by Firebird gstat (e.g., a file object or list of strings).

Return type:

None

push(line: str | STOP) → None

Pushes a single line (or STOP sentinel) into the parser state machine.

This method processes one line of gstat output at a time, updating the internal state and populating statistics attributes. Call with the STOP sentinel after the last line to finalize processing (e.g., convert distributions, freeze lists).

Parameters:

line (str | STOP) – Single gstat output line, or the firebird.base.types.STOP sentinel.

Return type:

None

attributes: list[DbAttribute]

Database attributes

backup_diff_file: str | None

Backup difference file

backup_guid: str | None

Backup GUID

completed: datetime | None

GSTAT completion timestamp

continuation_file: str | None

Continuation file

continuation_files: list[str]

Database file names

creation_date: datetime | None

Database creation timestamp

database_dialect: int

SQL Dialect

database_guid: str | None

Database GUID

encrypted_blob_pages: int | None

Encryption statistics for blob pages.

encrypted_data_pages: int | None

Encryption statistics for data pages.

encrypted_index_pages: int | None

Encryption statistics for index pages.

executed: datetime | None

GSTAT execution timestamp

filename: str | None

Database filename

flags: int

Database flags

generation: int

Database header generation

gstat_version: int | None

GSTAT version

implementation: str | None

Implementation

property indices: DataList[StatIndex]

DataList of StatIndex instances.

last_logical_page: int | None

Last logical page

next_attachment_id: int

Next attachment ID

next_header_page: int

Next header page

next_transaction: int

Next Transaction

oat: int

Oldest Active Transaction

oit: int

Oldest Interesting Transaction

ost: int

Oldest Snapshot Transaction

page_buffers: int

Number of page buffers

page_size: int

Database page size

replay_logging_file: str | None

Replay logging file

root_filename: str | None

Root file name

shadow_count: int

Number of shadows

sweep_interval: int | None

Sweep interval

system_change_number: int | None

System change number

property tables: DataList[StatTable]

DataList of StatTable instances.

class firebird.lib.gstat.StatTable

Bases: object

Statistics for a single database table, populated from gstat output.

Attributes are populated by the StatDatabase parser. Default values are None or 0 until parsed from the input.

avg_fill: float | None

Average data page fill ratio

avg_fragment_length: float | None

Average length of record fragments

avg_record_length: float | None

Average record length

avg_unpacked_length: float | None

Average length of unpacked record

avg_version_length: float | None

Average record version length

blob_pages: int | None

Number of BLOB pages

blobs: int | None

Number of BLOB values

blobs_total_length: int | None

Total length of BLOB values (bytes)

compression_ratio: float | None

Record compression ratio

data_page_slots: int | None

Number of data page slots for table

data_pages: int | None

Number of data pages for table

distribution: FillDistribution | None

Data page fill distribution statistics. Final type is FillDistribution.

empty_pages: int | None

Number of empty data pages

full_pages: int | None

Number of full data pages

index_root_page: int | None

Index Root Page for table

indices: DataList[StatIndex]

Indices belonging to table. Items are weakref.proxy to StatIndex.

level_0: int | None

Number of Level 0 BLOB values

level_1: int | None

Number of Level 1 BLOB values

level_2: int | None

Number of Level 2 BLOB values

max_fragments: int | None

Max number of fragments for single record

max_versions: int | None

Max number of versions for single record

name: str | None

Table name

pointer_pages: int | None

Number of Pointer Pages

primary_pages: int | None

Number of Primary Data Pages

primary_pointer_page: int | None

Primary Pointer Page for table

secondary_pages: int | None

Number of Secondary Data Pages

swept_pages: int | None

Number of swept data pages

table_id: int | None

Table ID

table_size: int | None

Table size

total_formats: int | None

Number of record formats

total_fragments: int | None

Total number of record fragments

total_records: int | None

Total number of record in table

total_versions: int | None

Total number of record versions

used_formats: int | None

Number of actually used record formats

class firebird.lib.gstat.StatIndex(table)

Bases: object

Statistics for a single database index, populated from gstat output.

Instances are linked to their parent StatTable via a weak reference. Attributes are populated by the StatDatabase parser.

Parameters:

table (ProxyType)

avg_data_length: float | None

Average data length

avg_key_length: float | None

Average key length

avg_node_length: float | None

Average node length

avg_prefix_length: float | None

Average key prefix length

clustering_factor: float | None

Index clustering factor

compression_ratio: float | None

Index key compression ratio

depth: int | None

Depth of index tree

distribution: FillDistribution | None

Index page fill distribution statistics

index_id: int | None

Index ID

leaf_buckets: int | None

Number of leaft index tree buckets

max_dup: int | None

Max number of occurences for single duplicate key

name: str | None

Index name

nodes: int | None

Number of index tree nodes

ratio: float | None

Ratio

root_page: int | None

Index Root page

table: ProxyType

Proxy to parent StatTable

Type:

wekref.proxy

total_dup: int | None

Total number of duplicate keys