class firebird.lib.gstat.DbAttribute(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

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'


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

Bases: object

Data/Index page fill distribution.

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

Bases: object

Page encryption status.

  • pages (int) –

  • encrypted (int) –

  • unencrypted (int) –


class firebird.lib.gstat.StatDatabase[source]

Bases: object

Firebird database statistics (produced by gstat).

has_encryption_stats() bool[source]

Returns True if instance contains information about database encryption.

Return type:


has_index_stats() bool[source]

Returns True if instance contains information about indices.

Return type:


has_row_stats() bool[source]

Returns True if instance contains information about table rows.

Return type:


has_system() bool[source]

Returns True if instance contains information about system tables.

Return type:


has_table_stats() bool[source]

Returns True if instance contains information about tables.


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:


parse(lines: Iterable[str]) None[source]

Parses gstat output.


lines (Iterable[str]) – Iterable that return lines from database analysis produced by Firebird gstat.

Return type:


push(line: str | Sentinel) None[source]

Push parser.


line (str | Sentinel) – Single gstat output line, or STOP sentinel.

Return type:


attributes: List[DbAttribute]

Database attributes

backup_diff_file: str

Backup difference file

backup_guid: str

Backup GUID

completed: datetime

GSTAT completion timestamp

continuation_file: str

Continuation file

continuation_files: List[str]

Database file names

creation_date: datetime

Database creation timestamp

database_dialect: int

SQL Dialect

encrypted_blob_pages: int

Stats for encrypted blob pages

encrypted_data_pages: int

Stats for encrypted data pages

encrypted_index_pages: int

Stats for encrypted index pages

executed: datetime

GSTAT execution timestamp

filename: str

Database filename

flags: int

Database flags

generation: int

Database header generation

gstat_version: int

GSTAT version

implementation: str


property indices: DataList[StatIndex]

DataList of StatIndex instances.

last_logical_page: int

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

Replay logging file

root_filename: str

Root file name

shadow_count: int

Number of shadows

sweep_interval: int

Sweep interval

system_change_number: int

System change number

property tables: DataList[StatTable]

DataList of StatTable instances.

class firebird.lib.gstat.StatTable[source]

Bases: object

Statisctics for single database table.

avg_fill: float

Average data page fill ratio

avg_fragment_length: float

Average length of record fragments

avg_record_length: float

Average record length

avg_unpacked_length: float

Average length of unpacked record

avg_version_length: float

Average record version length

blob_pages: int

Number of BLOB pages

blobs: int

Number of BLOB values

blobs_total_length: int

Total length of BLOB values (bytes)

compression_ratio: float

Record compression ratio

data_page_slots: int

Number of data page slots for table

data_pages: int

Number of data pages for table

distribution: FillDistribution

Data page fill distribution statistics

empty_pages: int

Number of empty data pages

full_pages: int

Number of full data pages

index_root_page: int

Index Root Page for table

indices: DataList[StatIndex]

Indices belonging to table

level_0: int

Number of Level 0 BLOB values

level_1: int

Number of Level 1 BLOB values

level_2: int

Number of Level 2 BLOB values

max_fragments: int

Max number of fragments for single record

max_versions: int

Max number of versions for single record

name: str

Table name

pointer_pages: int

Number of Pointer Pages

primary_pages: int

Number of Primary Data Pages

primary_pointer_page: int

Primary Pointer Page for table

secondary_pages: int

Number of Secondary Data Pages

swept_pages: int

Number of swept data pages

table_id: int

Table ID

total_formats: int

Number of record formats

total_fragments: int

Total number of record fragments

total_records: int

Total number of record in table

total_versions: int

Total number of record versions

used_formats: int

Number of actually used record formats

class firebird.lib.gstat.StatIndex(table)[source]

Bases: object

Statisctics for single database index.

avg_data_length: float

Average data length

avg_key_length: float

Average key length

avg_node_length: float

Average node length

avg_prefix_length: float

Average key prefix length

clustering_factor: float

Index clustering factor

compression_ratio: float

Index key compression ratio

depth: int

Depth of index tree

distribution: FillDistribution

Index page fill distribution statistics

index_id: int

Index ID

leaf_buckets: int

Number of leaft index tree buckets

max_dup: int

Max number of occurences for single duplicate key

name: str

Index name

nodes: int

Number of index tree nodes

ratio: float


root_page: int

Index Root page

table: ProxyType

Proxy to parent StatTable



total_dup: int

Total number of duplicate keys