Jaybird 5.0.4 Release Notes

The following has been changed or fixed since Jaybird 5.0.3:

The following has been changed or fixed since Jaybird 5.0.2:

The following has been changed or fixed since Jaybird 5.0.1:

The following has been changed or fixed since Jaybird 5.0.0:

First release of Jaybird 5.

There were no relevant changes compared to 5.0.0-beta-1.

Initial release for evaluation.

Jaybird 5 is — from a JDBC perspective — an incremental change from Jaybird 4. However, internally, Jaybird underwent some major changes, the biggest was the removal of JCA (Java Connector Architecture) support.

The major changes and new features in Jaybird 5 are:

Upgrading from Jaybird 4 to 5 should be simple, but please make sure to read Compatibility changes before using Jaybird 5. See also Upgrading from Jaybird 4 to Jaybird 5.

Bug reports about undocumented changes in behavior are appreciated. Feedback can be sent to the Firebird-java mailing list or reported on the issue tracker https://github.com/FirebirdSQL/jaybird/issues.

Jaybird 5.0.4 was tested against Firebird 2.5.9, 3.0.11, 4.0.4, and 5.0.0, but should also support other Firebird versions from 2.5 and up.

This driver does not support InterBase servers due to Firebird-specific changes in the protocol and database attachment parameters that are sent to the server.

Jaybird 5 supports Java 8 (JDBC 4.2), and Java 9 and higher (JDBC 4.3). Support for earlier Java versions has been dropped.

Given the limited support period for Java 9 and higher versions, we limit support to Java 8, 11, 17, 21 and the latest Java release. Currently, that means we support Java 8, 11, 17, and 21.

Jaybird 5 provides libraries for Java 8 and Java 11. The Java 8 builds have all JDBC 4.3 related functionality and can be used on Java 9 and higher as well, but the Java 11 version has additional features, like the ChaCha wire encryption.

Jaybird 5 is not modularized, but all versions declare the automatic module name org.firebirdsql.jaybird.

See also Java support in What’s new in Jaybird 5.

Jaybird supports the following specifications:

Change the version of the dependency to 5.0.4.<java> (where <java> is your Java version, java11 for Java 11 and higher, and java8 for Java 8). If you’re still using the artifact id jaybird-jdkXX, change it to jaybird.

When your Jaybird dependency defines the exclusion for javax.resource:connector-api (see below), you can remove it.

For more detailed instructions, see also the information on Maven in Getting Jaybird 5.

If you use native or embedded, make sure to update your JNA dependency to version 5.12.1 (Jaybird 5 requires at least JNA 5.0).

If you manage your dependencies manually, you need to do the following:

If you find a problem while upgrading, or other bugs: please report it on https://github.com/FirebirdSQL/jaybird/issues.

For known issues, consult Known issues.

Jaybird 5 supports Firebird version 2.5, 3.0, 4.0, and 5.0.

Jaybird 5 is the last version to support Firebird 2.5.

Jaybird no longer implements JCA, and no longer has a dependency on connector-api-1.5.jar.

See Removal of Java EE/Jakarta EE Connector Architecture (JCA) for details.

The Firebird wire protocol encryption plugin ChaCha — introduced in Firebird 4.0 — is now supported by the PURE_JAVA and OOREMOTE protocol implementations. Support is only available on Java 11 and higher using a Jaybird built for Java 11 or higher.

The implementation relies on the ChaCha20 cipher introduced by JEP 329.

Jaybird does not support the ChaCha64 wire protocol encryption. Support for ChaCha64 will be introduced in Jaybird 6.

The handling of connection properties for DriverManager, data sources and Jaybird internals was rewritten. The change is also documented in jdp-2020-10 and jdp-2021-01. This change has the following user-visible effects:

The properties used to configure the “address” (or “coordinates”) of a database or service have been unified and standardized.

Connections to a database are identified by a triplet of properties (serverName, portNumber, databaseName), and to a service with a triplet of properties (serverName, portNumber, serviceName).

The databaseName/serviceName property serves a dual purpose: if serverName is null, its value is handled as a connection URL which may or may not contain a server name and port number, otherwise it is only the database path or alias or service name. The syntax of databaseName as a connection URL is the same as the JDBC URL syntax, but without the jdbc:firebird[sql][:sub-protocol]: prefix and without connection properties. The exact supported syntax of connection URLs and their interpretation is determined by the protocol implementation (type or “sub-protocol”).

When serverName is null, the portNumber will be ignored unless the protocol requires a hostname, and databaseName doesn’t contain one. In that situation serverName is assumed to be localhost and portNumber is used.

Some examples that all identify the same database:

Some examples that all identify the same service:

These changes apply to FBConnectionPoolDataSource, FBSimpleDataSource, FBXADataSource, FirebirdConnectionProperties implementations, ServiceManager implementations, EventManager implementations, and — with some caveats — JDBC URLs.

The property database that existed on some of these interfaces and classes is now an alias for databaseName and deprecated for removal in Jaybird 6. The exception is database in ServiceManager. The database property on ServiceManager is still only a database path or alias and serves — for some ServiceManager implementations — as the database the service operation applies to (e.g. backup, restore).

The property host that existed on some of these interfaces and classes is now an alias for serverName and deprecated for removal in Jaybird 6. The same goes for port which is now an alias for portNumber.

As a result of Unification of database and service addressing and URL parser changes, JDBC URLs now allow:

The LOCAL protocol implementation (LocalGDSFactoryPlugin) has been removed. For backwards compatibility, the type-name LOCAL and the JDBC URL prefixes jdbc:firebird:local: and jdbc:firebirdsql:local: have been mapped to the NATIVE protocol implementation. This type name and these JDBC protocol prefixes should be considered deprecated and may be removed in a future Jaybird version.

The LOCAL protocol implementation was never really a local protocol, but — depending on fbclient version, its firebird.conf and platform — could also establish a TCP/IP, XNET, WNET or embedded connection to the database.

Establishing a local IPC connection to a database is only possible on Windows, using a Firebird 3.0 or higher fbclient with the databaseName xnet://C:\path\to\db.fdb or JDBC URL jdbc:firebird:native:xnet://C:\path\to\db.fdb. For earlier versions of fbclient, the recommended URL is jdbc:firebird:native:C:\path\to\db.fdb, but this will not necessarily use a local IPC connection.

Jaybird now defaults to creating stream blobs instead of segmented blobs. See jdp-2021-02 Stream blobs by default for more information.

To use segmented blobs, specify connection property useStreamBlobs with value false.

The “generated keys” parser has been replaced. This parser is used to detect statement types, the table name, and presence or absence of a RETURNING clause. The new parser has no external dependencies, so Jaybird no longer depends on the ANTLR runtime (org.antlr:antlr4-runtime).

As a result of this change, it is possible that detection of some statements has changed, especially detection of the presence of a RETURNING clause. Please report any incorrect changes in detection on the firebird-java list or on https://github.com/FirebirdSQL/jaybird/issues.

If you were relying on disabling generated keys support by excluding the antlr4-runtime library from the classpath, you will now need to explicitly disable it. Disabling generated keys can be done using the connection property generatedKeysEnabled with value disabled, or ignored if you don’t want an exception thrown when calling a generated-keys-related execute or prepare method.

This change was also backported to Jaybird 4.0.8.

Jaybird supports server-side batch updates introduced in Firebird 4.0.

This feature is only available on pure-java connections, and only on prepared statements (but not callable statements). Support is only available in pure-java, as the bindings for native and embedded use the legacy fbclient API, and batch updates are not (fully) exposed in the legacy fbclient API.

Two new properties have been added for this feature:

This support comes with a number of limitations:

When server-side batch support is unavailable, either because the server doesn’t support it, or because of above limitations, or if the connection property useServerBatch is false, Jaybird will fall back to the emulated behaviour.

By default, Jaybird will request the maximum server-side batch buffer size (256MB as of Firebird 4.0). A smaller buffer can be requested with connection property serverBatchBufferSize (value in bytes). Jaybird does not track the available size of the server-side batch buffer. Attempting to execute a batch larger than this buffer will fail with error “Internal buffer overflow - batch too big” (isc_batch_too_big, error code 335545198). The 256MB buffer used with Jaybird defaults on Firebird 4.0 is sufficient to accommodate several thousand rows at maximum row size (a naive calculation says around 4000 rows, but this doesn’t account for all overhead of a row).

Jaybird supports multi-row RETURNING introduced in Firebird 5.0.

The entire generated keys result set is retrieved immediately on execute. So, if the statement inserts, updates or deletes a significant number of rows, this can consume a lot of memory in Jaybird.

Jaybird supports server-side scrollable cursors introduced in Firebird 5.0.

This feature is only available on pure-java connections, and only when explicitly enabled with connection property scrollableCursor. Support is only available in pure-java, as the bindings for native and embedded use the legacy fbclient API, and scrollable cursors are not exposed in the legacy fbclient API.

The connection property scrollableCursor has the following values (case-insensitive):

If a connection does not support scrollable cursors, or if holdable cursors are requested, the behaviour will silently fall back to emulated scrollable cursors.

Compared to emulated scrollable cursor, server-side scrollable cursors exhibit slightly different behaviour (we may change the behaviour of emulated later in Jaybird 5 or in a future Jaybird release):

See also jdp-2021-04.

The Firebird Embedded locator service provider is an experimental feature to load Firebird Embedded from the classpath. This requires an additional library implementing the service provider interface (SPI) and providing the necessary Firebird Embedded binaries for the runtime platform.

This feature should be considered highly experimental. It may change in point releases, and may get dropped in future Jaybird major versions. The project does not provide libraries implementing the SPI at this time. As we have only successfully tested this on Windows, it is possible that — at least initially — only Windows versions of such a library will be released by the project.

For details, see jdp-2020-05: Firebird Embedded locator service provider.

A new class was added, org.firebirdsql.management.FBTableStatisticsManager, which can be used to retrieve the table statistics of a connection.

Create an instance with FBTableStatisticsManager#of(java.sql.Connection) — the connection must unwrap to a FirebirdConnection — and retrieve a snapshot of the statistics with FBTableStatisticsManager#getTableStatistics().

Jaybird 5 contains a number of changes that might break existing applications.

See also Compatibility changes for details.

See Removal of deprecated classes, packages and methods in Compatibility changes for more details.

Jaybird 5 does not support Java 7. You will need to upgrade to Java 8 or higher, or remain on Jaybird 4.

The Java EE/Jakarta EE Connector Architecture (JCA) implementation that was the core of Jaybird has been removed. The package org.firebirdsql.jca no longer exists, and it is no longer possible to use Jaybird as a JCA connector (Resource Adapter).

From its inception, Jaybird has been built around the — then new — JCA specification. Unfortunately, this had the side effect that Jaybird required the JCA api (connector-api) as a dependency. As far as we know, Jaybird was hardly used as a JCA connector, while at the same time it hindered development, as the JCA implementation was central to Jaybird. Lack of testing as a JCA connector also meant it was unclear if Jaybird actually functioned correctly as such.

To reduce development overhead, we have decided to remove support for JCA from Jaybird. A lot of classes previously in the org.firebirdsql.jca package are now in the package org.firebirdsql.jaybird.xca. This new package is marked as internal API and is not binary compatible with the old JCA implementation. Where possible, classes in this package have been declared final. Be aware that the API and implementation of the classes in this package can change in any point release.

If there turns out to be actual demand for JCA support in Jaybird after all, we will consider creating new support for JCA in a way that does not require JCA when using Jaybird as a JDBC driver. Contact us on the firebird-java list if you’re interested in such a solution.

As a result of this change, org.firebirdsql.jdbc.FBDataSource is now considered internal API as well. For normal data sources, look at the classes in the package org.firebirdsql.ds.

The handling of connection properties was refactored significantly to remove a lot of code duplication and other forms of repetition. As a result of this, a number of incompatibilities arise:

Previously, support for generated keys depended on the presence of the antlr4-runtime library on the classpath. With New parser for generated keys handling, generated keys support is now always available.

See New parser for generated keys handling for information on disabling or ignoring generated keys support if you relied on this behaviour.

With the introduction of server-side batch updates, it is possible that execution of a very large batch fails with error “Internal buffer overflow - batch too big” (isc_batch_too_big, 335545198).

There are two possible solutions for this error:

The maximum server-side batch buffer should be sufficient to have a batch of around 4000 rows with the maximum row size (around 64KB), more rows are possible for smaller row sizes.

The methods DatabaseMetaData.getColumnPrivileges and DatabaseMetaData.getTablePrivileges previously returned the privilege name REFERENCE in result set column PRIVILEGE. This has been changed to REFERENCES to match both the name of the privilege in the GRANT statement, and the name used in the JDBC 4.3 documentation.

Given recent Firebird versions have significantly improved support for built-in functions, and UDFs are now deprecated, the support to map JDBC function escapes to UDFs from ib_udf instead of built-in functions using the boolean connection property useStandarUdf[sic] has been removed.

As a result, the following methods, constants, properties and others are no longer available:

The following breaking changes were made to the internal API, like the GDS-ng API in org.firebirdsql.gds.ng and sub-packages. These changes are primarily interesting for implementers of custom GDS-ng implementations or forks of Jaybird, or people using these low-level APIs directly.

The following changes might cause issues, though we think this is unlikely:

With Jaybird 6 the following breaking changes will be introduced.

Jaybird uses JNA (Java Native Access) to access the client library. If you want to use the Type 2 driver, or Firebird embedded, then you need to include jna-5.12.1.jar on the classpath.

When using Maven, you need to specify the dependency on JNA yourself, as we don’t depend on it by default (it is specified as an optional dependency):

The fbclient.dll, fbembed.dll, libfbclient.so, or libfbembed.so need to be on the path, or the location needs to be specified in the system property jna.library.path (as an absolute or relative path to the directory/directories containing the library file(s)).

For Windows and Linux, you can add the org.firebirdsql.jdbc:fbclient dependency on your classpath to provide the native libraries for the native and local protocol. Be aware that this dependency does not support embedded.

In Jaybird 6 we will move the Type 2 support to a separate library. In the future we may provide JARs with the embedded libraries of a specific Firebird version.