Introduction
This document describes the Firebird wire protocol.Most of the information was obtained by studying the Firebird source code and implementing the wire protocol in the {net-provider-url}[Firebird .NET provider] and {jaybird-url}[Jaybird (Firebird JDBC driver)].
The protocol is described in the form of the message sent by the client and received from the server.The described protocol is Firebird/InterBase protocol version 10.Earlier (InterBase) versions of the protocol are not in scope for this document.Changes in later protocol versions are described in notes below the description of the relevant version 10 message (currently higher versions are only partially described), or the base message introduced in a later protocol version.Protocol changes to an existing message are generally additive (new fields are added to the end of a message) and cumulative (also apply for higher protocol versions), unless explicitly indicated otherwise.
This document is not complete.Consult the InterBase 6 API Guide for additional information on subjects like parsing the status vector, information request items, and the meaning of operations.You can find this manual under “InterBase 6.0 Manuals” in the {firebird-site}/en/reference-manuals/[Reference Manuals] section of the Firebird website.We also recommend consulting the Firebird sources and other wire protocol implementations.
Unless otherwise indicated, a client request must be flushed to the server for processing.For some operations the flush can be deferred, so it is sent together with a different operation.Versions 11 and higher of the wire protocol explicitly support (or even require) deferring of operations, including deferring the read of the response.
In the protocol descriptions below, we include the names of the fields of the structs used in the Firebird sources;this can make it easier to search for how it’s used in Firebird itself.
Protocol versions
Below is a high-level overview of the changes per protocol versions.
Be aware that protocol version greater than 10 are OR’ed with 0x8000
(FB_PROTOCOL_FLAG
) to differentiate them from newer InterBase protocol versions with the same number.In message exchanges like [wireprotocol-op-connect], this masked version is used, while for example the database info item fb_info_protocol_version
reports the bare version.
Protocol 10
The “baseline” protocol of this document.It was introduced in InterBase 6.0, and available in Firebird 1.0 and higher.
Protocol 11
Protocol 11 was introduced in Firebird 2.1.It introduces support for batching of messages, and lazy — or deferred — responses.
Specifically, it allows you to batch a message creating an object (e.g. a statement or blob), with subsequent operations on that object (e.g. information request, statement prepare, blob get, etc.) by using the invalid object handle (0xFFFF
) instead of the actual handle.This reduces latency, as you don’t have to wait for the server response to the create operation — containing the actual handle — before you can use the object.
In some cases, with ptype_lazy_send
, the server will defer the response to an operation until a subsequent operation is performed.For example, the response to statement allocation (op_allocate
) is withheld, in the expectation that a prepare (op_prepare
) follows immediately.
Similarly, freeing a statement (op_free_statement
) will not send its response immediately.This means that processing the response to a free can only be done later, after sending another operation, and before processing the response to that other operation.
Caution
|
The invalid object handle refers to the latest object created.So, while you can batch multiple create operations with use of those objects in a single send, you cannot interleave operations on different objects. That is, “create object1, use object1, create object2, use object2” will work, but “create object1, create object2, use object1, use object2” will not work or result in unwanted effects, as after create object2 handle |
Protocol 11 also introduced “trusted” authentication, which is not (yet) documented.
Protocol 12
Protocol 12 was introduced in Firebird 2.5.It provides asynchronous cancellation support.
Protocol 13
Protocol 13 was introduced in Firebird 3.0.It provides the following new features:
-
Authentication plugin support
-
Wire protocol encryption
-
Wire protocol compression
-
Database encryption key callback
-
Packed (
NULL
-aware) row data
Protocol 14
Protocol 14 was introduced in Firebird 3.0.1 to fix a bug in [wireprotocol-op-crypt-key-callback].
We recommend skipping separate implementation of this protocol version, and implement it as part of protocol 15.
Protocol 15
Protocol 15 was introduced in Firebird 3.0.2 and provides the following new features:
-
Support for [wireprotocol-op-crypt-key-callback] in the connect phase.This allows connections to encrypted databases that serve as their own security database.
Protocol 16
Protocol 16 was introduced in Firebird 4.0 and provides the following new features:
-
Statement timeouts
Protocol 17
Protocol 17 was introduced in Firebird 4.0.1 and provides the following new features:
-
Batch information request (not yet documented)