Chapter 3. firebird.conf

Configures the database paths — other than aliases — the server accepts for opening databases.

ConfigurationGlobal

Syntax

DatabaseAccess = <database-access-config>
 
<database-access-config> ::=
    None
  | Full
  | Restrict <path-list>
 
<path-list> ::= path [; path ...]

DefaultFull (see Security recommendation!)

Examples

# Only allow aliases
DatabaseAccess = None
# Full access
DatabaseAccess = Full
# Restricted (Windows)
DatabaseAccess = Restrict C:\Databases;D:\CRM
# Restricted (Linux)
DatabaseAccess = Restrict /var/db;/var/crm

See alsoSection 3.1.3, “ExternalFileAccess”, Section 8.1.11, “ISC_PATH”

Enables remote access of databases.

ConfigurationGlobal, and per-database

Syntax

RemoteAccess = Boolean

Defaulttrue

The Boolean option RemoteAccess controls if databases can be opened remotely — via TCP/IP, or WNET³, or only locally using embedded or — on Windows — XNET.

Any TCP/IP or WNET connection is considered remote, including connections created from the same machine (localhost).

Examples

# Enable remote access
RemoteAccess = true
# Disable remote access
RemoteAccess = false

Configures paths allowed for external table files.

ConfigurationGlobal, and per-database

Syntax

ExternalFileAccess = <external-file-access-config>
 
<external-file-access-config> ::=
    None
  | Full
  | Restrict <path-list>
 
<path-list> ::= path [; path ...]

DefaultNone

This setting does not prevent creation of an external table with a disallowed path, but attempts to query the external table or insert into the external table will fail if the path is not allowed.

Attempts to access (select or insert) an external table file not allowed by the configuration will produce error Use of external file at location <filename> is not allowed by server configuration (error code 335544831 or isc_conf_access_denied).

For more information on external tables, see section External Tables in the Firebird 5.0 Language Reference.

Examples

# No access
ExternalFileAccess = None
# Full access (DO NOT USE!)
ExternalFileAccess = Full
# Restricted (Windows)
ExternalFileAccess = Restrict C:\ExternalFiles;D:\Temp\ExternalFiles
# Restricted (Linux)
ExternalFilesAccess = /var/externalfiles;/tmp/externalfiles

See alsoSection 3.1.1, “DatabaseAccess”, Section 3.1.4, “UdfAccess”

Configures paths allowed for loading UDF — User-Defined Function — libraries.

ConfigurationGlobal

Syntax

UdfAccess = <udf-access-config>
 
<udf-access-config> ::=
    None
  | Full
  | Restrict <path-list>
 
<path-list> ::= path [; path ...]

DefaultNone

UDFs and — by extension — UdfAccess are deprecated. The recommended replacements are built-in functions, PSQL functions (introduced in Firebird 3.0), or UDR functions (User-Defined Routine, introduced in Firebird 3.0).

Examples

# No access
UdfAccess = None
# Full access (DO NOT USE!)
UdfAccess = Full
# Restricted (Windows)
UdfAccess = Restrict UDF;C:\UDF
# Restricted (Linux)
ExternalFilesAccess = UDF;/var/udf

See alsoSection 3.1.3, “ExternalFileAccess”

Directories used by the Firebird engine for temporary files.

ConfigurationGlobal

Syntax

TempDirectories = <path-list>
 
<path-list> ::= path [; path ...]

DefaultValue of environment variable Section 8.1.6, “FIREBIRD_TMP” (or its fallback).

The <path-list> is a semicolon-separated list of directories. It is possible to use absolute paths (e.g. Windows — C:\Database, Linux — /db), and relative paths. Relative paths are resolved against the root directory of Firebird. Given relative paths are not always obvious, it is recommended to use absolute paths.

Firebird will use the first directory listed until it runs out of disk space, then switch to the next directory in the list, and so on.

This setting does not affect the location of lock files.

Examples

# Multiple directories (Windows)
TempDirectories = C:\Temp\Firebird;D:\Temp\Firebird
# Single directory (Linux)
TempDirectores = /tmp/firebird

See alsoSection 3.1.6, “TempTableDirectory”, Section 8.1.6, “FIREBIRD_TMP”

Directory used for temporary tables and temporary blobs.

ConfigurationGlobal, and per-database

Syntax

TempTableDirectory = path

DefaultValue of environment variable Section 8.1.6, “FIREBIRD_TMP” (or its fallback).

Contrary to Section 3.1.5, “TempDirectories”, this setting only accepts a single directory. If the configured directory does not exist or is not accessible, Firebird will use the directory specified in FIREBIRD_TMP or its fallback.

Examples

# Windows
TempTableDirectory = C:\Temp\Firebird
# Linux
TempTableDirectory = /tmp/firebird

See alsoSection 3.1.5, “TempDirectories”, Section 8.1.6, “FIREBIRD_TMP”

Trace configuration file for system audit.

ConfigurationGlobal

Syntax

AuditTraceConfigFile = path

DefaultNo value

The AuditTraceConfigFile sets the configuration file for system-wide auditing using the trace facility. System audit is only enabled if this configuration item is set to a valid trace configuration file.

It is possible to use absolute paths (e.g. Windows — C:\Firebird\fbtrace.conf, Linux — /fb/fbtrace.conf), and relative paths. Relative paths are resolved against the root directory of Firebird.

Examples

# Relative path
AuditTraceConfigFile = fbtrace.conf
# Absolute path (Windows)
AuditTraceConfigFile = C:\Firebird\customtrace.conf
# Absolute path (Linux)
AuditTraceConfigFile = /fb/customtrace.conf

See alsoChapter 7, Trace configuration

Maximum size in MiB of user trace session log files.

ConfigurationGlobal

Syntax

MaxUserTraceLogSize = integer

UnitMegabyte (MiB)

Default10 (10 MiB)

When the log file of a user trace session reaches the configured size, the trace session is suspended until the trace data is read through the trace service API (which clears/deletes the outstanding log file).

Example

MaxUserTraceLogSize = 15

Default number of cached database pages

ConfigurationGlobal, and per-database

Syntax

DefaultDbCachePages = integer

UnitDatabase page

Firebird uses the page cache to store recently used database pages in memory. For SuperServer, the page cache is per database, and it’s shared by all connections to that database; for SuperClassic and Classic, the cache is per connection.

On SuperServer, the cache for each database will use (page count) * (page size). On (Super)Classic, the cache will use (page count) * (page size) * (connection count).

This setting only takes effect if the database has not been configured with an explicit number of page buffers using gfix -buffers. A backup with gbak will record the current configuration in the backup file — even if it is derived from DefaultDbCachePages and not explicitly set. After a restore, the database will have this value explicitly configured in its database header, unless overridden with -⁠BUFFERS.

On (Super)Classic the cache can also be overridden for a specific connection using the isc_dpb_num_buffers connection property.

Example

DefaultDbCachePages = 4096

Maximum database growth increment in bytes.

ConfigurationGlobal, and per-database

Syntax

DatabaseGrowthIncrement = integer

UnitByte

Default128M (128 MiB)

When a database has to allocate a database page, and there are no free pages, Firebird will allocate space with the following constraints:

• Minimum: 128 KiB

• 1/16th of existing allocated space

• Maximum: value of DatabaseGrowthIncrement

Preallocation reduces physical file fragmentation, and may improve performance.

If DatabaseGrowthIncrement is set to zero (0), preallocation is disabled, and Firebird will then allocate space per page.

Database shadow files are not preallocated.

Example

DatabaseGrowthIncrement = 512K

Configures if Firebird uses the filesystem cache for database files.

ConfigurationGlobal, and per-database

Syntax

UseFileSystemCache = Boolean

Defaulttrue

This setting is ignored if it is not explicitly set, and Section 3.1.12, “FileSystemCacheThreshold” has been explicitly set.

Example

# Disable filesystem cache
UseFileSystemCache = false

Enables filesystem caching of a database if its page cache size is less than the configured value.

ConfigurationGlobal, and per-database

Syntax

FileSystemCacheThreshold = integer

UnitDatabase page

Default64K (see also note below)

If set explicitly and Section 3.1.11, “UseFileSystemCache” is not set explicitly, the filesystem cache is used if the page cache size configured in the database header — or if not set in the database header, the value of Section 3.1.9, “DefaultDbCachePages” — is less than FileSystemCacheThreshold.

Example

FileSystemCacheThreshold = 8192

The maximum percentage of RAM used for the filesystem cache on 64-bit Windows.

ConfigurationGlobal

Syntax

FileSystemCacheSize = integer

UnitPercent

Range0, 10 - 95

Default0

If 0, Firebird will use the current filesystem cache settings and will not attempt to change the setting.

Values in the range of 10 to 95 specify the maximum percentage of RAM the host will use for the filesystem cache. Values outside this range — other than 0 — will apply a default value of 30.

Configures if Firebird allows opening of database files on mounted network volumes.

ConfigurationGlobal

Syntax

RemoteFileOpenAbility = Boolean

Default0 (false)

By default, Firebird only opens database files on local disks. When RemoteFileOpenAbility is enabled, Firebird can also open databases from mounted NFS volumes (Linux) or SMB/CIFS volumes (Windows)

Example

RemoteFileOpenAbility = 0

Allocation block size for temporary storage.

ConfigurationGlobal

Syntax

TempBlockSize = integer

UnitByte

Default1M (1 MiB)

Temporary storage is allocated in increments of TempBlockSize.

Example

TempBlockSize = 2M

Maximum amount of temporary space that is cached in memory.

ConfigurationGlobal, and per-database

Syntax

TempCacheLimit = integer

UnitByte

For Classic, the default is lower because the memory is allocated per server process, and this means the memory requirement grows with each connection.

Example

TempCacheLimit = 1G

Maximum identifier length in bytes.

ConfigurationGlobal, and per-database

Syntax

MaxIdentifierByteLength = integer

UnitByte

Range1 - 252

Default252

Since Firebird 4.0, identifiers can be a maximum 252 bytes, or 63 characters UTF8. Set to 31 to use the same limit as in Firebird 3.0 and earlier.

This setting combined with Section 3.1.18, “MaxIdentifierCharLength” determines the actual maximum length. For example, if MaxIdentifierCharLength setting is 31, and MaxIdentifierCharLength is not set, or set to 124 or higher, then an identifier can have maximum 31 characters of any UTF8 character. On the other hand, if MaxIdentifierCharLength is set to 31, and MaxIdentifierCharLength is also set to 31, then you can have 31 characters from the ASCII range, but using characters that require 2, 3, or 4 bytes to be encoded will reduce the actual maximum length in characters (to a minimum of 7 if all characters are 4 bytes in UTF8).

Example

MaxIdentifierByteLength = 31

See alsoSection 3.1.18, “MaxIdentifierCharLength”

Maximum identifier length in characters.

ConfigurationGlobal, and per-database

Syntax

MaxIdentifierCharLength = integer

UnitCharacter

Range1 - 63

Default63

Since Firebird 4.0, identifiers can be a maximum 252 bytes, or 63 characters UTF8. Set to 31 to use the same limit as in Firebird 3.0 and earlier.

This setting combined with Section 3.1.17, “MaxIdentifierByteLength” determines the actual maximum length. For example, if MaxIdentifierCharLength setting is 31, and MaxIdentifierCharLength is not set, or set to 124 or higher, then an identifier can have maximum 31 characters of any UTF8 character. On the other hand, if MaxIdentifierCharLength is set to 31, and MaxIdentifierCharLength is also set to 31, then you can have 31 characters from the ASCII range, but using characters that require 2, 3, or 4 bytes to be encoded will reduce the actual maximum length in characters (to a minimum of 7 if all characters of an identifier are 4 bytes in UTF8).

Example

MaxIdentifierCharLength = 31

See alsoSection 3.1.17, “MaxIdentifierByteLength”

Maximum sort record size that can be stored inline in the sort block.

ConfigurationGlobal, and per-database

Syntax

InlineSortThreshold = integer

UnitByte

Default1000

This controls if non-key fields are stored inside the sort block, or to refetch them from the data pages after sorting. If the sort record size with non-key fields exceeds the configured maximum, only the key fields are stored in the sort block.

A value of 0 (zero) disables storing non-key fields and always refetches non-key fields.

This setting is a balance between the cost of refetching data, and the cost of sorting when including non-key data. If a sort block is very large (e.g. due to a lot of rows and/or large sort record size), the sort will be performed on disk. The I/O cost of sorting including non-key fields may be larger than the I/O cost of refetching data.

Examples

# 2000 bytes
InlineSortThreshold = 2000
 
# Disabled
InlineSortThreshold = 0

Enables first row optimization strategy.

ConfigurationGlobal, and per-database

Syntax

OptimizeForFirstRows = Boolean

Defaultfalse (optimize for all rows)

Defines whether queries should be optimized to return the first row(s) as soon as possible rather than returning the whole dataset as soon as possible. By default, Firebird optimize for retrieval of all rows.

This can be overridden at the session level using the SET OPTIMIZE statement, or at the statement level by using the OPTIMIZE FOR clause.

Example

OptimizeForFirstRows = true

Enables optimizer conversion of outer joins to inner joins.

ConfigurationGlobal, and per-database

Syntax

OuterJoinConversion = Boolean

Defaulttrue (enabled)

Defines whether the optimizer attempts to convert outer joins into inner joins, provided that such a transformation is possible from the query result perspective. This can be done if — for example — a LEFT OUTER JOIN is used, but the missing rows of the right table are filtered out in the WHERE by a condition that excludes NULL for a column of that table.

Enabled by default. Disable to simplify the migration path if outer joins are used intentionally in SQL queries (e.g. as optimizer hints) even if they are known to be semantically equivalent to inner joins.

Example

# Disable outer join conversion
OuterJoinConversion = false

Enables experimental optimizer conversion of subqueries in EXISTS and IN to semi-joins.

ConfigurationGlobal, and per-database

Syntax

SubQueryConversion = Boolean

Defaultfalse (disabled)

Defines whether the optimizer attempts to merge subqueries in EXISTS and IN with the outer query by converting them to semi-joins, provided that such a transformation is possible from the query result perspective.

Example

SubQueryConversion = true

Authentication plugins accepted by Firebird server.

ConfigurationGlobal, and per-database

Syntax

AuthServer = <plugin-list>
 
<plugin-list> ::= plugin [<separator> plugin ...]
 
<separator> ::=
  one of <space> (' '), <comma> (','), <semicolon> (';')

DefaultSrp256

Authentication plugins have a server-side part and client-side part. The authentication plugins implement how a user is authenticated. Some authentication plugins also generate the encryption key for wire encryption. Generally, users are managed by a user manager that is specific to a plugin or family of plugins.

The authentication plugins the client tries are specified by the Section 3.1.24, “AuthClient” setting.

A default Firebird installation supports the following authentication plugins:

From these plugins, only Legacy_Auth does not generate an encryption key for wire encryption. Additional third-party plugins may be available.

Example

AuthServer = Srp256, Srp

See alsoSection 3.1.24, “AuthClient”, Section 3.1.25, “UserManager”

Authentication plugins tried by Firebird fbclient.

ConfigurationGlobal, per-database, client-side, and per-connection

Syntax

AuthClient = <plugin-list>
 
<plugin-list> ::= plugin [<separator> plugin ...]
 
<separator> ::=
  one of <space> (' '), <comma> (','), <semicolon> (';')

DefaultSrp256, Srp, Legacy_Auth (non-Windows) Srp256, Srp, Win_Sspi, Legacy_Auth (Windows)

The authentication plugins determine how a user authenticates. Some authentication plugins also generate the encryption key for wire encryption.

For a list of plugins supported by a default Firebird installation, see Table 3.12, “Standard authentication plugins included in Firebird”.

When configured server-side (in firebird.conf or databases.conf), this setting controls which plugins are tried when the server creates a connection to another database (e.g. using EXECUTE STATEMENT …​ ON EXTERNAL).

When configured client-side — in firebird.conf read by the client, or using isc_dpb_config (key/value) or isc_dpb_auth_plugin_list (value only) — it controls which plugins are tried for connecting.

The server and client must agree on the plugins used. The list of plugins accepted by the server is configured through Section 3.1.23, “AuthServer”. However, the client will always try the first plugin listed, even if not supported by the server. Subsequent plugins will only be tried if they are also listed in the AuthServer setting of the server.

Example

AuthClient = Srp256

See alsoSection 3.1.23, “AuthServer”

Enabled user manager plugins.

ConfigurationGlobal, and per-database

Syntax

UserManager = <plugin-list>
 
<plugin-list> ::= plugin [<separator> plugin ...]
 
<separator> ::=
  one of <space> (' '), <comma> (','), <semicolon> (';')

DefaultSrp

User manager plugins manage users, generally in the security database. The user manager plugins are also used to populate the SEC$USERS and SEC$USER_ATTRIBUTES virtual tables.

The first plugin listed is the default user manager. The default user manager is used if the USING PLUGIN clause is absent from user management statements. The default user manager is also used by gsec and the user management service API⁴.

Setting UserManager explicitly to an empty value (blank) will disallow management of users.

A default Firebird installation supports the following user manager plugins:

The per-database configuration in databases.conf enables which user manager plugins are allowed  — and which is the default — when connecting to that specific database. When configured on a security database, it only manages which user manager plugins are allowed when connecting directly to that security database; it does not configure which user manager plugins may store data in that security database.

Examples

# Enable Srp and Legacy_UserManager, with Srp as default
UserManager = Srp, Legacy_UserManager
# Disable user management
UserManager =

See alsoSection 3.1.23, “AuthServer”

Default profiler plugin

ConfigurationGlobal, and per-database

Syntax

DefaultProfilerPlugin = plugin

DefaultDefault_Profiler

Specifies the default profiler plugin used by the RDB$PROFILER package, if no explicit plugin name is specified (parameter PLUGIN_NAME of START_SESSION).

Example

# Set default to MyCustomProfiler
# This requires a custom plugin-library with that name
DefaultProfilerPlugin = MyCustomProfiler

The trace plugin used by the Firebird trace facility.

ConfigurationGlobal

Syntax

TracePlugin = plugin

Defaultfbtrace

The Firebird trace facility can be used to audit or record statements executed on the server. The trace plugin is responsible for writing the data to a log file in a specific format.

Firebird includes a default trace plugin called fbtrace. There are third-party plugins available which provide different output formats.

Example

TracePlugin = customtrace

Wire crypt plugins tried by the client and/or accepted by the server.

ConfigurationGlobal, per-database, client-side, and per-connection

Syntax

WireCryptPlugin = <plugin-list>
 
<plugin-list> ::= plugin [<separator> plugin ...]
 
<separator> ::=
  one of <space> (' '), <comma> (','), <semicolon> (';')

DefaultChaCha64, ChaCha, Arc4

Wire crypt plugins allow for encryption of the database connection after authentication. The default plugins included in Firebird use a session-key generated by the authentication plugin⁵ to encrypt the connection.

A default Firebird installation supports the following wire encryption plugins:

This configuration property serves multiple purposes:

1. server-side (firebird.conf or databases.conf of the server)

   • The plugins accepted for incoming connections

   • The plugins tried for outgoing connections (i.e. server as client)

2. client-side (firebird.conf read by client, or key/value in isc_dpb_config)

   • The plugins tried for outgoing connections

The intersection of server-side and client-side wire encryption plugins decides which plugins are tried. The server-side order of plugins decides in which order they are tried.

Example

# Only enable Arc4
WireCryptPlugin = Arc4

Database encryption keyholder plugin

ConfigurationGlobal, and per-database

Syntax

KeyHolderPlugin = plugin

DefaultNo value

A keyholder serves as a temporary storage for database encryption keys. Generally, this plugin will be provided by the third-party database encryption plugin.

Firebird does not include a default plugin. The Linux distribution includes an example in libCryptKeyHolder_example.so, but this library is intended as an example only, and is not for production use.

Example

KeyHolderPlugin = CustomKeyHolder

Enables use of an encrypted security database.

ConfigurationGlobal, and per-database

Syntax

AllowEncryptedSecurityDatabase = Boolean

Defaultfalse

With the default setting, it is not possible to authenticate against an encrypted security database.

Depending on the database encryption plugin used and its configuration, the client may hold the encryption key and needs to send it to the server to be able to access the database. With the default configuration, this key exchange will only happen after authentication completed successfully and — if enabled — wire encryption was set up (which depends on the session key of authentication).

However, if the security database is encrypted, this key exchange must occur before authentication. As this needs to happen before wire encryption is established, and could lead to key exposure⁶, this must be explicitly enabled.

In general, the security database — assuming use of SRP and long/quality passwords — is pretty good at protecting itself and doesn’t need to be encrypted. One use case of an encrypted security database is if a database is its own security database and needs to be encrypted for other reasons.

Authenticating against an encrypted security database is not supported by the Legacy_Auth authentication plugin.

Example

AllowEncryptedSecurityDatabase = false

Connection providers used to connect to a database.

ConfigurationGlobal, per-database, client-side, and per-connection

Syntax

Providers = <plugin-list>
 
<plugin-list> ::= plugin [<separator> plugin ...]
 
<separator> ::=
  one of <space> (' '), <comma> (','), <semicolon> (';')

DefaultRemote,EngineNN,Loopback (with NN the major ODS of the Firebird version)

Providers are plugins used to connect to a database.

A default Firebird installation supports the following provider plugins:

Additional providers may be added. For example, copying the Engine12.dll/libEngine12.so from Firebird 3.0 to the plugins directory of Firebird 4.0 or 5.0 and including Engine12 in Providers adds support for opening Firebird 3.0 (ODS 12) databases.

This configuration property serves multiple purposes:

1. server-side (firebird.conf or databases.conf of the server)

   • The plugins accepted for incoming connections. However, unless Section 3.1.75, “Redirection” is enabled, Remote is ignored for incoming connections.

   • The plugins tried for outgoing connections (i.e. server as client)

2. client-side (firebird.conf read by client, or key/value in isc_dpb_config)

   • The plugins tried for outgoing connections

     For example, specifying only Engine13 will ensure the client will only make embedded connections.

Example

Providers = Engine13

Timeout for detecting and purging locks held by dead processes in case of a lock conflict.

ConfigurationGlobal, and per-database

Syntax

DeadlockTimeout = integer

UnitSecond

Default10

The deadlock timeout is the number of seconds the lock manager will wait in case of a lock conflict before purging locks of dead processes and doing an extra deadlock scan cycle. In normal cases, Firebird will detect deadlocks instantly, so this timeout is only to detect exceptional cases.

Setting this setting too low may increase load and reduce performance.

Example

DeadlockTimeout = 15

Statement timeout.

ConfigurationGlobal, and per-database

Syntax

StatementTimeout = integer

UnitSecond

Default0 (no timeout)

The statement timeout is the maximum duration of statement execution and cursor use. The engine will automatically cancel the statement after the configured number of seconds. A value of 0 means that no database-level statement timeout is set.

The statement timeout can be configured on three levels:

1. Database level (through firebird.conf or databases.conf)

2. Connection level (through SET STATEMENT TIMEOUT or the API)

   If the database-level timeout is non-zero and lower than the connection-level timeout, the database-level timeout applies instead.

3. Statement level (through the API)

   If the database-level timeout is non-zero and lower than the statement-level timeout, the database-level timeout applies instead. A non-zero statement-level timeout takes precedence over the connection-level timeout (i.e. the connection-level timeout is not an upper bound).

The timeout is reported when the client sends a request involving the statement handle. The request will complete with error isc_cancelled and a secondary error code indicating which timeout expired:

Example

# Five minute timeout
StatementTimeout = 300

Connection idle timeout.

ConfigurationGlobal, and per-database

Syntax

ConnectionIdleTimeout = integer

UnitMinute

Default0 (no timeout)

The connection idle timeout — or session idle timeout — is the maximum time a connection may be idle (i.e. the engine receives no requests) before it shuts down the connection. A setting of 0 means that no database-level connection idle timeout is set.

By default, the idle timeout is not enabled. No minimum or maximum limit is imposed, but a reasonably large period — such as a few hours — is recommended.

The connection idle timeout can be configured on three levels:

1. Database level (through firebird.conf or databases.conf)

2. Connection level (through SET SESSION IDLE TIMEOUT or the API)

   If the database-level timeout is non-zero and lower than the connection-level timeout, the database-level timeout applies instead.

When a connection is shutdown by the expiration of the idle timeout, the next user API call returns the error isc_att_shutdown with secondary error isc_att_shut_idle.

Example

# One hour
ConnectionIdleTimeout = 60

Timeout of ON DISCONNECT triggers.

ConfigurationGlobal, and per-database

Syntax

OnDisconnectTriggerTimeout = integer

UnitSecond

Default180 (3 minutes)

Firebird will automatically cancel ON DISCONNECT triggers if they run longer than the configured timeout. A value of 0 means that no timeout is set.

Example

# Five minutes
OnDisconnectTriggerTimeout = 300

Maximum number of pending asynchronous writes.

ConfigurationGlobal, and per-database

Syntax

MaxUnflushedWrites = integer

UnitData page/pending write

Default100 (Windows) -1 (other platforms)

This parameter determines how frequently pending asynchronous writes are flushed to disk when Forced Writes are disabled (or, asynchronous writing is enabled). Its value is the number of asynchronous writes that may be pending before a flush is flagged to be done next time a transaction commits. A setting of -1 disables this (i.e. pending writes are not flushed).

This setting only applies when forced-writes are off.

If the Section 3.1.37, “MaxUnflushedWriteTime” expires before the maximum number of pending pages is reached, the currently pending pages are flushed as well.

Example

MaxUnflushedWrites = 50

See alsoSection 3.1.37, “MaxUnflushedWriteTime”

Maximum time asynchronous writes may be pending.

ConfigurationGlobal, and per-database

Syntax

MaxUnflushedWriteTime = integer

UnitSecond

Default5 (Windows) -1 (other platforms)

This parameter determines how frequently pending asynchronous writes are flushed to disk when Forced Writes are disabled (or, asynchronous writing is enabled). Its value is the maximum time in seconds an asynchronous write may be pending before a flush is flagged to be done next time a transaction commits. A setting of -1 disables this (i.e. pending writes are not flushed).

This setting only applies when forced-writes are off.

If the Section 3.1.36, “MaxUnflushedWrites” is reached before this timeout, the currently pending pages are flushed as well.

Example

# 10 seconds
MaxUnflushedWriteTime = 10

See alsoSection 3.1.36, “MaxUnflushedWrites”

Enables bugcheck abort.

ConfigurationGlobal

Syntax

BugcheckAbort = Boolean

Default0 (false) — normal builds 1 (true) — debug builds (with DEV_DEBUG)

When enabled, Firebird calls abort() when internal errors or BUGCHECK macros are encountered. This invokes the post-mortem debugger which can create a core-dump for off-line analysis. When disabled, the engine tries to minimize damage and continue execution.

Setting this option to 1 will produce traceable core-dumps when something nasty like SIGSEGV happens inside a UDF. On Windows, enabling this option will invoke the JIT debugger facility when errors happen.

Example

# Enable bugcheck abort
BugcheckAbort = 1

Configures if Global Temporary Tables (GTT) with ON COMMIT DELETE ROWS are cleared on commit/rollback retaining.

ConfigurationGlobal, and per-database

Syntax

ClearGTTAtRetaining = Boolean

Default0 (false)

This is a compatibility setting to restore behaviour of Global Temporary Tables as it was in Firebird 2.1. In the normal behaviour (ClearGTTAtRetaining = 0), a Global Temporary Table with ON COMMIT DELETE ROWS is cleared at a hard commit or rollback, but is retained and the data is accessible after a commit retain or rollback retain. When enabled (ClearGTTAtRetaining = 1), the table is also cleared on commit retain or rollback retain.

Example

# Enable clearing GTT at commit/rollback retain
ClearGTTAtRetaining = 1

Relaxes relation alias checking rules in SQL.

ConfigurationGlobal

Syntax

RelaxedAliasChecking = Boolean

Default0 (false)

In Firebird 2.0, stricter parser rules for aliases of relations (e.g. tables, views) were implemented to conform to SQL standard requirements. Enabling this setting relaxes the relation alias checking rules to the Firebird 1.5 and older behaviour.

With the default setting, if a relation is aliased, you are only allowed to reference that relation using its alias. If RelaxedAliasChecking is set to 1 (true), you can also reference the relation using its original name.

For example:

-- Reference by alias (strict and relaxed)
select E.FIRST_NAME
from EMPLOYEE as E
 
-- Reference by relation name (relaxed only)
select EMPLOYEE.FIRST_NAME
from EMPLOYEE as E

Example

# Relaxed (non-strict) alias checking
RelaxedAliasChecking = 1

Configures if READ COMMITTED transactions always use READ CONSISTENCY mode.

ConfigurationGlobal, and per-database

Syntax

ReadConsistency = Boolean

Default1 (true)

Since Firebird 4.0, READ COMMITTED by default always uses the READ CONSISTENCY mode, even if [NO] RECORD VERSION (isc_tpb_rec_version/isc_tpb_no_rec_version in TPB) is requested. If ReadConsistency is set to 0 (false), the requested mode is used.

When disabled, READ CONSISTENCY mode must be requested explicitly (e.g. SET TRANSACTION READ COMMITTED READ CONSISTENCY or by including isc_tpb_read_consistency in the TPB).

This setting is intended for backwards compatibility, if your application specifically depends on the behaviour of [NO] RECORD VERSION. In general, we recommend to leave it at its default value.

Example

# Disable always using read consistency mode for READ COMMITTED
ReadConsistency = 0

Configures if newer data types are automatically converted to data types available in an older version.

ConfigurationGlobal, and per-database

Syntax

DataTypeCompatibility = [{ 2.5 | 3.0 }]

DefaultNo value

The DataTypeCompatibility setting controls if input parameters (e.g. query parameters) and output columns (e.g. columns of a result set) using new data types are automatically converted to legacy data types of the specified older version.

Setting to an empty value will return the data type as is. This can be used in databases.conf to override (clear) the configuration from firebird.conf.

Configure this setting as a last resort, as it affects all clients to the server — if set in firebird.conf — or database — in databases.conf — even if a client supports the newer data types. Whenever possible, use the isc_dpb_set_bind connection property or the SET BIND statement instead.

Example

DataTypeCompatibility = 2.5

Connection timeout.

ConfigurationGlobal, client-side, and per-connection

Syntax

ConnectionTimeout = integer

UnitSecond

Default180 (3 minutes)

The ConnectionTimeout is the number of seconds the client (or the server acting as client to another database) waits before concluding the connection attempt failed.

Example

# Connection timeout of 5 minutes
ConnectionTimeout = 300

Controls if wire encryption is used or even required.

ConfigurationGlobal, per-database, client-side, and per-connection

Syntax

WireCrypt = { Disabled | Enabled | Required }

DefaultRequired (server) Enabled (client)

By default, encryption is Required for incoming connections and Enabled for outgoing connections (client connections).

To access a server using an older client library which does not support wire encryption, WireCrypt in the server configuration file should be set to Enabled instead of the default Required. It is recommended to not set WireCrypt to Disabled, because then newer clients will also not encrypt their connections.

The rules are:

• If one side has WireCrypt = Disabled:

  • If the other side has WireCrypt = Required, the connection is rejected

  • Otherwise, the connection is established without encryption

• If the server and client don’t have matching wire encryption plugins, or the encryption key is missing:

  • If either side has WireCrypt = Required, the connection is rejected

  • Otherwise, the connection is established without encryption

• In all other cases, an encrypted connection is established.

Example

WireCrypt = Enabled

Enables (zlib) wire compression of connections.

ConfigurationClient-side, and per-connection

Syntax

WireCompression = Boolean

Defaultfalse

This setting is ignored if the client library does not have access to the zlib library (zlib1.dll/libz.so.1).

It is not possible to disable wire compression server-side; if the client requests compression, the server will enable compression.

Example

# Enable wire compression
WireCompression = true

Seconds to wait on a silent client connection before the server sends a dummy packet to request acknowledgment.

ConfigurationGlobal, per-database, client-side, and per-connection

Syntax

DummyPacketInterval = integer

UnitSecond

Default0 (disabled)

The dummy packet interval is a way to detect broken connections. If a client is idle for more than the configured interval, the server will send a dummy packet to the client. This packet will result in a TCP/IP-level acknowledgement if the connection is still alive. Otherwise, it will result in detection of the broken connection.

Configuring this setting should generally be unnecessary as Firebird configures its sockets with SO_KEEPALIVE which will do a similar check at a lower level. If you do not like the default 2-hour keepalive timeout used by the TCP/IP stack, adjust your server OS settings appropriately.

On UNIX-like OS’s, modify contents of /proc/sys/net/ipv4/tcp_keepalive_* (which also apply to IPv6!).

For Windows, see the KeepAliveTime registry documentation.

Example

# Set interval to 30 minutes
DummyPacketInterval = 1800

Buffer size (in bytes) used by the client connection to accumulate output messages before sending them to the server using the Batch API.

ConfigurationClient-side, and per-connection

Syntax

ClientBatchBuffer = integer

UnitByte

Default131072 (or 128K)

This configuration item governs size of the client-side buffers for statement parameters and blobs for batch execution. Given blob and parameters are stored in separate buffers, the total space allocated is upto twice the configured size, per batch. Irrespective of the configured buffer size, the client will allocate sufficient space to buffer at least one set of statement parameters.

Example

# Buffer two megabyte
ClientBatchBuffer = 2M

Default session or client time zone.

ConfigurationGlobal, client-side, and per-connection

Syntax

DefaultTimeZone = time-zone-name

DefaultNo value (for server: derive from OS time zone)

• If empty, the default time zone for the server is derived from the OS time zone.

  The derived time zone uses the rules in the ICU time zone database loaded by Firebird, not the OS time zone database. Additional OS settings, like disabling daylight saving time, have no effect.

• When set in the server, it defines the default session time zone for attachments that don’t specify isc_dpb_session_time_zone.

• When set in the client, it defines the default time zone used with client-side API functions and the default value of isc_dpb_session_time_zone.

The value of time-zone-name is a time zone identifier string, as documented in Time Zone Format in the Firebird 5.0 Language Reference.

Example

# Default to Europe/Berlin
DefaultTimeZone = Europe/Berlin

The TCP service name/port number to be used for database connections.

ConfigurationGlobal, client-side, and per-connection

Syntax

RemoteServiceName = service-name

Defaultgds_db

If service-name is defined in the services definition file (e.g. /etc/services or C:\Windows\System32\drivers\etc\services), it is used to determine the TCP port to use. If service-name is not found, the value or default of Section 3.1.50, “RemoteServicePort” is used.

Server-side

Determines the port that the server listens for connections

Client-side and per-connection

Determines the port to use if none is specified in a TCP/IP connection URL

The order of precedence is explicitly set values before defaults, and RemoteServiceName — if an entry is found in the services file — before RemoteServicePort. In other words, if RemoteServiceName is not explicitly set, and RemoteServicePort is explicitly set, the value of RemoteServicePort is used.

Example

RemoteServiceName = gds_db

See alsoSection 3.1.50, “RemoteServicePort”

The TCP service port number to be used for database connections.

ConfigurationGlobal, client-side, and per-connection

Syntax

RemoteServicePort = integer

Range1 - 65535

Default3050

Configures the TCP port to use.

Server-side

Determines the port that the server listens for connections

Client-side and per-connection

Determines the port to use if none is specified in a TCP/IP connection URL

The order of precedence is explicitly set values before defaults, and RemoteServiceName — if an entry is found in the services file — before RemoteServicePort. In other words, if RemoteServiceName is not explicitly set, and RemoteServicePort is explicitly set, the value of RemoteServicePort is used.

Example

# Use port 3051 instead of 3050
RemoteServicePort = 3051

See alsoSection 3.1.49, “RemoteServiceName”

The TCP port number to be used for server event notification messages.

ConfigurationGlobal, and per-database

Syntax

RemoteAuxPort = integer

Range0 - 65535

Default0 (use random port)

When a client listens for events, it establishes a secondary connection to the Firebird server, using a port number the server sends to the client. By default, a random port is used.

This setting can be used to specify a fixed port number, for example one that can be allowed through the firewall.

Example

# Use port 3051 instead of a random port
RemoteAuxPort = 3051

Buffer size for send and receive buffers of both the client and server for TCP/IP connections.

ConfigurabilityGlobal, client-side, and per-connection

Syntax

TcpRemoteBufferSize = integer

UnitByte

Range1448 - 32767

Default8192

The engine reads ahead of the client and can send several rows of data in a single packet. With a larger buffer size, more data can be sent per request (e.g. per fetch).

The server-side configuration only configures the server buffer sizes, and the client-side (and per-connection) configuration only configures the client buffer sizes.

Example

# Use maximum buffer size of 32767
TcpRemoteBufferSize = 32767

Enables the TCP_NODELAY socket option (which disables Nagle’s algorithm).

ConfigurationGlobal, client-side, and per-connection

Syntax

TcpNoNagle = Boolean

Default1 (enabled)

Disabling Nagle’s algorithm (enabling TCP_NODELAY, the default) can improve the responsiveness of network connections, as the socket will not try to coalesce small packets.

Example

# Disable TCP_NODELAY (so, use Nagle's algorithm)
TcpNoNagle = 0

Enables the TCP Loopback Fast Path feature (SIO_LOOPBACK_FAST_PATH).

ConfigurationGlobal, client-side, and per-connection

Syntax

TcpLoopbackFastPath = Boolean

Default0 (disabled) — since Firebird 3.0.11 and 4.0.3 1 (enabled) — in older versions

The TCP Loopback Fast Path can improve performance of localhost connections on Windows systems. For it to work, both the client and the server need to enable the SIO_LOOPBACK_FAST_PATH option on the socket before connecting.

As this option is now deprecated, and Microsoft advises not to use it, exercise caution with this option, and leave or set it disabled.

Example

# Disable the "TCP Loopback Fast Path"
TcpLoopbackFastPath = 0

When enabled, sets the IPV6_V6ONLY socket option on the listener socket.

ConfigurationGlobal

Syntax

IPv6V6Only = Boolean

Default0 (disabled)

By default, the Firebird server listens on the zero IPv6 address (::) and accepts all incoming connections, whether IPv4 or IPv6, and IPv6V6Only is set to false (0). If it is set to true (1), the server, still listening implicitly or explicitly on the zero IPv6 address, will accept only IPv6 connections.

A different listening address, either IPv4 or IPv6, can be set using the Section 3.1.56, “RemoteBindAddress” parameter. If an IPv4 address or a non-zero IPv6 address is used, the IPv6V6Only setting has no effect.

When enabled, this will also reject IPv4-mapped IPv6 addresses as a value of RemoteBindAddress.

Example

# Enable IPV6_V6ONLY
IPv6V6Only = 1

See alsoSection 3.1.56, “RemoteBindAddress”

Network interface of the TCP/IP listener.

ConfigurationGlobal

Syntax

RemoteBindAddress = string

DefaultEmpty (bind to ::)

The setting accepts an IPv4, IPv6 address, or a hostname; the value may optionally be enclosed in square brackets.

By default — when not specified, or explicitly empty — Firebird listens on :: (the zero IPv6 address). The exact behaviour of the zero IPv6 address depends on Section 3.1.55, “IPv6V6Only”:

• if disabled (the default), Firebird listens on all IPv4 and IPv6 network interfaces of the host.

• if enabled, Firebird only listens on all IPv6 network interfaces of the host (not IPv4).

It is not possible to specify multiple bind addresses.

If Section 3.1.55, “IPv6V6Only” is enabled, IPv4-mapped IPv6 addresses are rejected.

When using a hostname, that hostname is used to resolve an IP address, preferring IPv6 over IPv4; the resolved address is then used to bind the server. So, make sure the hostname resolves to one IP address only (i.e. not be multihomed or otherwise multiplexed, nor be both IPv4 and IPv6). Otherwise, the server may bind to a different IP address on each restart (e.g. if the DNS resolution does a round-robin), and clients may have connection failures when they resolve a different IP address than the one the server was bound to.

Examples

# listen on IPv4 localhost
RemoteBindAddress = 127.0.0.1
 
# listen on IPv6 localhost
RemoteBindAddress = ::1
 
# listen on all IPv4 network interfaces of the host
RemoteBindAddress = 0.0.0.0
 
# listen on the IP address of fbserver.local
RemoteBindAddress = fbserver.local

See alsoSection 3.1.55, “IPv6V6Only”

Allocation size of the shared memory of the lock manager table.

ConfigurationGlobal, and per-database

Syntax

LockMemSize = integer

UnitByte

Default64K (64 KiB)

The lock manager table is allocated per database.

The value of LockMemSize is the initial size and the allocation unit. The shared memory will grow dynamically as needed in increments of this allocation unit, up to 2 GiB - 1, or when the system runs out of memory.

Example

# Allocate lock memory in increments of 2 MiB
LockMemSize = 2M

The number of times that the lock manager will try acquiring a lock in a loop before waiting.

ConfigurationGlobal, and per-database

Syntax

LockAcquireSpins = integer

Default0

The lock table of a database can only be accessed by one server process or thread at a time, and this is governed by a mutex. This mutex can be requested conditionally or unconditionally. A conditional request either succeeds immediately or fails and must be retried. An unconditional request will make the process or thread wait (block) until the request succeeds.

This setting is only relevant for SuperClassic and Classic.

It is hard to give specific advice for configuring LockAcquireSpins. On multicore machines — when using Classic and SuperClassic — it can be advantageous to spin on the lock a few times before waiting unconditionally, on the other hand if the lock table is heavily contested, this is likely to burn CPU cycles. As such, the advice is to experiment with it, and tune it per database in databases.conf.

Example

# Spin 5 times while acquiring lock
LockAcquireSpins = 5

Number of hash slots for locks.

ConfigurationGlobal, and per-database

Syntax

LockHashSlots = integer

Range101 - 65521

Default8191

Use of prime numbers is highly recommended. Setting out of range values will use the boundary values.

The number of hash slots determines how locks are distributed in the lock hash table. If two or more locks are assigned to the same hash slot, they are chained together, and the server must walk this chain to find the right lock in the slot.

If the average length of lock chains is very long (e.g. 20 locks on average), performance of the server may be affected. In that case, you can increase the number of LockHashSlots to a higher prime number. You can use fb_lock_print to determine the average lock chain length (called Hash lengths in the lock print output).

Example

# Use 9001 hash slots
LockHashSlots = 9001

Allocation size of the shared memory for the event manager.

ConfigurationGlobal, and per-database

Syntax

EventMemSize = integer

UnitByte

Default64K (64 KiB)

The memory for the event manager is allocated per database.

The value of EventMemSize is the initial size and the allocation unit. The shared memory will grow dynamically as needed in increments of this allocation unit, until the system runs out of memory.

Example

# Allocate event manager memory in increments of 128 KiB
EventMemSize = 128K

Allocation size of shared memory for snapshot management.

ConfigurationGlobal, and per-database

Syntax

SnapshotsMemSize = integer

UnitByte

Default64K (64 KiB)

The memory for snapshots is allocated per database. Each active snapshot uses 16 bytes of memory.

The value of SnapshotsMemSize is the initial size and the allocation unit. The memory will grow dynamically as needed in increments of this allocation unit, until the system runs out of memory.

Snapshots are used to provide a stable view on data within a transaction or during statement execution. See also Commit Order for Capturing the Database Snapshot in the Firebird 4.0 Release Notes.

Example

# Allocate snapshot memory in increments of 128 KiB
SnapshotsMemSize = 128K

Block size of shared memory allocated for TIP cache.

ConfigurationGlobal, and per-database

Syntax

TipCacheBlockSize = integer

UnitByte

Default4M (4 MiB)

The TIP cache is a list of all known transactions with associated Commit Numbers (CN), which are used to determine record visibility of active transactions.

The memory for the TIP cache is allocated per database. Each transaction uses 8 bytes of memory. The default size of a TIP cache block is 4 MiB, providing capacity for 512 * 1024 transactions.

A reason to reduce this value is if you have a small TIP cache (or, a small difference between OIT and Next Transaction) and want to conserve memory. A reason to increase this value is if you need a very large TIP cache (or, a very large difference between OIT and Next Transaction) and approach limits on kernel objects allocated for each block (files, mutexes, etc).

The TIP cache is implemented as an array indexed by transaction ID, with as value the corresponding Commit Number. This array is split into blocks of TipCacheBlockSize bytes containing the CN’s for all transactions between the OIT and Next Transaction markers. When Next Transaction moves beyond the range of the highest block, a new block is allocated. The oldest block is released when the OIT moves beyond the range of that block.

Example

# Block size of 1 MiB (128 * 1024 transactions per block)
TipCacheBlockSize = 1M

File to redirect stdout and stderr output of server.

ConfigurationGlobal

Syntax

OutputRedirectionFile = path

Default/dev/null (Linux and other Unix-like OSes) nul (Windows)

By default, stdout and stderr are redirected to the null-device to suppress any output.

When set to empty or -, the stderr and stdout are not redirected. When set to a file, it is redirected to that file.

This can be helpful when debugging plugins, UDRs, or UDFs that write to stdout or stderr.

Example

# Disable default redirect
OutputRedirectionFile =
# Redirect to file /var/tmp/firebirdoutput.log
OutputRedirectionFile = /var/tmp/firebirdoutput.log

Which CPUs should be used (Windows Only)

ConfigurationGlobal

Syntax

CpuAffinityMask = integer

Default0 (all CPUs)

Sets which processors can be used by the server. The value is taken from a bitmap in which each bit represents a CPU. Thus, to use only the first processor (CPU 0), the value is 1. To use both CPU 0 and CPU 1, the value is 3 (binary 11). To use CPU 1 and CPU 2, the value is 6 (binary 110). The default value is 0 - no affinity will be set.

In Firebird 5 and later, on Windows 10 and later, if affinity is not set by CpuAffinityMask, nor by the caller process, then the server tries to exclude efficiency cores from its own affinity mask, i.e. default affinity mask includes performance cores only.

On 32-bit Windows, this can configure at most 32 CPUs; on 64-bit Windows, at most 64 CPUs. On systems with more than 64 processors, it can only configure the processors in the processor group assigned to the Firebird process.

For technical information, see the Microsoft documentation of SetProcessAffinityMask.

Example

# Use CPU 7 only (binary 10000000)
CpuAffinityMask = 128
# Use CPU 15 and CPU 7 (binary 1000000010000000)
CpuAffinityMask = 32896

Garbage collection policy.

ConfigurationGlobal, and per-database

Syntax

GCPolicy = { cooperative | background | combined }

Defaultcombined (SuperServer) cooperative (Classic/SuperClassic)

The garbage collection policy configures how Firebird SuperServer performs garbage collection. For Classic and SuperClassic, this setting is ignored; they always use the cooperative policy.

Example

# Use background garbage collection policy
GCPolicy = background

Maximum amount of memory per connection for the statement cache.

ConfigurationGlobal, and per-database

Syntax

MaxStatementCacheSize = integer

UnitByte

Default2M (2 MiB)

The statement cache is a per-connection cache of previously compiled SQL statements. Setting the value to 0 disables the cache.

The cache is maintained automatically; cached statements are invalidated when required, e.g. when a DDL statement is executed, or when the cache size exceeds MaxStatementCacheSize.

Example

# Disable statement cache
MaxStatementCacheSize = 0
# Cache 5 MiB
MaxStatementCacheSize = 5M

Location of the security database.

ConfigurationGlobal, and per-database

Syntax

SecurityDatabase = { path | alias }

Default$(dir_secDb)/securityN.fdb (with N the major version of Firebird)

The security database is used for authentication and certain global configuration and user privileges (e.g. global authentication mapping, and CREATE DATABASE privileges). When using embedded mode, no authentication is performed.

The SecurityDatabase can be configured per database in databases.conf. Such a security database can be created as a normal database. Initialization as a security database happens per authentication plugin, the first time that authentication plugin is used to create a user. This initialization must be done with an embedded connection otherwise you cannot connect, or authenticated with a SYSDBA or RDB$ADMIN user of an already initialized authentication plugin.

It is possible to configure a database as its own security database, but only after the database has been created.

Example in databases.conf

# Configure employee example database as its own security database
employee = $(dir_sampleDb)/employee.fdb
{
  SecurityDatabase = employee
}

Maximum number of parallel workers per database per process.

ConfigurationGlobal

Syntax

MaxParallelWorkers = integer

Range1 - 64

Default1 (no parallelism)

Values higher than 1 configure the total number of parallel workers that can be created within a single Firebird process for each attached database. Workers are accounted for each attached database independently.

Parallel workers are used to parallelize certain database operations. In Firebird 5.0, that includes index creation and rebuilding, and sweep.

In SuperServer, worker attachments are implemented as light-weight system attachments, while in Classic and SuperClassic they look like normal user attachments. All worker attachments are embedded into the creating server process, so in Classic there are no additional server processes. Worker attachments are present in monitoring tables. Idle worker attachments are destroyed after 60 seconds of inactivity. In Classic, worker attachments are destroyed immediately when the user connection detaches from the database.

Setting out of range values will use the boundary values.

Example

MaxParallelWorkers = 8

See alsoSection 3.1.69, “ParallelWorkers”

Default number of parallel workers for a connection.

ConfigurationGlobal

Syntax

ParallelWorkers = integer

Range1 - Section 3.1.68, “MaxParallelWorkers”

Default1 (no parallelism)

This configures the default number of parallel workers that can be created by a single connection. This default can be overridden with the isc_dpb_parallel_workers connection property (up to the maximum Section 3.1.68, “MaxParallelWorkers”).

For accounting purposes, the user connection itself is counted as a worker, which is why value 1 means no parallelism, and a value of 2 means 1 additional worker connection next to the user connection.

Parallel workers are allocated on a first come, first served basis, so — in SuperServer and SuperClassic — when multiple connections to a database ask for parallel workers, at most Section 3.1.68, “MaxParallelWorkers” workers can be created. For example, if ParallelWorkers is 3 and MaxParallelWorkers is 4, and three connections ask for parallel workers, only 4 are allocated, e.g. two workers for the first, two for the second, and none for the third connection.

A connection only asks for parallel workers when performing a parallel operation. Once the operation is complete, the worker is released.

Parallel workers are used to parallelize certain database operations. In Firebird 5.0, that includes index creation and rebuilding, and sweep.

Setting out of range values will use the boundary values.

Example

ParallelWorkers = 4

See alsoSection 3.1.68, “MaxParallelWorkers”

Configures behaviour of the Firebird Guardian service (Windows only).

ConfigurationGlobal

Syntax

GuardianOption = integer

Default1 (always restart)

This setting only has effect when the Firebird Guardian service is installed and running.

Example

GuardianOption = 0

Priority level/class for the server process (Windows only).

ConfigurationGlobal

Syntax

ProcessPriorityLevel = integer

Default0 (normal priority)

Configures the process priority on Windows, which is used by the CPU scheduler to decide how and when to schedule threads of the Firebird process(es).

Setting a negative value may reduce responsiveness of the Firebird server if the system is otherwise busy, and setting a positive value may result in Firebird starving other process of CPU cycles. In general, do not set this to anything other than 0, and if you do set it, carefully test if your system responds correctly.

For technical information, see the Microsoft documentation of SetPriorityClass.

Example

# Set high priority
ProcessPriorityLevel = 1
# Set idle priority
ProcessPriorityLevel = -1

Name of the shared memory area used as the transport channel for the XNET (a.k.a. local) protocol (Windows only).

ConfigurationGlobal, client-side, and per-connection

Syntax

IpcName = string

DefaultFIREBIRD

Server-side, the configuration is used to create the shared memory to accept XNET connections, and for creating XNET connections to other servers. Client-side, the configuration is used to open the shared memory to make XNET connections to the server.

The user running the server process should have the SE_CREATE_GLOBAL_NAME privilege (or SeCreateGlobalPrivilege), so the shared memory area can be registered in the Global\ namespace. If the user does not have this privilege, it will be registered in the local namespace, and only processes running in the same session will be able to connect using XNET.

If you’re running Firebird as a service, and the user does not have SeCreateGlobalPrivilege, processes on the same machine will not be able to connect with XNET, as the service runs in its own session.

You can configure this value if you have multiple Firebird servers running on the same machine which all need to be able to accept XNET connections. In that case, clients will need to be configured with that IpcName as well, either in their firebird.conf, or through isc_dpb_config.

Example

IpcName = FIREBIRD_2_5

Name of the pipe used as a transport channel in the WNET (a.k.a. NetBEUI) protocol (Windows only).

ConfigurationGlobal, client-side, and per-connection

Syntax

RemotePipeName = string

Defaultinterbas

Server-side, the configuration is used to create the pipe to accept WNET connections, and for creating WNET connections to other servers. Client-side, the configuration is used to open the pipe to make WNET connections to the server.

You can configure this value if you have multiple Firebird servers running on the same machine which all need to be able to accept WNET connections. In that case, clients will need to be configured with that RemotePipeName as well, either in their firebird.conf, or through isc_dpb_config.

Example

RemotePipeName = FIREBIRD_2_5

Configures how Firebird creates named Windows kernel objects, such as events, memory mapped files, etc. (Windows only).

ConfigurationGlobal

Syntax

UseLegacyKernelObjectsNames = Boolean

Defaultfalse

Since version 4.0.3, Firebird creates named kernel objects in a private namespace. This allows processes to interact within different Windows sessions, such as a user session and a service session. Also, it uses the engine version in some shared event names; this allows a single process to host Firebird engines of different versions.

This setting is for backward compatibility between Firebird 4.0 releases only, and is not present in Firebird 5.0 and higher. Enabling it allows simultaneous running of processes of newer (>= 4.0.3) and older (< 4.0.3) subreleases of Firebird 4.0.

Example

# Enable legacy behaviour
UseLegacyKernelObjectsNames = true

Allow multi-hop connections to other Firebird servers.

ConfigurationGlobal

Syntax

Redirection = Boolean

Default0 (false)

A multi-hop connection allows you to redirect a connection to a database through intermediate servers.

With this setup, a connection string specifies a list of servers to connect through, where the last server is the server that actually hosts the database.

For example, with the connection string host1:host2:database, the client will connect to host1 with the database host2:database. If host1 has redirection enabled, it will — without authentication on host1 — forward the connection to host2 to open database database — where the connection will be authenticated. Packets will be routed through host1 between host2 and the client.

In effect, host1 serves as a pass-through proxy to host2.

Example

# Explicitly disable redirection
Redirection = 0

Configures database access, process, and caching behaviour of the Firebird engine.

ConfigurationGlobal

Syntax

ServerMode =
  { Super | ThreadedDedicated
  | SuperClassic | ThreadedShared
  | Classic | MultiProcess }

DefaultSuper

The ServerMode affects how Firebird opens databases, and the memory use per attachment. There is no single best choice.

Example

ServerMode = SuperClassic

Maximum number of inactive (idle) connections in the external connections pool.

ConfigurationGlobal

Syntax

ExtConnPoolSize = integer

Range0 - 1000

Default0 (disabled)

The external connections pool is a connection pool for the external data source (EDS) subsystem. For details, consult Pooling of External Connections in the Firebird 3.0 Release Notes.

As the connection pool is per process, for Classic this means it is effectively per connection.

Example

ExtConnPoolSize = 20

The number of seconds a connection can be idle in the external connections pool before it is closed.

ConfigurationGlobal

Syntax

ExtConnPoolLifeTime = integer

UnitSecond

Range1 - 86400 (1 second to 24 hours)

Default7200 (2 hours)

When an external connection is returned to the idle list of the pool, a timer is started. At or after this timer reaches ExtConnPoolLifeTime, the connection will be closed and removed from the pool.

The timer is stopped and cleared when the connection is returned to the active list of the pool.

The external connections pool is a connection pool for the external data source (EDS) subsystem. For details, consult Pooling of External Connections in the Firebird 3.0 Release Notes.

Example

# 1.5 hours
ExtConnPoolLifeTime = 5400