FirebirdSQL logo
  • Anglaiskeyboard_arrow_down

Gstat Caveats

The following is a brief list of gotchas and funnies that I have detected in my own use of gstat.Some of these are mentioned above, others may not be.By collecting them all here in one place, you should be able to find out what’s happening if you have problems.

The -⁠t[able] Switch Can Cause Problems

The [gstat-cmdline-table] switch expects a list of table names to be supplied.

In older versions, if you supply the database name after a table name, it is assumed to be a table name, and you are prompted for a database name.

tux> gstat -t EMPLOYEE JOB employee
please retry, giving a database name

In Firebird 2.5 and higher, using -⁠t before the database name accepts only one table name, and a second table name is interpreted as the database name, resulting in an error when the actual database name is encountered.

> gstat -u sysdba -t EMPLOYEE JOB employee
database name was already specified

For this reason, call gstat with the database name as the very first parameter, or at least put the -⁠t[able] option after the database name:

tux> gstat employee -t EMPLOYEE JOB

Database "/opt/firebird/examples/empbuild/employee.fdb"
Database header page information:
...

Database file sequence:
File /opt/firebird/examples/empbuild/employee.fdb is the only file

Analyzing database pages ...
...

In Firebird 2.1 and earlier, you can supply an additional switch after the last table name and before the database name.This trick no longer works in Firebird 2.5 and higher, as it will only accept one table name when before the database name.

tux> gstat -t EMPLOYEE JOB -z employee
gstat version LI-V2.1.3.18185 Firebird 2.1

Database "/opt/firebird/examples/empbuild/employee.fdb"
Database header page information:
...

Database file sequence:
File /opt/firebird/examples/empbuild/employee.fdb is the only file
        Firebird/linux Intel (access method), version
"LI-V2.1.3.18185 Firebird 2.1"
        Firebird/linux Intel (remote server), version
"LI-V2.1.3.18185 Firebird 2.1/tcp (greenbird)/P11"
        Firebird/linux Intel (remote interface), version
"LI-V2.1.3.18185 Firebird 2.1/tcp (greenbird)/P11"
        on disk structure version 11.1

Analyzing database pages ...

docnext count = 3

The Shadow Count Seems Wrong

It appears that adding and/or dropping shadow files from a database is not always reported by gstat when it produces a database report.

tux> # Use gstat to display shadow details
tux> gstat employee -h|grep -i sh[a]dow
        Shadow count            0

tux> isql employee
Database: employee

SQL> SHOW DATABASE;
Database: employee
        Owner: SYSDBA
 Shadow 1: "/u00/firebird/databases/employee.shd1" auto
...

Straight away, it is obvious that the report from gstat is incorrect as the employee database has one shadow file.If we use isql to add a new shadow file to this database, as shown below, gstat still insists that there are no shadows.

SQL> CREATE SHADOW 7 AUTO '/u00/firebird/databases/employee.shd7';

SQL> SHOW DATABASE;
Database: employee
        Owner: SYSDBA
 Shadow 1: "/u00/firebird/databases/employee.shd1" auto
 Shadow 7: "/u00/firebird/databases/employee.shd7" auto
...

SQL> shell;

tux> gstat employee -h | grep -i sh[a]dow
        Shadow count            0

Document history

The exact file history is recorded in the firebird-documentation git repository; see https://github.com/FirebirdSQL/firebird-documentation

Revision History

1.9

24 Feb 2024

MR

Fixed broken cross-references caused by using prefix gbak instead of gstat

1.8

24 Feb 2024

MR

1.7

23 Feb 2024

MR

  • Reordered document history so most recent changes are on the top

  • Convert commandline options from definition list to sections

  • Add switches: -⁠?, -⁠encryption, -⁠nocreation, -⁠role, and -⁠trusted

  • Misc. copy editing, and updating information for newer version

  • Add some links to gfix and gbak documentation

  • Cross-links between sections

  • Added word-joiner in commandline switches between minus (-) and first character to ensure they aren’t broken up on word wrap

1.6

19 Jun 2020

MR

Conversion to AsciiDoc, minor copy-editing

1.5

11 Oct 2011

ND

  • Updated for Firebird 2.5.

  • Spelling errors corrected.

1.4

23 Mar 2011

ND

  • Added ODS 9.1 for Interbase 5.0 to the list of known ODS values.

  • Added reference to Managing Limbo Transactions in the gfix manual.

  • Corrected explanation of when an automatic database sweep is carried out, based on OIT and OST as opposed to OIT and OAT.As advised by Vlad Khorsun.

1.3

17 Feb 2010

ND

Formatting errors in the command line switches corrected.

1.2

14 Dec 2009

ND

A couple more minor corrections and spelling mistakes corrected.

1.1

30 Nov 2009

ND

Many corrections suggested by Paul Vinkenoog plus a general tidy up and a few more examples added.

1.0

29 Oct 2009

ND

Created a new gstat manual.

License notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”); you may only use this Documentation if you comply with the terms of this License.Copies of the License are available at https://www.firebirdsql.org/pdfmanual/pdl.pdf (PDF) and https://www.firebirdsql.org/manual/pdl.html (HTML).

The Original Documentation is titled Firebird Database Statistics Reporting Tool.

The Initial Writer of the Original Documentation is: Norman Dunbar.

Copyright © 2009 - 2011.All Rights Reserved.Initial Writer contact: NormanDunbar at users dot sourceforge dot net.

Contributor(s): Mark Rotteveel.

Portions created by Mark Rotteveel are Copyright © 2020-2024.All Rights Reserved.(Contributor contact(s): mrotteveel at users dot sourceforge dot net).