Command-line Utilities

cf) Firebird 2.5 Release Notes


This is a new CLI utility for interfacing with the new trace facilities. Usage is as follows.-

 fbtracemgr <action> [<parameters>]

Action Switches

  -STA[RT]     Start trace session
  -STO[P]      Stop trace session
  -SU[SPEND]   Suspend trace session
  -R[ESUME]    Resume trace session
  -L[IST]      List existing trace sessions


Action parameters

-N[AME]     <string>  Session name
-I[D]       <number>  Session ID
-C[ONFIG]   <string>  Trace configuration file name

Connection parameters

-SE[RVICE]  <string>  Service name
-U[SER]     <string>  User name
-P[ASSWORD] <string>  Password
-FE[TCH]    <string>  Fetch password from file
-T[RUSTED]  <string>  Force trusted authentication

Examples using fbtracemgr

fbtracemgr -SE remote_host:service_mgr -USER SYSDBA -PASS masterkey -LIST
fbtracemgr -SE service_mgr -START -NAME my_trace -CONFIG my_cfg.txt
fbtracemgr -SE service_mgr -SUSPEND -ID 2
fbtracemgr -SE service_mgr -RESUME -ID 2
fbtracemgr -SE service_mgr -STOP -ID 4


All switches and parameter identifiers are case-insensitive

To stop an interactive trace session on any platform, press Ctrl-C.

V.2.5.1 Improvements

The diagnostics of internal trace errors were improved. (Tracker reference CORE-3413).

Output is now flushed periodically. (Tracker reference CORE-3324).

Retrieve Password from a File or Prompt

Any command-line utility that takes a -password parameter is vulnerable to password sniffing, especially when the utility is run from a script. Since v.2.1, the [PASSWORD] argument has displayed in the process list on POSIX platforms as an asterisk ( * ), which was an improvement on showing it in clear.

As a second stage towards hiding the password from unauthorised eyes, this release enables it to be retrieved from a file or (on POSIX) from STDIN.

New -fetch_password Switch

Firebird 2.5 introduces the new switch -fet[ch_password] as an optional replacement for -pa[ssword] for all command-line utilities that take a password for authentication purposes. The switch may be progressively abbreviated from the right, conforming to the established rules.


The exception to the rules is the qli utility, for which only -F is valid.

The new switch cannot be applied to substitute for the -pw switch of the gsec utility.

Usage of -fetch_password

The switch requires one parameter, an unquoted string that is the file path for the file containing the password. If the call is not made by a system user with Superuser/Administrator privileges, the location must be accessible by the system user making the call.

For example,

 isql -user sysdba -fet passfile server:employee

extracts the first line of from a file named “passfile” in the current working directory and loads it into the [PASSWORD] argument of the call.

The filename can be specified as stdin:

 isql -user sysdba -fet stdin server:employee

If stdin is the terminal, a prompt is presented—

 Enter password:

—requiring the operator to type in the password.


On POSIX, the operator will also be prompted if s/he specifies

   -fetch /dev/tty

This technique could be useful if, for example, you needed to restore from stdin (all one line):

 bunzip2 -c emp.fbk.bz2 | gbak -c stdin /db/new.fdb
    -user sysdba -fetch /dev/tty


The following improvements have been added for gsec:

Since v.2.1, Windows domain administrators have had full access to the user management functions. In v.2.5 they do not get these privileges automatically unless the SYSDBA has configured the security database to make it happen automatically.

In the Administrative Features chapter is a detailed overview of the new system role RDB$ADMIN. There, you will find descriptions of the new ALTER ROLE syntax that can be used by the SYSDBA to enable or disable the automatic mapping of Windows administrators to the RDB$ADMIN role in databases, including the security database which they access when creating, altering and dropping users.

This automatic mapping can also be done in a gsec command-line call, using the new -mapping switch.

Mapping an OS Administrator to the RDB$ADMIN Role

The new -mapping switch is used to enable or disable the association of an operating system user with the RDB$ADMIN role in the security database. It takes one argument: either set to enable the association or drop to disable it. The syntax is:

 -mapping {set | drop}

Granting the RDB$ADMIN Role to a Firebird User

The introduction of the RDB$ADMIN system role has made it possible to escalate the privileges of an ordinary user. However, it was (and still is) not possible any for any user, even SYSDBA, to attach directly to the security database and grant the required permissions for the user to manage other users. A parameter—GRANT ADMIN ROLE—was included in the new CREATE USER and ALTER USER statement syntaxes to enable SYSDBA, or another user that has already acquired the RDB$ADMIN role in the security database, to have the RDB$ADMIN role applied to an ordinary user “at arm's length”, as it were.

The same can be achieved in gsec using the new switch -admin. It takes one argument: either YES (to grant the RDB$ADMIN role to the specified user in security2.fdb) or NO (to revoke it). The syntax is:

 -admin {YES | NO}

Command-line Help for gsec

Claudio Valderrama

Tracker reference: CORE-756)

Parameter help has been implemented for gsec, accessible by using the -help or -? switches.


Additions made to gsec and the Service Parameter Block (SPB) relating to the system role RDB$ADMIN are covered by the appropriate support in the fbsvcmgr utility.

for gsec -mapping, two new tag items: isc_action_svc_set_mapping and isc_action_svc_drop_mapping

for gsec -admin: the new parameter isc_spb_sec_admin, of spb_long with either 0 as its value (meaning REVOKE ADMIN ROLE) or non-zero (meaning GRANT ADMIN ROLE).

For a full overview of the RDB$ADMIN role, refer to the topic New RDB$ADMIN System Role in the Administrative Features chapter.


Repair Switches for Malformed Strings

The gbak utility has two new restore switches intended to repair malformed UNICODE_FSS character data and metadata, respectively, when restoring the backup of an affected database.

Switch Syntax

 -FIX_FSS_D(ATA) <charset> -- fix malformed UNICODE_FSS data
 -FIX_FSS_M(ETADATA) <charset> -- fix malformed UNICODE_FSS metadata

Hints with Malformed String Exceptions for Restores

(CORE-2754, A. dos Santos Fernandes)

When a restore fails with malformed string errors, gbak will supply a hint in verbose output, referring the user to the -FIX_FSS_METADATA and -FIX_FSS_DATA switches.

Preserve Character Set Default Collation

An improvement allows the current value of RDB$DEFAULT_COLLATE_NAME in the system table RDB$CHARACTER_SETS to survive the backup/restore cycle.

Tracker reference CORE-789.

Improve Insertion Performance for Restore

Adriano dos Santos Fernandes

(v.2.5.1) Improved performance in the records insertion phase of restore.

Tracker reference CORE-3433.


New Switches Added

Four switches were added to NBackup:

 -FE <filename>   Fetch password from file
 -Z               Print version information
 -?               Help
 -D ON|OFF        Force direct I/O on or off

  • FE :: Supports the feature allowing the authentication password to be fetched from a file. For details, see New -fetch_password Switch in this chapter.
  • Z :: Prints the version details of the nbackup executable.
  • ? :: Prints a terse list of usage instructions for the switches and options.
  • D :: ON option enables direct input and output operations; OFF disables them. The default settings depend on the operating system and Firebird version, as follows:

Windows service-capable platforms ON in all versions.

POSIX OFF in 2.0-2.0.5, 2.1-2.1.2, 2.1.4, 2.5 and higher

ON in 2.1.3 and 2.0.6, provided O_DIRECT is available; otherwise OFF. POSIX_FADV_NOREUSE is also set, if available.


Using -D ON has no effect if neither O_DIRECT nor POSIX_FADV_NOREUSE is available, although no error or warning will be raised.


Support for the new -D switch is also included among changes to the Services API in this version. For details, see isc_spb_nbk_direct on|off in the chapter Changes to the Firebird API and ODS.

I/O Resource Load Reduced on POSIX

An improvement has been done for POSIX versions to address a problem whereby the full backup tool of the nBackup incremental backup utility would hog I/O resources when backing up large databases, bringing production work to a standstill. Now, nBackup tries to read from the operating system cache before attempting to read from disk, thus reducing the I/O load substantially.


The “cost” may be a 10 to 15 percent increase in the time taken to complete the full backup under high-load conditions.

Tracker reference CORE-2316.


Some changes to the isql interactive query tool have been implemented.


isql now returns the SQLSTATE completion code in diagnostics, instead of the now deprecated SQLCODE. For more information, see the topic Support for SQLSTATE Completion Codes in the chapter Changes to the Firebird API and ODS.

Improvement for Exponential Number Output

Claudio Valderrama

Tracker reference CORE-1171.

isql has always output different formatting of numbers on Windows and POSIX for two-digit exponents. The default behaviour of Microsoft and Intel compilers is to zero-pad the exponent to three digits regardless. For example,

 select cast ('-2.488355210669293e+39' as double precision)
   from rdb$database;

On POSIX, the result is -2.488355210669293e+39

On Windows, the result was -2.488355210669293e+039

The isql output has been modified so that the Windows output now conforms with that on other platforms.


Help for SHOW COLLATIONS has been added to the command-line help for isql. (Tracker reference CORE-2432, A. dos Santos Fernandes).

SET ROWCOUNT Statement Added

Mark O'Donohue

Added mainly to assist testers, this command enables a limit to be set on the number of rows a query returns to the interactive isql shell.

Example of Use

The following isql statement will stop returning rows after the 10,000th row has been output:

 SQL>set rowcount 10000;

gpre (Precompiler)

Some Updates

Stephen Boyd

Adriano dos Santos Fernandes

Tracker reference CORE-1527.

GPRE now supports the IS NOT DISTINCT predicate and CASE/NULLIF/COALESCE/SUBSTRING functions, as well as the whole set of CURRENT_* context variables.

Deprecated Features with Future Impact on Utilities

In anticipation of the dropping of the intrinsic function isc_ddl from the Firebird 3 codebase, certain features currently available in the gdef and gpre tools are deprecated—meaning that, whilst they may work in V.2.5, they will fail in Firebird 3. More details can be found in the Compatibility chapter.


Claudio Valderrama

Tracker reference CORE-1411.

The gstat statistics reporting utility now has -? and -help switches for requesting help about available switches and arguments.