1. Jaybird 5.0.x changelog

Changes per Jaybird 5 release. See also What’s new in Jaybird 5. For known issues, consult Known issues.

1.1. Jaybird 5.0.6

The following has been changed or fixed since Jaybird 5.0.5:

  • Fixed: Exceptions during statement execution did not always complete the statement, which could delay transaction commit in auto-commit mode (#806)

    This fix was backported from Jaybird 6.

  • Fixed: Closing a connection when the database was shutdown, or the connection was otherwise broken, could result in a NullPointerException (#812)

    This fix was backported from Jaybird 6.

  • Fixed: Error “Column unknown; IND.RDB$CONDITION_SOURCE” when calling DatabaseMetaData.getIndexInfo on Firebird 5.0 with a Firebird 4.0 (ODS 13.0) database (#813)

    The partial index metadata support introduced in Jaybird 5.0.5 did not take into account that Firebird 5.0 could also open a Firebird 4.0 database.

  • Fixed: Calling ResultSet.wasNull() when on the insert-row throws a SQLException instead of reporting the null-state of the last retrieved column (#816)

    As part of this fix, we no longer check if wasNull() is called on a row, or after getting a column value, as the JDBC API does not require such check. Instead, false is reported if not currently on a row, or if no column value was retrieved, and an exception is thrown if the result set is closed. The value reported by wasNull() is reset to false on each cursor move (e.g. next()), and modified by each getXXX call.

  • Fixed: Inserting a row into a result set backed by a server-side scrollable cursor could include the inserted row twice (#819)

    This could happen if the insert was performed when the server-side cursor was not fully materialized (e.g. by inserting the row immediately after execute). As the server-side cursor is only fully materialized on certain operations like requesting the cursor size, the inserted row could be included in the server-side cursor, as well as the local inserted rows collection.

  • Improvement: Updated JNA dependency to version 5.15.0 (#823)

    If you use native or embedded connections, make sure the upgrade the JNA dependency to JNA 5.15.0 by replacing the JAR or updating the JNA (net.java.dev.jna:jna) version number in your build configuration. In practice, Jaybird should still be able to work with JNA 5.12.1 (used in Jaybird 5.0.0 — 5.0.4), and JNA 5.14.0 (used in Jaybird 5.0.5).

1.2. Jaybird 5.0.5

The following has been changed or fixed since Jaybird 5.0.4:

  • Fixed: FBResultSetMetaData.getPrecision would always estimate the precision of NUMERIC or DECIMAL columns instead of obtaining the actual precision if the column position was 71 or higher (#731)

    This fix was backported from Jaybird 6.

  • Optimized the query to retrieve extended field info for ResultSetMetaData.getPrecision to only retrieve columns of type NUMERIC or DECIMAL (#732)

    This improvement was backported from Jaybird 6.

  • Fixed: PreparedStatement.executeBatch() of statement without parameters throws “Statement used in batch must have parameters [SQLState:07001, ISC error code:335545186]” on Firebird 4.0 or higher (#788)

    Given the Firebird server-side batch facility doesn’t support executing parameterless statements, the implementation now falls back to emulated batch execution for this case.

  • New feature: ResultSetMetaData.isAutoIncrement(int) reports true for identity columns if Jaybird can identify the underlying table and column (#793)

    This feature was backported from Jaybird 6.

  • New feature: Boolean connection property extendedMetadata (default true) to disable querying of extended metadata for getPrecision(int) and isAutoIncrement(int) of ResultSetMetaData (#795)

    Disabling extended metadata may improve performance of these ResultSetMetaData methods in exchange for estimated precision information of NUMERIC and DECIMAL columns, and not being able to determine the auto-increment status of INTEGER, BIGINT or SMALLINT columns.

    This feature was backported from Jaybird 6.

  • Improvement: The FILTER_CONDITION of DatabaseMetaData.getIndexInfo is populated for Firebird 5.0 partial indices (#797)

    This improvement was backported from Jaybird 6.

  • Fixed: ResultSet.isBeforeFirst() and ResultSet.isAfterLast() should always report false for an empty result set (#807)

  • Improvement: Statement.getResultSet no longer throws a SQLException with message “Only one result set at a time/statement” if the current result set has already been returned by executeQuery or a previous call to getResultSet (#762)

    Repeated calls to getResultSet will now return the current result set. As part of this change implementations of FirebirdStatement.getCurrentResultSet now simply return getResultSet, and the getCurrentResultSet method has been deprecated for removal in Jaybird 7.

    This improvement was backported from Jaybird 6.

  • Improvement: Updated JNA dependency to version 5.14.0 (#810)

    If you use native or embedded connections, make sure the upgrade the JNA dependency to JNA 5.14.0 by replacing the JAR or updating the JNA (net.java.dev.jna:jna) version number in your build configuration. In practice, Jaybird should still be able to work with JNA 5.12.1 (the version used in Jaybird 5.0.0 — 5.0.4).

1.3. Jaybird 5.0.4

The following has been changed or fixed since Jaybird 5.0.3:

  • Firebird 5.0 is now formally supported

  • Fixed: Potential NPE when warningMessageCallback is null while reading operations or consuming packets (#778)

    As part of this change, the constructor AbstractWireOperations now explicitly requires the connection and defaultWarningMessageCallback to be non-null and throws a NullPointerException otherwise. This may affect custom protocol implementations extending AbstractWireOperations and/or calling ProtocolDescriptor#createWireOperations(WireConnection, WarningMessageCallback): make sure you don’t pass null.

  • Fixed: FBRowUpdater incorrectly considers result set with only partial PK updatable — backported from Jaybird 6 (#780)

    This change also improves performance of updateRow(), insertRow(), deleteRow() and refreshRow(). The best row identifier or RDB$DB_KEY were detected each time when calling updateRow(), insertRow(), deleteRow(), or refreshRow(). This has been improved so this detection is done once, and in a way that non-updatable result sets can now be downgraded to CONCUR_READ_ONLY instead of throwing an exception when performing the modification.

  • Fixed: Use of offset timezone names (e.g. +05:00) for sessionTimeZone would result in a warning being logged, and an incorrect conversion applied (in UTC instead of the offset) when using the legacy time types — backported from Jaybird 6 (#787)

1.4. Jaybird 5.0.3

The following has been changed or fixed since Jaybird 5.0.2:

  • Improvement: Do not reject attempts to read blob id 0 — backported from Jaybird 6 (#765)

    Previously, Jaybird rejected attempts to read blobs with blob id 0 (not on all code paths, for some only when assertions are enabled). Formally, blob id 0 is not a valid blob id, but in practice they can occur (e.g. due to bugs, or access components/drivers explicitly setting a blob column to id 0). Other drivers and tools simply send the requests for blob id 0 to the server, which then treats it as an empty blob. For consistency, we decided to let Jaybird handle it the same.

  • Fixed: on CHAR fields, a too short value could be returned if the string contained one or more codepoints represented by surrogate pairs and the string length in char exceeded the maximum string length — backported from Jaybird 6 (#770)

    We now truncate the returned string if the codepoint count exceeds the maximum string length.

  • Fixed: CallableStatement.getXXX(String) could return value from wrong column — backported from Jaybird 6 (#772)

  • Updated: error messages updated from Firebird 5.0.0.1272

1.5. Jaybird 5.0.2

The following has been changed or fixed since Jaybird 5.0.1:

  • Fixed: Reconnect transaction with a transaction id exceeding 0x7FFF_FFFF did not work (#734)

  • New feature: add connection property parallelWorkers to set Firebird 5.0 isc_dpb_parallel_workers (#737)

  • New feature: add MaintenanceManager.upgradeOds() for the Firebird 5.0 gfix/service repair action to perform a minor ODS upgrade of a database (#738)

  • New feature: add parallel workers support for BackupManager (#739)

  • New feature: add parallel workers support for sweep in MaintenanceManager (#740)

  • Fixed: DatabaseConnectionProperties.setServerBatchBufferSize(int) ignored provided value and always set default (0, or “use server-side maximum”) (#741)

    This bug did not affect connection property serverBatchBufferSize set through the JDBC URL or provided in a Properties object to DriverManager, it only affected the property set through implementations of DatabaseConnectionProperties (e.g. data sources from org.firebirdsql.ds).

  • New feature: add MaintenanceManager.fixIcu() for the Firebird 3.0 gfix/service repair action “ICU” to update or rebuild collations and indexes when the ICU version changed (#744)

  • Fixed: The first call to getTableStatistics() of a FBTableStatisticsManager instance returned only a few or even no tables; if no tables were returned, subsequent calls would also return no tables (#747)

    Truncation of the information response will now result in three retries (so, four attempts), increasing the buffer size for each retry. If after three retries, the buffer is still truncated, an InfoTruncatedException exception is thrown. Subsequent attempts to call getTableStatistics() may succeed as that will further increase the buffer size.

1.6. Jaybird 5.0.1

The following has been changed or fixed since Jaybird 5.0.0:

  • Fixed: Executing DML with a RETURNING clause containing a blob column would return the blob-id instead of the blob value (#728)

  • Fixed: CallableStatement.getString and CallableStatement.getObject would incorrectly trim string values (#729)

  • Fixed: ResultSetMetaData.getPrecision(int) of a connectionless result set could throw a NullPointerException if the column was of type FLOAT or DOUBLE PRECISION (#730)

1.7. Jaybird 5.0.0

First release of Jaybird 5.

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

1.8. Jaybird 5.0.0-beta-1

Initial release for evaluation.

2. Known issues

  • Using a native connection with a Firebird 3.0 or higher client library to a Firebird 2.5 or older server may be slow to connect.

    Possible workarounds:

    • Use a native URL with the Firebird INET4 protocol (e.g. for DriverManager jdbc:firebird:native:inet4://<serverName>[:<portNumber>]/<databaseName>).

    • Use the IPv4 address instead of the host name in the connection string

    • Use a Firebird 2.5 or earlier fbclient.

    This is caused by firebird#4971

3. Support

If you need support with Jaybird, join the Firebird-Java Google Group and mailing list. You can subscribe by sending an email to [email protected].

Looking for professional support of Jaybird? Jaybird is now part of the Tidelift subscription.

See also Where to get help

4. General Notes

Jaybird is a JDBC driver suite to connect to Firebird database servers from Java and other Java Virtual Machine (JVM) languages.

This driver does not work on Android, because it uses classes and features not available in Android.

4.1. About this version

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.

4.2. Supported Firebird versions

Jaybird 5.0.6 was tested against Firebird 2.5.9, 3.0.12, 4.0.5, and 5.0.1, 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.

4.3. Supported Java versions

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, 21, and 23.

Jaybird 5 will be the last version to support Java 8 and 11. Jaybird 6 will use Java 17 as the baseline (minimum) version. We highly recommend upgrading to Java 17 or higher.

Jaybird 5 will serve as a “long-term support” version for Java 8 and 11, with maintenance releases at least until the release of Jaybird 7.

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.

4.4. Specification support

Jaybird supports the following specifications:

Specification Notes

JDBC 4.3

All JDBC 4.3 methods for features supported by Firebird; Java 9 and higher supported using the Java 8 or Java 11 driver.

JDBC 4.2

All JDBC 4.2 methods for features supported by Firebird.

JTA 1.0.1

Implementation of javax.transaction.xa.XAResource interface via XADataSource implementation.

5. Getting Jaybird 5

5.1. Jaybird 5.0.6

5.1.1. Maven

Jaybird 5.0.6 is available on Maven Central:

groupId

org.firebirdsql.jdbc
artifactId

jaybird
version

5.0.6.<java> (where <java> is java11 or java8)

For example:

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird</artifactId>
    <version>5.0.6.java11</version>
</dependency>

If you want to use Type 2 support (native or embedded), you need to explicitly include JNA 5.15.0 as a dependency:

<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna</artifactId>
    <version>5.15.0</version>
</dependency>

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

See also Type 2 (native) and embedded driver.

5.1.2. Download

You can download the latest versions from https://firebirdsql.org/en/jdbc-driver/

At minimum, Jaybird 5 requires jaybird-5.0.6.<java>.jar (where <java> is java11 or java8).

For native or embedded support, you will need to include jna-5.15.0.jar on your classpath. See also Type 2 (native) and embedded driver.

6. Upgrading from Jaybird 4 to Jaybird 5

Please make sure to read Compatibility changes before upgrading to Jaybird 5.

6.1. Maven

Change the version of the dependency to 5.0.6.<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.

<exclusions>
    <exclusion>
        <groupId>javax.resource</groupId>
        <artifactId>connector-api</artifactId>
    </exclusion>
</exclusions>

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.15.0 (Jaybird 5 requires at least JNA 5.0, but we recommend using JNA 5.15.0).

<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna</artifactId>
    <version>5.15.0</version>
</dependency>

6.2. Manual install

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

  1. Replace the Jaybird 4 library with the Jaybird 5 version

    • jaybird-4.0.x.<java>.jar with jaybird-5.0.6.<java>.jar (where <java> is java11 or java8)

    • jaybird-full-4.0.x.<java>.jar with jaybird-5.0.6.<java>.jar, the jaybird-full library no longer exists

  2. Replace the jna-5.5.0.jar library (or any JNA version before 5.15.0) with jna-5.15.0.jar

    This library is only needed if you actually use native or embedded connections, otherwise remove JNA (assuming your application itself or other dependencies don’t use it).

  3. Remove the connector-api-1.5.jar library, it is no longer used by Jaybird

  4. Remove the antlr4-runtime-4.7.2.jar library, it is no longer used by Jaybird

6.3. Gotcha’s

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.

7. What’s new in Jaybird 5

For a full list of changes, see Firebird tracker for Jaybird 5.

7.1. Java support

7.1.1. Java 7 support dropped

Java 7 is no longer supported. See also jdp-2020-02 Drop Java 7 support.

7.1.2. Java 8

The driver supports Java 8.

Jaybird 5 is the last version to support Java 8

7.1.3. Java 9 and higher

Jaybird 5 supports Java 9 and higher (JDBC 4.3) with the Java 8 and 11 version of the driver. Most of the JDBC 4.3 features have been implemented (in as far as they are supported by Firebird).

You can use the Java 8 driver under Java 9 and higher. For Java 11 or higher we recommend using the Java 11 driver, as it provides additional features (e.g. ChaCha wire encryption).

Given the limited support period for Java 9 and higher versions, not all Java releases are supported, see Supported Java versions for details.

For compatibility with Java 9 modules, Jaybird defines the automatic module name org.firebirdsql.jaybird. This guarantees a stable module name for Jaybird, and allows for future modularization of Jaybird.

Jaybird 5 is the last version to support Java versions earlier than Java 17.

7.2. Firebird support

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.

7.3. Java Connector Architecture (JCA) support removed

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.

7.4. ChaCha wire protocol encryption support

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.

7.5. Changes to properties

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:

  1. Jaybird-specific connection properties no longer have an alias with prefix isc_dpb_. Aliases with prefix isc_dpb_ are now only available for actual Firebird connection properties.

    If you used connection properties starting with isc_dpb_, the solution is to remove isc_dpb_ from the property name.

  2. A number of connection properties getter/setter pairs on data sources and management APIs have been deprecated — for removal in Jaybird 6 — in favour of a new name for consistency or better naming.

    • get/setDatabase — use get/setDatabaseName (see also Unification of database and service addressing).

    • get/setPort — use get/setPortNumber (see also Unification of database and service addressing).

    • get/setHost — use get/setServerName (see also Unification of database and service addressing).

    • get/setUserName — use get/setUser, only deprecated, will not be removed

    • get/setConnectionDialect() — use get/setSqlDialect().

    • get/setBuffersNumber — use get/setPageCacheSize.

    • get/setBlobBufferLength — use get/setBlobBufferSize.

    • getNonStandardProperty(String)/setNonStandardProperty(String,String) — use getProperty(String)/setProperty(String,String).

  3. The various interfaces defining connection properties (e.g. for data sources) now all share a common interface org.firebirdsql.jaybird.props.DatabaseConnectionProperties (for database connections) or org.firebirdsql.jaybird.props.ServiceConnectionProperties (for service connections).

  4. Type of get/setWireCrypt was changed from WireCrypt to String — use get/setWireCryptAsEnum to be able to use the enum WireCrypt.

7.6. Unification of database and service addressing

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:

  • (serverName = "localhost", portNumber = 3050, databaseName = "/path/to/db.fdb")

  • (serverName = null, portNumber = 3050, databaseName = "//localhost//path/to/db.fdb")

  • (serverName = null, portNumber = 3050, databaseName = "localhost:/path/to/db.fdb")

  • (serverName = null, portNumber = 3050, databaseName = "////path/to/db.fdb") — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

  • (serverName = null, portNumber = 3050, databaseName = "/path/to/db.fdb") — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

Some examples that all identify the same service:

  • (serverName = "localhost", portNumber = 3050, serviceName = "service_mgr")

  • (serverName = "localhost", portNumber = 3050, serviceName = null)

  • (serverName = null, portNumber = 3050, serviceName = "//localhost")

  • (serverName = null, portNumber = 3050, serviceName = "//localhost/")

  • (serverName = null, portNumber = 3050, serviceName = "//localhost/service_mgr")

  • (serverName = null, portNumber = 3050, serviceName = "///service_mgr")  — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

  • (serverName = null, portNumber = 3050, serviceName = "//")  — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

  • (serverName = null, portNumber = 3050, serviceName = "service_mgr")  — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

  • (serverName = null, portNumber = 3050, serviceName = null)  — for NATIVE and EMBEDDED, this may result in an embedded connection instead of through localhost.

  • (serverName = null, portNumber = 3050, serviceName = "host/3050:") — for PURE_JAVA the : is required, otherwise host/3050 is taken as the service name, for NATIVE and EMBEDDED behaviour will depend on the client version and connected Firebird version

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.

7.7. Changes to JDBC URL syntax

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

  1. More lenient syntax

  2. NATIVE (and EMBEDDED) now supports new Firebird 3.0+ URL formats

  3. Specification of part or entire database address through connection properties

7.7.1. More lenient syntax

The syntax of JDBC URLs is now more lenient.

  • In the standard syntax (starting with “jdbc:firebird[sql][:sub-protocol]://”), specifying server name and port number are now optional, but server name must be specified if a port number is specified. For example, jdbc:firebird:////path/to/db.fdb or jdbc:firebird:///C:\path\to\db.fdb is now allowed and connects to localhost port 3050, database /path/to/db.fdb or C:\path\to\db.fdb.

  • For PURE_JAVA, localhost and port 3050 are used as defaults, for other protocol implementations the behaviour will vary. For example, for NATIVE it will depend on the version of fbclient and the configured providers in its firebird.conf.

  • For PURE_JAVA, in the legacy syntax, server name and port number are now optional as well. For example, jdbc:firebird:/path/to/db.fdb is now allowed and connects to localhost port 3050, database /path/to/db.fdb.

  • JDBC URLs that only contain a Windows path will no longer interpret the drive letter as a server name. For example, jdbc:firebird:C:\path\to\db.fdb and jdbc:firebird:C:/path/to/db.fdb is now allowed and connects to localhost port 3050, database C:\path\to\db.fdb or C:/path/to/db.fdb.

    In theory, this results in a minor backwards incompatibility for URLs with the legacy syntax using single character server names. If this is an issue for you, the solution is to use the standard syntax (with “//”).

  • If the database address is specified through connection properties (see also Specification of part or entire database address through connection properties), the URL can consist only of the JDBC URL prefix. For example, jdbc:firebird: is now a legal URL, if at least databaseName is specified as a connection property in the Properties object passed to DriverManager.getConnection(String, Properties).

7.7.2. NATIVE (and EMBEDDED) now supports new Firebird 3.0+ URL formats

The NATIVE protocol implementation (and technically the EMBEDDED protocol as well), now support the Firebird 3.0 and higher URL formats. The reason is that for the NATIVE protocol, Jaybird now only parses standard syntax URLs (those that start with “//”), and passes all other values to fbclient without further interpretation or parsing.

Some examples that are now valid (assuming a Firebird 3.0 or higher fbclient is used):

  • jdbc:firebird:native:inet://myserver//path/to/db.fdb

  • jdbc:firebird:native:inet4://myserver//path/to/db.fdb — Use IPv4 only

  • jdbc:firebird:native:inet6://myserver//path/to/db.fdb — Use IPv6 only

  • jdbc:firebird:native:xnet://C:\path\to\db.fdb — Windows only

  • jdbc:firebird:native:wnet://C:\path\to\db.fdb — Windows only

  • jdbc:firebird:native:wnet://myserver/C:\path\to\db.fdb — Windows only

  • jdbc:firebird:native:wnet://myserver:fb_db/C:\path\to\db.fdb — Windows only

Support for the WNET protocol is removed in Firebird 5.0.

7.7.3. Specification of part or entire database address through connection properties

The JDBC URL after the protocol prefix up to the ‘?’ or — if no properties are defined in the URL — the end of the URL defines the databaseName property. It is now possible to specify some or all of the address of the database (serverName, portNumber, databaseName) through connection properties. When databaseName is also specified as a connection property, it overwrites the value derived from the URL itself. When serverName is specified as a connection property, the databaseName value (derived from the URL or explicitly set) will be used as the database path or alias. When portNumber is specified as a connection property, it will only be used when serverName is specified, or if databaseName doesn’t seem to contain a server name and the protocol implementation falls back to localhost.

Some examples:

  • jdbc:firebird:?serverName=localhost&portNumber=3050&databaseName=/path/to/db.fdb

  • jdbc:firebird: with Properties with "serverName" = "localhost", "portNumber" = "3050", "databaseName" = "/path/to/db.fdb", and user and password as required

  • jdbc:firebird:/path/to/db.fdb?serverName=localhost&portNumber=3050

  • jdbc:firebird:?databaseName=//localhost//path/to/db.fdb

  • jdbc:firebird://localhost//path/to/db.fdb?serverName=myserver — this will attempt to connect to database //localhost//path/to/db.fdb on server myserver (which will likely fail)

  • jdbc:firebird://localhost//path/to/db.fdb?databaseName=//myserver//path/to/other.fdb — this will connect as if you had used jdbc:firebird://myserver//path/to/other.fdb

Just because you can do this, doesn’t mean you should!

We recommend not to specify serverName, portNumber and databaseName as explicit connection properties when using DriverManager, but instead only use the URL itself to define the address of the database.

The behaviour defined in this section is the result of unification and simplification of connection property handling across JDBC URLs, data sources and internals of Jaybird.

7.8. Removal of LOCAL protocol implementation

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.

7.9. Stream blobs are now the default

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.

7.10. New parser for generated keys handling

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.

7.11. Firebird 4.0 server-side batch updates

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:

  • useServerBatch — a Boolean property to enable or disable server-side batch, default is true. When set to false, emulated batch behaviour (comparable to the behaviour of previous Jaybird versions) will be used.

    When server-side batch support is not available, Jaybird will fall back to the emulated batch behaviour.

  • serverBatchBufferSize — size in bytes of the server-side batch buffer, default is 0.

    This property supports the following value ranges:

    < 0

    use server-side default (16MB as of Firebird 4.0)
    0

    (default) use server-side maximum (256MB as of Firebird 4.0)
    > 0

    use specified size, capped at server-side maximum

    Too small buffer sizes will use 128KB or the size necessary for two rows (whichever is bigger). Too large buffer sizes will use the server-side maximum (256MB as of Firebird 4.0).

This support comes with a number of limitations:

  • Only supported on the pure Java protocol, not on native or embedded.

  • Only supported on PreparedStatement.

    • The Statement batch behaviour is not supported by server-side batch updates, so Jaybird always emulates batch support for Statement.

    • The CallableStatement implementation is more complex than prepared statement, so the decision was made not to reimplement this using server-side batch updates. Jaybird always emulates batch support for CallableStatement. The implementation might be rewritten in a future Jaybird version, if there is sufficient interest. As a workaround, use execute procedure or {call procedure_name(...)} from a PreparedStatement.

  • Requesting generated-keys will fall back to emulated behaviour as server-side batches do not support returning values produced by the RETURNING clause.

  • Using parameterless statements will fall back to emulated behaviour (since Jaybird 5.0.5) as server-side batches do not support executing parameterless statements.

  • The server-side batch update feature in Firebird 4.0 and higher has additional facilities to send BLOB values as part of the batch update. This is not yet used by Jaybird.

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).

7.12. Firebird 5.0 multi-row RETURNING support

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.

7.13. Firebird 5.0 scrollable cursor support

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):

EMULATED

(default) Use client-side cached result set; this is the same behaviour as previous Jaybird versions used

SERVER

Use server-side scrollable cursors, if possible

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):

  • New rows are inserted at the end of the cursor, where in emulated they are inserted before the current row

  • Deleted rows are visible with an all-null marker row, where in emulated, the deleted row is removed from the result set

  • Result sets now report true for rowUpdated(), rowDeleted() and rowInserted() for rows updated, deleted or inserted through the result set.

    This is not yet reflected in updatesAreDetected(), deletesAreDetected() and insertsAreDetected() of DatabaseMetaData. This will be corrected if and when we retrofit the new behaviour for emulated as well.

See also jdp-2021-04.

7.14. Firebird Embedded locator service provider (experimental)

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.

This is an experimental feature. Its API may change in point releases, or it may be removed or replaced entirely in a future major release.

7.15. Table statistics of a connection (experimental)

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().

This is an experimental feature. Its API may change in point releases, or it may be removed or replaced entirely in a future major release.

7.16. Potentially breaking changes

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

See also Compatibility changes for details.

7.17. Other fixes and changes

  • Fixed: changes to the transaction configuration (transaction parameter buffer configuration) of one connection are no longer propagated to other connections with the same connection properties (#428)

    Backported to Jaybird 3.0.9 and 4.0.1.

  • Changed: build migrated from Ant to Gradle (#461)

  • Changed: removed debug logging in AbstractFbStatement.ensureClosedCursor (#604)

    The solution for not closing the cursor on all code paths — introduced in Jaybird 3.0.6 — is no longer considered a stopgap measure.

  • Improvement: Optimization of ResultSet.next() (#663)

    This change was contributed by Vasiliy Yashkov.

  • Improvement: add setForceWrite/getForceWrite to FBManager to allow disabling force write on database creation (#671)

  • Improvement: Attempts to connect without username and password with the pure Java protocol will now result in error isc_login (“Your user name and password are not defined. Ask your database administrator to set up a Firebird login.”) instead of isc_connect_reject (“connection rejected by remote interface”) (#583)

  • Improvement: Don’t send cursor close to server when closing ResultSet in response to Statement close (#669)

    This provides a small performance increase in cases where a result set was not already closed (e.g. no explicit ResultSet.close() or result set not fully read) before the statement close.

  • New feature: Support for NBackup GUID-based backup and in-place restore (#672)

    The org.firebirdsql.management.NBackupManager interface has two new methods: setBackupGuid(String) expecting the brace-enclosed GUID of a previous backup to use as the starting point for this backup, and setInPlaceRestore(boolean) to enable (or disable) in-place restore. These options require Firebird 4.0 or higher.

    This feature was also backported to Jaybird 4.0.4.

  • New feature: Support for NBackup fixup and preserve sequence (#673)

    The org.firebirdsql.management.NBackupManager interface has two new methods: fixupDatabase() to “fixup” a database (switch back to 'normal' state without merging the delta file), and setPreserveSequence(boolean) to preserve the current database GUID and replication sequence on fixup or restore. These options require Firebird 4.0 or higher.

  • Improvement: The charSet connection property now also has an alias charset (URL property, not as get/set pair).

  • Improvement: The dbCryptConfig connection property now supports base64url (the “URL and Filename safe” Base 64 Alphabet) with the base64url: prefix (#677)

  • Fix: FBStatement allowed retrieval of update count after error, while FBPreparedStatement — correctly — did not (#681)

    Now, after an exception, attempting to retrieve the update count with getUpdateCount() will return -1.

  • Improvement: Renamed NativeResourceUnloadWebListener to NativeResourceUnloadWebListenerJavaX and added its twin NativeResourceUnloadWebListenerJakarta using the jakarta.servlet namespace to support native resource unloading on Jakarta EE 9 and higher (#684)

  • Improvement: Connection.isValid(int) now asynchronously checks validity of connections, allowing the timeout to also be honoured for native connections (#685)

  • New feature: Support for isc_spb_expected_db on service manager (#691)

    With Firebird 3.0 and higher, this is used by Firebird to find the non-default security database to use when authenticating.

    The setDatabase method of a service manager will also set the expectedDb property.

  • Change: Removed finalization from FBConnection and FBStatement (#699)

  • Fix: XAResource checked at most 10 records for forget or recovery operations (#701)

    As part of this change, — for Firebird 3.0 and higher — queries were changed to convert the RDB$TRANSACTION_DESCRIPTION to an octets varchar field (to avoid additional roundtrips for blob fields), and — when applicable, for Firebird 2.5 and higher — only query transactions that have a transaction description written by Jaybird

  • Change: Stop reporting 0 update count with getUpdateCount() for statement types that never produce an update count (#703)

    getUpdateCount() will no longer report an update count of 0 for statements that never have a non-zero update count (e.g. select, execute procedure, DDL, management statements). Now, it will immediately report -1 (which it previously only did after another call to getMoreResults()).

    The executeUpdate and executeLargeUpdate methods will continue to report an update count of 0, as required by the JDBC API documentation. For consistency with server-side batch execution, emulated batch execution will also report update counts of 0 where getUpdateCount() would report -1.

  • New feature: Support for role name on FBManager (#705)

  • New feature: Support for NBackup “clean history” option (#706)

    The org.firebirdsql.management.NBackupManager interface has three new methods: setCleanHistory(boolean) to enable (or disable) cleaning of history during backup, and setKeepDays(int) and setKeepRows(int) to specify the number of days or rows to keep history. These options require Firebird 4.0.3 or higher.

    This feature was also backported to Jaybird 4.0.7.

  • Improvement: Allow statements longer than 64KB with native and embedded connections (#713)

    This requires Firebird 3.0 or higher server and a Firebird 3.0 or higher fbclient. Long statement texts were already supported for pure Java connections.

  • Fixed: DatabaseMetaData.getIdentifierQuoteString() should return " " (space) for connection dialect 1 (#714)

  • Improvement: A column JB_GRANTEE_TYPE was added to getColumnPrivileges and getTablePrivileges in DatabaseMetaData. It returns the object type of the grantee (e.g. USER, ROLE). This is a Jaybird specific extension, we recommend retrieving it by name only.

  • Improvement: Populate COLUMN_DEF of DatabaseMetaData.getProcedureColumns with the default of the parameter (#715)

  • Change: Jaybird no longer registers a SQLWarning nor logs a warning when connecting without an explicit connection character set (#717)

7.18. Removal of deprecated classes and packages

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

8. Compatibility changes

Jaybird 5 introduces some changes in compatibility and announces future breaking changes.

The list might not be complete, if you notice a difference in behavior that is not listed, please report it as bug. It might have been a change we forgot to document, but it could just as well be an implementation bug.

8.1. Support for Java 7 dropped

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

8.2. Removal of Java EE/Jakarta EE Connector Architecture (JCA)

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.

8.3. Changes to connection properties

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:

  1. Jaybird specific connection properties no longer have an alias of the form isc_dpb_<name>. Only shorter aliases (camel-case and underscored) are still supported. For example isc_dpb_use_stream_blobs no longer exists, but use_stream_blobs and useStreamBlobs do.

    This does not apply to connection properties defined by Firebird itself, which still support the isc_dpb_ prefix.

  2. The Jaybird specific connection properties no longer have a constant isc_dpb_<name> in org.firebirdsql.gds.ISCConstants.

  3. Previously a FBSQLException was thrown if multiple aliases of the same property where used through DriverManager. This is now silently allowed, and the last property 'wins', however the ordering of properties is not deterministic.

    The behaviour of FBDriver.normalizeProperties no longer matches with the behaviour of connecting through DriverManager as normalizeProperties still throws the exception.

  4. FBDriver.normalizeProperties normalizes to a different property name than previous versions, the shorter camel-case name, instead of the longer, underscored isc_dpb_ alias. For example, charSet instead of isc_dpb_local_encoding.

8.3.1. Changes to setNonStandardString(String)

The FirebirdConnectionProperties.setNonStandardString(String) (implemented by a number of data sources) is documented as accepting strings with the format propertyName[=propertyValue]. However, the actual implementation was far more lenient, allowing odd values like " =:propertyName :==: propertyValue" and "propertyName propertyValue".

This has been rectified, and now we split on the first ‘=’, everything before the ‘=’ — or the entire string if there is no ‘=’ — is the property name, and everything after — or an empty string if there is no ‘=’ — is the property value. Leading and trailing whitespace is trimmed from the property name and value.

This has the effect that previously valid options will now configure a different property or — for a limited number of cases — throw an IllegalArgumentException. Some examples:

  • "a:=b" used to set name "a" with value "b", but now sets name "a:" with value "b".

  • "a b" used to do the same, but now sets name "a b" with value empty string.

  • "=a=b" used to set the same, but now throws an `IllegalArgumentException.

These cases need to be replaced with "a=b".

8.4. Generated keys support always available

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.

8.5. Batch execution error “Internal buffer overflow - batch too big”

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:

  1. Reduce the size of the batch, by executing when the batch has accumulated a few hundred to a few thousand rows.

  2. Disable server-side batch updates by setting connection property useServerBatch to false.

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.

8.6. Changes affecting metadata compatibility

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.

8.7. Removal of classes, packages and methods without deprecation

8.7.1. Removal of packages without deprecation

The following packages have been removed in Jaybird 5 without deprecation:

8.7.2. Removal of methods without deprecation

The following methods have been removed in Jaybird 5 without deprecation:

  • FirebirdConnectionProperties.getDatabaseParameterBuffer(); there is no direct replacement, though BaseProperties.connectionPropertyValues() can be considered its successor.

  • FBConnection.getDatabaseParameterBuffer(); there is no direct replacement, though FBConnection.connectionProperties() can be considered its successor.

  • FBStatement

    • toArray(Collection<Long> updateCounts) — use org.firebirdsql.util.Primitives.toIntArray(List<? extends Number>) (note: this is considered internal API)

    • toLargeArray(Collection<Long> updateCounts) — use org.firebirdsql.util.Primitives.toLongArray(List<? extends Number>) (note: this is considered internal API)

    • forgetResultSet(); there is no replacement

    • isExecuteProcedureStatement(String sql); there is no replacement

  • FBPreparedStatement

    • setStringForced(int, String); there is no replacement with the same behaviour, use setString(int, String)

  • FBRowUpdater, parameter Synchronizable syncProvider was removed from its constructor

  • GDSHelper

    • getDatabaseParameterBuffer(), the significant refactoring of Jaybird’s internals resulted in this method no longer making any sense. There is no direct replacement, though GDSHelper.getConnectionProperties() can be considered its successor.

    • openBlob(long, boolean), use openBlob(long, BlobConfig)

    • createBlob(boolean), use createBlob(BlobConfig)

    • getJavaEncoding(); there is no replacement

    • getBlobBufferLength(), use getConnectionProperties().getBlobBufferSize()

  • WireCrypt getWireCrypt() in ServiceManager, EventManager and IAttachProperties; replacement is WireCrypt getWireCryptAsEnum() or String getWireCrypt().

  • setWireCrypt(WireCrypt) in ServiceManager, EventManager and IAttachProperties; replacement is setWireCryptAsEnum(WireCrypt) or setWireCrypt(String).

  • getServerName(), getPortNumber() and getAttachObjectName() in org.firebirdsql.gds.ng.AbstractConnection; handling of database coordinates is now considered internal to the protocol implementation. There is no direct equivalent beyond accessing the properties with the same name in the attachment properties (though keep in mind that the meaning of those properties has changed in Jaybird 5, see also jdp-2021-01).

  • constructor FBCachedClob(FBCachedBlob, String), use FBCachedClob(FBCachedBlob, FBBlob.Config)

  • constructor FBProcedureParam(), use FBProcedureParam(int, String)

The following methods had their visibility reduced:

  • FBTpbMapper.getDefaultTransactionIsolation() to default access.

  • FBTpbMapper.setDefaultTransactionIsolation(int) to default access.

  • FBProcedureParam

    • isParam() made final

    • getPosition() made final

    • getParamValue() made final

8.7.3. Removal of classes without deprecation

The following classes have been removed in Jaybird 5 without deprecation:

  • ParameterBufferHelper

  • ParameterBufferHelper.DpbParameterType

  • ParameterBufferHelper.DpbValueType

  • DatabaseParameterBufferExtension

  • Base64Decoder and Base64DecoderImpl, these classes were internal API, but not marked as such.

  • JdbcVersionSupport and implementations, JdbcVersionSupportHolder. These were implementation artifacts to support multiple JDBC versions.

  • AbstractPreparedStatement, AbstractCallableStatement and AbstractResultSet. These were implementation artifacts to support multiple JDBC versions.

  • Synchronizable, it is no longer possible to synchronize on the lock object of JDBC classes. Thread safety and locking is now an internal implementation detail.

    For maintainers of derived drivers, usage of synchronized (getSynchronizationObject()) { .. } need to be replaced with try (LockCloseable ignored = withLock()) { .. }.

The following classes are no longer accessible in Jaybird 5:

  • FBUpdatableCursorFetcher is now package private.

  • FBRowUpdater is now package private and final.

The following classes can no longer be subclassed in Jaybird 5:

  • FBRowUpdater is now final

  • DefaultEncodingSet is now final. In practice, this class was already defined in a way that it couldn’t be subclassed in a useful way, but it was documented that it could because of an earlier design iteration.

  • FBBlob is now final

  • FBClob is now final

  • FBCachedClob is now final

  • FBConnectionProperties is now final

  • FBRowId is now final

  • FBSavePoint is now final

  • FBTpbMapper is now final

  • ExecutionPlanProcessor is now final

  • BlobLengthProcessor is now final

  • FBEscapedFunctionHelper is now final and can no longer be instantiated

  • FBEscapedCallParser is now final, and some previously protected methods have been made package private or removed entirely.

8.7.4. Removal of constants without deprecation

The following constants have been removed in Jaybird 5 without deprecation:

  • TIME_WITH_TIMEZONE and TIMESTAMP_WITH_TIMEZONE from org.firebirdsql.jdbc.JaybirdTypeCodes. Use the constants with the same name from java.sql.Types.

  • ISCConstants

    • isc_dpb_* of Jaybird-specific connection properties, Firebird-specific connection properties have been deprecated for removal in Jaybird 6.

    • jaybirdMinIscDpbValue

    • jaybirdMaxIscDpbValue

  • IAttachProperties.DEFAULT_PORT

  • IAttachProperties.DEFAULT_SERVER_NAME

  • FBBlob.SEGMENTED

8.8. Removal of deprecated classes, packages and methods

8.8.1. Removal of deprecated packages

The following packages have been removed in Jaybird 5:

8.8.2. Removal of deprecated methods

The following methods have been removed in Jaybird 5:

  • MaintenanceManager.listLimboTransactions(), use MaintenanceManager.limboTransactionsAsList() or MaintenanceManager.getLimboTransactions() instead.

  • TraceManager.loadConfigurationFromFile(String), use standard Java functionality like new String(Files.readAllBytes(Paths.get(fileName)), <charset>)

  • FBDatabaseMetaData.hasNoWildcards(String pattern)

  • FBDatabaseMetaData.stripEscape(String pattern)

  • FbStatement.getFieldDescriptor(), use FbStatement.getRowDescriptor()

  • AbstractFbStatement.setFieldDescriptor(RowDescriptor fieldDescriptor), use AbstractFbStatement.setRowDescriptor(RowDescriptor rowDescriptor)

  • FBField.isType(FieldDescriptor, int), use JdbcTypeConverter.isJdbcType(FieldDescriptor, int)

  • EncodingFactory

    • getCharacterSetSize(int), use getEncodingDefinitionByCharacterSetId(int) and then getMaxBytesPerChar()

    • getEncoding(String), use getEncodingForCharsetAlias(String, Encoding)

    • getEncoding(Charset), use getEncodingForCharset(Charset, Encoding) or getOrCreateEncodingForCharset(Charset)

    • getIscEncoding(String), use getEncodingDefinitionByCharsetAlias(String) and then getFirebirdEncodingName()

    • getIscEncoding(Charset), use getEncodingDefinitionByCharset(Charset) and then getFirebirdEncodingName()

    • getIscEncodingSize(String), use getEncodingDefinitionByFirebirdName(String) and then getMaxBytesPerChar()

    • getJavaEncoding(String), use getEncodingDefinitionByFirebirdName(String) and then getJavaEncodingName()

    • getJavaEncodingForAlias(String), use getEncodingDefinitionByCharsetAlias(String) and then getJavaEncodingName()

8.8.3. Removal of deprecated classes

The following classes have been removed in Jaybird 5:

  • FBMissingParameterException, exception is no longer used.

8.8.4. Removal of deprecated constants

The following constants have been removed in Jaybird 5:

  • All SQL_STATE_* constants in FBSQLParseException. Use equivalent constants in org.firebirdsql.jdbc.SQLStateConstants.

8.9. Removal of UDF support for JDBC escapes

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:

  • Connection property useStandarUdf[sic] and its alias use_standard_udf

  • isUseStandardUdf() and setUseStandardUdf(boolean useStandardUdf) in FirebirdConnectionProperties and in implementations of DataSource and other classes

  • Constants

    • FBConnectionProperties.USE_STANDARD_UDF_PROPERTY

    • DatabaseParameterBufferExtension.USE_STANDARD_UDF

    • ISCConstants.isc_dpb_use_standard_udf

  • Enum EscapeParserMode and its usages in FBEscapedCallParser and FBEscapedParser

  • Public classes in package org.firebirdsql.jdbc.escape are now marked as internal API

8.10. Breaking changes internal API

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.

  • constructor AbstractStatement(Object syncObject) was replaced with a no-arg constructor.

  • ProtocolDescriptor.createWireOperations(WireConnection<?, ?> connection, WarningMessageCallback defaultWarningMessageCallback, Object syncObject) was replaced with ProtocolDescriptor.createWireOperations(WireConnection<?, ?> connection, WarningMessageCallback defaultWarningMessageCallback)

  • The third parameter, Object syncObject, of constructor AbstractWireOperations (and its subclasses) was removed

  • Method getSynchronizationObject() was removed from various interface, replace use of synchronized blocks with try (LockCloseable ignored = withLock()) { .. }

    • FbAttachment

    • FbBlob

    • AbstractFbStatement

    • AbstractFbTransaction

    • AbstractWireOperations

  • Class SyncObject has been removed

  • IConnectionProperties.getExtraDatabaseParameters; there is no direct replacement, though BaseProperties.connectionPropertyValues() can be considered its successor for read-only access.

  • FbConnectionProperties.fromDpb(DatabaseParameterBuffer); there is no replacement.

  • AbstractParameterConverter.populateNonStandardProperties; there is no direct replacement. The new way of adding non-standard properties is setting the appropriate properties by name (e.g. using BaseProperty.setProperty(String, String)) before ParameterConverter.toDatabaseParameterBuffer is called.

  • FBConnectionRequestInfo.deepCopy() (internal API); if a replacement is needed, use new FBConnectionRequestInfo(instance.asIConnectionProperties().asNewMutable()).

  • DatatypeCoder

    • encodeTimestamp(Timestamp, Calendar) — use encodeTimestamp(Timestamp, Calendar, boolean)

    • encodeTimestamp(Timestamp) — use encodeTimestampCalendar(Timestamp, Calendar)

    • decodeTimestamp(Timestamp, Calendar) — use decodeTimestamp(Timestamp, Calendar, boolean)

    • decodeTimestamp(byte[]) — use decodeTimestampCalendar(byte[], Calendar)

    • encodeTime(Time) — use encodeTimeCalendar(Time, Calendar)

    • decodeTime(byte[]) — use decodeTimeCalendar(byte[], Calendar)

    • encodeDate(Date) — use encodeDateCalendar(Date, Calendar)

    • decodeDate(byte[]) — use decodeDateCalendar(byte[], Calendar)

    • encodeLocalTime(int, int, int, int) — use encodeLocalTime(LocalTime)

    • encodeLocalDate(int, int, int) — use encodeLocalDate(LocalDate)

    • encodeLocalDateTime(int, int, int, int, int, int, int) — use encodeLocalDateTime(LocalDateTime)

  • V10Statement

    • sendInfoSql(byte[], int) — use getInfo(int, byte[], int) (which sends and receives)

    • processInfoSqlResponse(GenericResponse) — use GenericResponse.getData()

    • writeSqlData(RowDescriptor, RowValue) — use writeSqlData(RowDescriptor, RowValue, boolean), with the third parameter true for the equivalent behaviour

  • StatementListener.allRowsFetched(FbStatement) — use afterLast(FbStatement)

  • AbstractFbStatement

    • setAllRowsFetched(boolean) — use setAfterLast()

    • isAllRowsFetched() — isAfterLast()

  • FbWireOperations.readSingleResponse — use FbWireOperations.readResponse

    Contrary to readSingleResponse, readResponse throws the SQLException reported in a GenericResponse

  • FBWorkaroundStringField.setTrimString — use StringTrimmable.setTrimTrailing (implemented by FBStringField and subclasses). The replacement only trims trailing spaces.

  • FBDatabaseMetaData

    • getWantsSystemTables(String[]) — there is no replacement

    • getWantsTables(String[]) — there is no replacement

    • getWantsViews(String[]) — there is no replacement

  • RowValueBuilder was moved to another package and will be made package private in Jaybird 6

  • FBBlob.getGdsHelper() has been removed

  • constructor BlobLengthProcessor(FbBlob) was replaced by a no-arg constructor

8.10.1. Additional statement state PREPARING

To be able to detect preparing a new statement text on a statement handle, the state PREPARING has been added to org.firebirdsql.gds.ng.StatementState. The state transition ALLOCATED → PREPARED is no longer valid, and must now be ALLOCATED → PREPARING → PREPARED.

Custom statement implementations need to add a state transition to PREPARING before preparing a new statement text.

8.11. Unlikely breaking changes

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

  • The trim behaviour of metadata queries (e.g. for DatabaseMetaData) was changed. Previously it used stringValue.trim() only through ResultSet.getString(..). This was changed to use a custom trim to trim only trailing spaces, but only for (non-OCTETS) CHAR, VARCHAR, BLOB SUB_TYPE TEXT. This trim is now applied for code paths calling getString() on the underlying field.

    This change can have two potentially breaking effects:

    1. Values from metadata queries can now have leading spaces, where previously those were removed

    2. Some — but not all — metadata ResultSets would previously return the untrimmed value through getObject(..), but now return the trimmed value.

  • CallableStatement.getString — in Jaybird 3, 4.0.0 - 4.0.8, and 5.0.0 — and CallableStatement.getObject — in Jaybird 5.0.0 — would incorrectly trim string values.

  • Setting a string on a PreparedStatement, or updatable ResultSet, had a weird boundary check that tried to exploit a benign buffer overflow if the value started and/or ended with “%”, and was one or two bytes too long. This odd boundary check has been removed, and will now throw a DataTruncation if the byte length is longer than the declared length (in bytes) of the field. Previously, in Jaybird 3.0 and 4.0, this had the following effects:

    • For pure Java, this would throw a “string truncation error” on execute

    • For native/embedded, it would be silently accepted with truncation of the value (one byte too long), or throw an IndexOutOfBoundsException (two bytes too long)

8.12. Breaking changes for Jaybird 6

With Jaybird 6 the following breaking changes will be introduced.

8.12.1. Dropping support for Firebird 2.5

Jaybird 6 will drop support for Firebird 2.5 (see also jdp-2021-03: Drop Firebird 2.5 support). In general, we expect the driver to remain functional, but chances are certain metadata — e.g. DatabaseMetaData — will break if we use features introduced in newer versions.

Wire protocol versions for Firebird 2.5 and earlier will be disabled by default to disallow connection for the pure Java protocol. An option is available to re-enable unsupported wire protocol versions.

8.12.2. Dropping support for Java 8 and 11

Jaybird 6 will drop support for Java 8 and 11, making Java 17 the baseline version (see also jdp-2022-03: Java 17 minimum version).

Jaybird 5 will serve as a form of “long-term support” for Java 8 and 11, with maintenance releases at least until the release of Jaybird 7.

8.12.3. Dropping support for OOREMOTE (OpenOffice/LibreOffice driver)

The OOREMOTE protocol (JDBC URL prefix jdbc:firebird:oo and jdbc:firebirdsql:oo) has been deprecated in Jaybird 5 and will be removed in Jaybird 6.

See also jdp-2022-04: Deprecate OOREMOTE (OpenOffice/LibreOffice driver) for removal.

The recommended replacement is to use LibreOffice and the builtin “Firebird External” connection option in LibreOffice Base, instead of the “JDBC” option with Jaybird on the classpath of LibreOffice.

8.12.4. Removal of deprecated classes, packages and methods

Removal of deprecated methods

The following methods will be removed in Jaybird 6:

  • FirebirdConnectionProperties
    Changes to the FirebirdConnectionProperties interface affect the data source implementations in org.firebirdsql.ds, and FBManagedConnectionFactory.

    • getDatabase() and all its implementations, use DatabaseConnectionProperties.getDatabaseName()

    • setDatabase(String) and all its implementations, use DatabaseConnectionProperties.setDatabaseName(String)

    • getNonStandardProperty(String) and all its implementations, use BaseProperties.getProperty(String)

    • setNonStandardProperty(String,String) and all its implementations, use BaseProperties.setProperty(String,String)

    • getBuffersNumber and all its implementations, use DatabaseConnectionProperties.getPageCacheSize

    • setBuffersNumber and all its implementations, use DatabaseConnectionProperties.setPageCacheSize

  • IConnectionProperties

    • short getConnectionDialect() and all its implementations, use int DatabaseConnectionProperties.getSqlDialect()

    • setConnectionDialect(short), and all its implementations, use DatabaseConnectionProperties.setSqlDialect(int)

  • FBSimpleDataSource.get/setBlobBufferLength, use get/setBlobBufferSize

  • EventManager

    • get/setHost, use get/setServerName

    • get/setPort, use get/setPortNumber

    • get/setDatabase, use get/setDatabaseName

  • GDSFactory.getJdbcUrl(GDSType, String), use GDSFactory.getJdbcUrl(GDSType, DatabaseConnectionProperties)

  • FBManagedConnection.getDatabase(), there is no direct replacement, but the information can be obtained from the connection properties

  • GDSHelper.getIscEncoding(); there is no replacement

  • FirebirdConnection.getIscEncoding; there is no replacement

Removal of deprecated classes

The following classes have been deprecated and will be removed in Jaybird 6:

  • org.firebirdsql.gds.ng.listeners.DefaultDatabaseListener — implementing DatabaseListener is now sufficient as all methods in the interface now have a default implementation that does nothing

  • org.firebirdsql.gds.ng.listeners.DefaultStatementListener — implementing StatementListener is now sufficient as all methods in the interface now have a default implementation that does nothing

  • org.firebirdsql.jdbc.FBConnectionDefaults, its replacement, org.firebirdsql.jaybird.props.PropertyConstants, is considered internal API

  • org.firebirdsql.gds.ng.DatatypeCoder.RawDateTimeStruct (semi-internal API) — use one of the java.time classes instead

8.12.5. Removal of deprecated constants

The following constants have been deprecated and will be removed in Jaybird 6:

  • All public String constants in FBDriver. The replacement for most constants can be found in org.firebirdsql.jaybird.props.PropertyNames, though some will be removed without replacement.

  • ISCConstants.isc_dpb_* that are DPB items, the replacement is the constant with the same name in org.firebirdsql.jaybird.fb.constants.DpbItems.

  • ISCConstants.isc_tpb_* that are TPB items, the replacement is the constant with the same name in org.firebirdsql.jaybird.fb.constants.TpbItems.

  • ISCConstants.isc_spb_* that are SPB items, the replacement is the constant with the same name in org.firebirdsql.jaybird.fb.constants.SpbItems.

  • ISCConstants.isc_bpb_* that are BPB items, the replacement is the constant with the same name in org.firebirdsql.jaybird.fb.constants.BpbItems.

  • ISCConstants.isc_bpb_type_segmented and ISCConstants.isc_bpb_type_stream, the replacement is the constant with the same name in org.firebirdsql.jaybird.fb.constants.BpbItems.TypeValues

  • All constants in DatabaseParameterBuffer, use the equivalent constant from org.firebirdsql.jaybird.fb.constants.DpbItems.

  • All constants in TransactionParameterBuffer, use the equivalent constant from org.firebirdsql.jaybird.fb.constants.TpbItems.

  • All constants in ServiceParameterBuffer, use the equivalent constant from org.firebirdsql.jaybird.fb.constants.SpbItems.

  • All constants in BlobParameterBuffer, use the equivalent constant from org.firebirdsql.jaybird.fb.constants.BpbItems and org.firebirdsql.jaybird.fb.constants.BpbItems.TypeValues

  • All TPB_* constants in FirebirdConnection, use the equivalent constant from org.firebirdsql.jaybird.fb.constants.TpbItems.

  • All public String constants in org.firebirdsql.jdbc.FBConnectionProperties. The replacement for most constants can be found in org.firebirdsql.jaybird.props.PropertyNames, though some will be removed without replacement.

  • GDSHelper.DEFAULT_BLOB_BUFFER_SIZE, its replacement, org.firebirdsql.jaybird.props.PropertyConstants.DEFAULT_BLOB_BUFFER_SIZE, is considered internal API

  • All constants in IConnectionProperties, use the equivalent constant from org.firebirdsql.jaybird.props.PropertyConstants, though this class is considered internal API

9. Compatibility notes

9.1. Type 2 (native) and embedded driver

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.15.0.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):

<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna</artifactId>
    <version>5.15.0</artifactId>
</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.

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>fbclient</artifactId>
    <version>5.0.1.1</artifactId>
</dependency>

For more information about this library, see https://github.com/mrotteveel/jaybird-fbclient.

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.