Firebird Documentation IndexFirebird 3.0.6 Release Notes → Changes to the Firebird API and ODS
Firebird Home Firebird Home Prev: Miscellaneous ImprovementsFirebird Documentation IndexUp: Firebird 3.0.6 Release NotesNext: Application Programming Interfaces

Chapter 4: Changes to the Firebird API and ODS

as at Release 3.0

Table of Contents

ODS (On-Disk Structure) Changes
Application Programming Interfaces

ODS (On-Disk Structure) Changes

New ODS Number

Firebird 3.0 creates databases with an ODS (On-Disk Structure) version of 12. In the initial release, a database with an older ODS cannot be opened by Firebird 3.0. In order to work with a database with an older ODS it will be necessary to make a backup using gbak under the older server and restore it with gbak on Firebird 3.

Note

A legacy provider for databases with ODS 8 to 11.2 is planned for a future sub-release.

Firebird 3.0.4: ODS 12.2 for POSIX Platforms

In the V.3.0.4 sub-release we have a minor ODS change for databases created or restored on a Linux x86 (32-bit) platform and all other POSIX platforms including MacOSX. The new ODS for these databases is 12.2.

The change is due to a change in the page layout of the system table RDB$GENERATORS affecting only some platforms. ODS 12.0 databases copied across platforms, e.g., from Linux-x86 to Linux-x64, show wrong values for generators, typically very large.

Other Platforms

The most popular platforms—Windows and Linux x64 (64-bit)—were not affected by the change. They were carefully checked to verify that, for them, there is no actual difference between ODS 12.0 and 12.2. To avoid disturbing users of these platforms with a new ODS, it was decided to retain the ODS number 12.0 for them.

For non-Windows and non-Intel-Linux platforms, developers could not perform all the required checks. The only guaranteed safe solution for them was the minor ODS upgrade.

To restate, MacOSX (32-bit and 64-bit) and 32-bit Linux builds will create (and restore) databases as ODS 12.2.

Existing databases (with ODS 12.0) are always opened successfully with Firebird 3.0.4 on the platform where they were initially created. Under these conditions, there will be no problems opening existing databases with the new Firebird sub-release.

Cross-Platform File-Copying

Cross-platform copying of any ODS 12.0 database other than those created on Windows and and Linux-x64 is best avoided: Firebird versions < V.3.0.3 may produce errors with generators, while V.3.0.4 will report an issue and not attach to such a database.

Our checks did not reveal any cross-platform compatibility issues between ODS 12.2 databases and ODS 12.0 databases from Windows and Linux-x64 with matching Endianness.

Implementation ID is Deprecated

Alex Peshkov

The Implementation ID in the ODS of a database is deprecated in favour of a new field in database headers describing hardware details that need to match in order for the database to be assumed to have been created by a compatible implementation.

The old Implementation ID is replaced with a 4-byte structure consisting of hardware ID, operating system ID, compiler ID and compatibility flags. The three ID fields are just for information: the ODS does not depend upon them directly and they are not checked when opening the database.

The compatibility flags are checked for a match between the database and the engine opening it. Currently we have only one flag, for endianness. As previously, Firebird will not open a database on little-endian that was created on big-endian, nor vice versa.

Sample gstat Output

# ./gstat -h employee
Database /usr/home/firebird/trunk/gen/Debug/firebird/examples/empbuild/employee.fdb
Database header page information:
        ..............
        Implementation          HW=AMD/Intel/x64 little-endian OS=Linux CC=gcc
        ..............
        

The purpose is to make it easier to do ports of Firebird for new platforms.

Maximum Database Size

Maximum database size is increased to 232 pages (previously 231 pages). The new limit is 16TB|32TB|64TB, depending on the page size.

Maximum Page Size

The maximum page size remains 16 KB (16384 bytes).

Maximum Number of Page Buffers in Cache

The maximum number of pages that can be configured for the database cache depends on whether the database is running under 64-bit or 32-bit Firebird:

  • 64-bit :: 231 -1 (2,147,483,647) pages

  • 32-bit :: 128,000 pages, i.e., unchanged from V.2.5

Extension of Transaction ID Space Limit

Dmitry Yemanov

Historically, transaction ID space was limited to 231 transactions, counted from the time the database was created. After that point, the database becomes unavailable until backup and restore is performed to reset the transaction ID counter back to zero. Initially in Firebird 3.0, the transaction ID space was raised to 232 transactions, doubling the database up-time without backup and restore.

This improvement request is about shifting that limit even further, with the introduction of 48-bit internal transaction IDs that are publicly (via the API and the MON$ tables) represented as 64-bit numbers. This makes the new limit roughly equal to 2.8 * 1014 transactions. Later, it could be extended up to the 263 limit.

The implemented solution has no additional storage overhead until the transaction counters grow beyond the 232 boundary.

Limits Raised for Attachment and Statement IDs

Attachment IDs and statement IDs were changed to 64-bit numbers, both internally and externally via the API and the MON$ tables.

System Tables

New System Tables

RDB$AUTH_MAPPING Stores authentication and other security mappings
RDB$PACKAGES Header for SQL packages
RDB$DB_CREATORS A list of users granted the CREATE DATABASE privilege when using the specified security database
SEC$USERS Virtual table to query the local user list
SEC$USER_ATTRIBUTES Virtual table storing local user attributes
SEC$DB_CREATORS SQL interface to access the list in RDB$CREATORS, i.e. select * from SEC$DB_CREATORS
SEC$GLOBAL_AUTH_MAPPING SQL interface to access the members of RDB$AUTH_MAPPING that have access to all databases using the specified security database, i.e. select * from SEC$GLOBAL_AUTH_MAPPING.
  For information about authentication mapping, see Mapping of Users to Objects in the Security chapter.

Changes to System Tables

From Firebird 3 forward, all non-virtual system tables (RDB$*) are read-only.

Note

In V. 3.0.4, the read-only restriction was relaxed to permit CREATE, ALTER and DROP operations on the indexes of system tables.

RDB$SYSTEM_FLAG

Claudio Valderrama C.

RDB$SYSTEM_FLAG has been made NOT NULL in all tables.

CORE-2787.

RDB$TYPES

Dmitry Yemanov

Missing entries were added to RDB$TYPES. They describe the numeric values for these columns:

  RDB$PARAMETER_TYPE     (table RDB$PROCEDURE_PARAMETERS)
  RDB$INDEX_INACTIVE     (table RDB$INDICES)
  RDB$UNIQUE_FLAG        (table RDB$INDICES)
  RDB$TRIGGER_INACTIVE   (table RDB$TRIGGERS)
  RDB$GRANT_OPTION       (table RDB$USER_PRIVILEGES)
  RDB$PAGE_TYPE          (table RDB$PAGES)
  RDB$PRIVATE_FLAG       (tables RdB$PROCEDURES and RDB$FUNCTIONS)
  RDB$LEGACY_FLAG        (table RDB$FUNCTIONS)
  RDB$DETERMINISTIC_FLAG (table RDB$FUNCTIONS)
              
Monitoring Tables

Dmitry Yemanov

Changes to Client Address Reporting

Prior to Firebird 3.0, the network address of remote clients were reported in MON$ATTACHMENTS.MON$REMOTE_ADDRESS and RDB$GET_CONTEXT('SYSTEM', 'CLIENT_ADDRESS'). For TCP/IP protocol (a.k.a. INET), it contained a TCPv4 dot-separated address. For Named Pipes (a.k.a. WNET, NetBeui) protocol, it was always NULL. For shared memory (aka XNET) protocol, it contained the local host name.

Starting with Firebird 3.0, the network address of a remote client contains the TCP/IP port number of the remote client, separated with a slash:

<IP address>/<port>
                  

The port number is also retrieved via the new built-in context variable RDB$GET_CONTEXT('SYSTEM', 'CLIENT_PORT').

The host name is also reported now, in the new column MON$REMOTE_HOST.

Alert

The WNET (Named Pipes/Netbeui) protocol should be considered as deprecated. It is likely to be abandoned in a future version.

Per-table performance counters added to the monitoring tables

Per-table performance counters have been added to all of the monitoring tables. See Tracker CORE-4564.

MON$ATTACHMENTS

New information is now available:

  • Operating system user name. See Tracker CORE-3779.

  • Protocol and client library version. See Tracker CORE-2780.

  • Client host name. See Tracker CORE-2187.

  • authentication method used for connection (MON$AUTH_METHOD). See Tracker CORE-4222.

  • MON$REMOTE_ADDRESS now contains the <IP>/<port> string. See Tracker CORE-5028.

MON$DATABASE
  • Database owner (MON$OWNER) added. See Tracker CORE-4218.

  • Security database type (MON$SEC_DATABASE) flag added. Value will be one of Default/Self/Other. See Tracker CORE-4729.

MON$STATEMENTS

The PLAN is now included. See Tracker CORE-2303.

Prev: Miscellaneous ImprovementsFirebird Documentation IndexUp: Firebird 3.0.6 Release NotesNext: Application Programming Interfaces
Firebird Documentation IndexFirebird 3.0.6 Release Notes → Changes to the Firebird API and ODS