Skip to content

release_notes.adoc

Latest commit

 

History

History
1016 lines (772 loc) · 49.4 KB

release_notes.adoc

File metadata and controls

1016 lines (772 loc) · 49.4 KB

Jaybird {version_wo_target} Release Notes

Table of Contents

1. Jaybird 7.0.x changelog

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

…​

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

  • In Java 24 and higher, the mapping of some named WITH TIME ZONE values changed as Java’s mapping of short IDs changed. This should only affect cases where you explicitly obtain ZonedDateTime or ZonedTime instances with these named zones.

    • EST (ID 65136) → America/Panama; maps to -05:00 in older Java versions

    • HST (ID 65027) → Pacific/Honolulu; maps to -10:00 in older Java versions

    • MST (ID 65002) → America/Phoenix; maps to -07:00 in older Java versions

    This is informational only, and not something that we can fix or change in a later Jaybird release.

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

3.1. About this version

The major changes and new features in Jaybird 7 are:

  • …​

Upgrading from Jaybird 6 should be straightforward, but please make sure to read Compatibility changes before using Jaybird 7. See also Upgrading from Jaybird 6 to Jaybird 7.

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.

3.2. Supported Firebird versions

Jaybird {version_wo_target} was tested against Firebird 3.0.12, Firebird 4.0.5, Firebird 5.0.1 and a recent snapshot of Firebird 6.0, but should also support other Firebird versions from 3.0 and up. Firebird 2.5 and older are not supported.

Firebird 6.0 is currently also not considered supported (see also Firebird support in What’s new in Jaybird 7).

Jaybird 7 will — by default — not connect to Firebird 2.5 or older.

This driver does not support InterBase.

3.3. Supported Java versions

Jaybird 7 supports Java 17 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 17, the most recent LTS version after Java 17, and the latest Java release. Currently, that means we support Java 17, Java 21, and Java 23.

Note

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 7 provides libraries compiled for Java 17.

Jaybird 7 is modularized. The available modules are:

org.firebirdsql.jaybird

main Jaybird driver (jaybird-{version_example}.jar)

org.firebirdsql.jaybird.chacha64

ChaCha64 wire encryption implementation (chacha64-plugin-{version_example}.jar)

org.firebirdsql.jna

native and embedded protocol implementation using JNA (jaybird-native-{version_example}.jar)

3.4. Specification support

Jaybird supports the following specifications:

Specification Notes

JDBC 4.5

All JDBC 4.5 methods for features supported by Firebird.

JDBC 4.4

If a security manager is available, the driver still performs SQLPermission checks.

JDBC 4.3

All JDBC 4.3 methods for features supported by Firebird.

JTA 1.0.1

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

4. Support

If you need support with Jaybird, join the Firebird-Java Google Group and mailing list. You can subscribe by sending an email to firebird-java+subscribe@googlegroups.com.

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

For a more complete list, see the next section.

4.1. Where to get help

4.2. Contributing

There are several ways you can contribute to Jaybird or Firebird in general:

4.3. Reporting bugs

The developers follow the firebird-java Google Group. Join the list and post information about suspected bugs. List members may be able to help out to determine if it is an actual bug, provide a workaround and get you going again, whereas bug fixes might take a while.

You can also report bugs in the Jaybird bug tracker, https://github.com/FirebirdSQL/jaybird/issues.

When reporting bugs, please provide a minimal, but complete reproduction, including databases and sourcecode to reproduce the problem. Patches to fix bugs are also appreciated. Make sure the patch is against a recent master version of the code. You can also fork the jaybird repository and create pull requests.

5. Getting Jaybird 7

5.1. Jaybird {version_wo_target}

5.1.1. Maven

Jaybird {version_wo_target} is available on Maven Central.

groupId

org.firebirdsql.jdbc
artifactId

jaybird
version

{version_example}

For example:

Main Jaybird artifact
<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird</artifactId>
    <version>{version_example}</version>
</dependency>

If you want to use Type 2 support (native or embedded), you need to explicitly add jaybird-native as a dependency:

Jaybird native artifact (native and embedded protocol)
<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird-native</artifactId>
    <version>{version_example}</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.

To enable the “ChaCha64” wire encryption support for pure Java connections, also add:

ChaCha64 wire encryption plugin
<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>chacha64-plugin</artifactId>
    <version>{version_example}</version>
</dependency>

5.1.2. Gradle

See also Maven.

Examples:

Main Jaybird artifact
implementation 'org.firebirdsql.jdbc:jaybird:{version_example}'
Jaybird native artifact (native and embedded protocol)
implementation 'org.firebirdsql.jdbc:jaybird-native:{version_example}'
ChaCha64 wire encryption plugin
implementation 'org.firebirdsql.jdbc:chacha64-plugin:{version_example}'

5.1.3. Download

You can download the release of Jaybird from https://firebirdsql.org/en/jdbc-driver/

At minimum, Jaybird 7 requires jaybird-{version_example}.jar.

For native or embedded support, also add jaybird-native-{version_example}.jar and jna-jpms-5.18.1.jar () on your classpath or modulepath. See also Type 2 (native) and embedded driver.

For “ChaCha64” wire-encryption support with pure Java connections, also add chacha64-plugin-{version_example}.jar, and bcprov-jdk18on-1.83.jar from the lib directory of the distribution zip.

6. Upgrading from Jaybird 6 to Jaybird 7

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

6.1. Maven

Change the version of the dependency to {version_example}.

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

If you use native or embedded, you need to explicitly add jaybird-native as a dependency:

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird-native</artifactId>
    <version>{version_example}</version>
</dependency>

If you use native or embedded, make sure to update your JNA dependency to version 5.18.1 and artifact id jna-jpms, or remove it altogether as the dependencies will now be pulled in through the jaybird-native artifact.

<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna-jpms</artifactId>
    <version>5.18.1</version>
</dependency>
Warning

Jaybird 5 and older used artifactId jna instead of jna-jpms. Although both artifacts are nearly identical, the jna-jpms artifact provides a module-info.class, while the jna artifact does not. If you want to use Jaybird as a module, and use jaybird-native, make sure to use the jna-jpms artifact.

6.2. Manual install

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

  1. Replace the Jaybird 6 library with the Jaybird 7 version

    • jaybird-6.0.x.<java>.jar with jaybird-{version_example}.jar

  2. If you use the NATIVE or EMBEDDED protocols, replace the following JARs to the classpath or modulepath

    • jaybird-native-6.0.x.<java>.jar with jaybird-native-{version_example}.jar

    • older jna or jna-jpms versions with jna-jpms-5.18.1.jar from the lib directory of the distribution zip

  3. To enable “ChaCha64” wire encryption support replace the following JARs to the classpath or modulepath

    • chacha64-plugin-6.0.x.<java>.jar with chacha64-plugin-{version_example}.jar

    • older bcprov-jdk18on with bcprov-jdk18on-1.83.jar from the lib directory of the distribution zip

6.3. Gotcha’s

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

For known issues, consult Known issues.

7. What’s new in Jaybird 7

For a full list of changes, see milestone “v7-initial”.

7.1. Java support

Note

At this point in the Jaybird 7 development, information about supported Java versions is tentative.

We may decide to change the minimum supported Java version before the final release of Jaybird 7.

Jaybird 7 supports Java 17 and higher (JDBC 4.3). Most of the JDBC 4.3 features have been implemented (in as far as they are supported by Firebird).

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

7.2. Firebird support

Note

At this point in the Jaybird 7 development, information about supported Firebird versions is tentative.

We may decide to change the minimum supported Firebird version before the final release of Jaybird 7.

Jaybird 7 supports Firebird 3.0, Firebird 4.0, and Firebird 5.0.

Warning
No promises on Firebird 6.0 support

Firebird 6.0 is still in its early stages of development, and is expected to include changes — like schema support — that may impact Jaybird.

As a result — at this time — we make no promises on the support for Firebird 6.0 by Jaybird 7.

Jaybird 7 will — by default — not connect to unsupported versions (that is, Firebird 2.5 or older) using the pure Java protocol.

7.3. REUSE SPDX copyright information

Jaybird now includes copyright information complying with the REUSE 3.3 specification. This can be used to generate an SBOM (Software Bill Of Materials) of the Jaybird sources. The project itself will not provide an SBOM, but people interested in that information can generate it themselves using the reuse tool.

The copyright headers in all source files were replaced with SPDX (System Package Data Exchange) information, with actual licenses consolidated in the LICENSES folder of the repository. We have tried to record copyright of all contributors to files, but due to file renames, moves, and other refactoring, and resulting discontinuities in the history, or contributions committed by someone else, we may have missed some. If you find any errors in the recorded copyright information, let us know.

Files that were historically intended to be dual-licensed under LGPL and BSD, but only had a BSD license header, are now explicitly licensed as LGPL and BSD.

As part of this change, project documentation — Release Notes, FAQ, developer documentation, and the Jaybird Design Proposals — are now licensed under the Public Documentation License. These were previously not explicitly licensed.

7.4. Blob performance improvements

7.4.1. Deferred blob open

In the pure Java implementation, performance of reading and writing blobs was improved by deferring the server-side opening or creating of a blob until an actual server-side operation (putting or getting a segment, or getting blob info). The open or create blob request is pipelined with the subsequent operation, avoiding a round trip to the server. This is especially noticeable in connections with high latency.

Artificial testing on local WiFi with small blobs shows around 85% increase in throughput (comparing a 6.0.1-SNAPSHOT against 6.0.0).

The Inline blob support for Firebird 5.0.3 and higher replaces this improvement for smallish blobs, but it still has benefit for blobs larger than maxInlineBlobSize or blobs that are discarded when the inline blob cache is full.

This optimization is available for Firebird 2.1 and higher, but formally only supported for Firebird 3.0 and higher.

This optimization was backported to Jaybird 5.0.7 and Jaybird 6.0.1.

For native connections, a similar optimization — but only for reading blobs — is available when using a Firebird 5.0.2 or higher fbclient, independent of the Jaybird version.

7.4.2. Requesting known info items on open

In the pure Java implementation, when an input blob is opened, all known blob information items are requested. Subsequent blob information requests on the same FbBlob handle are fulfilled using the cached information. If the request contains information items not in the cache, the request is sent to the server.

For access through JDBC, this optimization has little to no effect, as one of the few times Jaybird itself requests blob information is immediately after opening the blob, which is optimized by the deferred blob open. Direct use of FirebirdBlob.BlobInputStream.length() or the GDS-ng internal API may benefit from this change. We’re also investigating further changes to the implementation of Jaybird that could benefit from this.

This optimization is available for Firebird 2.1 and higher, but formally only supported for Firebird 3.0 and higher.

This optimization was backported to Jaybird 5.0.7 and Jaybird 6.0.1.

For native connections, a similar optimization is available when using a Firebird 5.0.2 or higher fbclient, independent of the Jaybird version.

7.4.3. Inline blob support

Introduced in Firebird 5.0.3 (protocol 19), inline blobs offer a significant performance improvement for querying smallish blobs. As the name suggests, blobs are sent inline together with the row data, avoiding additional round trips to the server for reading the blob data and blob information.

There are two connection properties affecting inline blobs:

maxInlineBlobSize (aliases: max_inline_blob_size, isc_dpb_max_inline_blob_size)

Maximum size in bytes of the blob (default: 65535).
A value of 0 will disable sending of inline blobs.

The maximum value is decided by the Firebird server, and is currently 65535; this may change in the future

If a blob is smaller than the specified size, the server will send it inline. The size includes segment lengths, so the actual maximum blob data received is N * 2 bytes smaller, where N is the number of segments of the actual blob.

The default can be changed with system property org.firebirdsql.jdbc.defaultMaxInlineBlobSize.

maxBlobCacheSize (aliases: max_blob_cache_size, isc_dpb_max_blob_cache_size)

Maximum size in bytes — per connection — of the blob cache (default: 10485760 or 10 MiB).
A value of 0 will disable the cache, but does not disable sending of inline blobs. Set maxInlineBlobSize to 0 to disable sending of inline blobs.

For pure Java, only the data size is counted towards the cache size. For native, the segment lengths also count towards the cache size.

The default can be changed with system property org.firebirdsql.jdbc.defaultMaxBlobCacheSize.

This feature works with pure Java and native connections when connecting to Firebird 5.0.3 or higher. For native connections, a Firebird 5.0.3 or higher client library must be used.

If the maximum blob cache size is reached, received inline blobs will be discarded. For pure Java connections, an inline blob is removed from the cache on first use, or when the transaction associated with the blob ends. The native client implementation may have different cache eviction rules.

As pure Java connections remove the inline blob from the cache on first use, subsequent attempts to read the same blob — by getting a different instance of java.sql.Blob or through multiple calls to the ResultSet.getXXX methods — will use a server-side blob. This can also happen if multiple columns or rows, even in different result sets on the same connection, point to the same blob id in the same transaction.

If you execute queries returning blobs, while those blobs are never actually opened, you may fill up the cache and later received inline blobs are then discarded. Especially in long-running transactions, this may reduce the effectiveness of this feature.

Artificial testing on local WiFi with small blobs (200 bytes) shows a 30,000-45,000% (yes, thousand)[1] increase in throughput comparing a 6.0.2-SNAPSHOT against 6.0.0, and a 15,000-25,000% increase in throughput comparing a 6.0.2-SNAPSHOT against 6.0.1.

This optimization was backported to Jaybird 5.0.8 and Jaybird 6.0.2.

7.5. Schema support

Firebird 6.0 introduces schemas, and Jaybird 7 provides support for schemas as defined in the JDBC specification.

Changes include:

  • Connection property searchPath sets the initial search path of the connection.

    The search path is the list of schemas that will be searched for schema-bound objects if they are not explicitly qualified with a schema name. The first valid schema is the current schema of the connection.

    The value of searchPath is a comma-separated list of schema names. Schema names that are case-sensitive or otherwise non-regular identifiers, must be quoted. Unknown schema names are ignored. If SYSTEM is not included, the server will automatically add it as the last schema.

  • DatabaseMetaData

    • Methods accepting a schema (exact match if not null) or schemaPattern (LIKE match if not null) will return no rows for value empty ("") on Firebird 6.0 and higher; use null or — schemaPattern only — "%" to match all schemas

    • getCatalogs — when useCatalogAsPackage=true — returns all (distinct) package names over all schemas. Within the limitations and specification of the JDBC API, this method cannot be used to find out which schema(s) contain a specific package name.

    • getColumnPrivileges and getTablePrivileges received an additional column, JB_GRANTEE_SCHEMA, which is non-null for grantees that are schema-bound (e.g. procedures).

      As this is a non-standard column, we recommend to always retrieve it by name.

    • getProcedures received two additional columns.

      As these are non-standard columns, we recommend to always retrieve them by name.

      • JB_PROCEDURE_TYPE — value of column RDB$PROCEDURE_TYPE

        For the possible values, the following constants were added to FirebirdDatabaseMetaData:

        • jbProcedureTypeUnknown (0)

        • jbProcedureTypeSelectable (1)

        • jbProcedureTypeExecutable (2).

      • JB_PROCEDURE_SOURCE — value of column RDB$PROCEDURE_SOURCE: the body of the stored procedure; this column is null for procedures in a package.

    • getProcedureSourceCode is deprecated, the recommended replacement is DatabaseMetaData.getProcedures(String, String, String), column JB_PROCEDURE_SOURCE.

    • getTriggerSourceCode/getViewSourceCode now also have an overload accepting the schema; the overloads without a schema parameter, or schema is null will return the source code of the first match found (schema order is undefined). This behaviour also applies for — now deprecated — getProcedureSourceCode(String).

      The schema parameter is ignored on Firebird 5.0 and older.

    • getSchemas() returns all defined schemas

    • getSchemas(String catalog, String schemaPattern) returns all schemas matching the LIKE pattern schemaPattern, with the following caveats

      • catalog non-empty will return no rows — even if useCatalogAsPackage is true; we recommend to always use null for catalog

  • ResultSetMetaData

    • getSchemaName reports the schema if the column is backed by a table, otherwise empty string ("")

  • FirebirdConnection/FBConnection

    • setSchema will modify the search path by prepending the specified schema, or — if setSchema was called previously — replacing the previous value set.

      The schema is not checked for existence, and setting one will not result in an exception, see also note about getSchema below.

    • getSchema() reports the value of CURRENT_SCHEMA, which is the first valid (i.e. existing) schema on the search path.

      The value reported can change if a previously missing schema is created in the database.

    • Added method String getSearchPath() to obtain the search path as reported by RBB$GET_CONTEXT('SYSTEM', 'SEARCH_PATH'), or null if schemas are not supported

    • Added method List<String> getSearchPatList() to obtain the search path as a list of unquoted object names, or empty list if schemas are not supported

    • Added methods setSearchPath(String) and setSearchPathList(String…​)/(List<String>) to set the search path; these methods throw SQLFeatureNotSupportedException if schemas are not supported.

  • StatisticsManager

    • getTableStatistics

      • getTableStatistics(String[] tableNames) was changed to accept varargs (getTableStatistics(String…​ tableNames))

      • Added overload getTableStatistics(Collection<String> tableNames) with same behaviour as getTableStatistics(String…​ tableNames)

      • Added overload getTableStatistics(Collection<String> schemas, Collection<String> tableNames) — if schemas is non-empty, on Firebird 6.0 and higher, it will restrict the search for tables to the specified schemas; if tableNames is empty, and schemas is not, only the tables of the specified schemas will be reported

  • FBTableStatisticsManager (experimental feature)

    • For schema-bound tables, the key of the map returned by getTableStatistics() is a fully qualified and quoted table reference (i.e. <quoted-schema>.<quoted-table-name>). For schemaless tables (Firebird 5.0 and older, or tables that were not found), the key is still the unquoted <table-name>.

    • The static method toKey(String schema, String tableName) can be used to create a table reference in the same format as the key of the map returned by getTableStatistics(). The schema can be null or empty string for schemaless tables (i.e. Firebird 5.0 or older)

    • The TableStatistics object received additional accessors:

      • schema() with the schema, or empty string for schemaless (Firebird 5.0 or older) or if the table was not found

      • tableReference() with the fully qualified and quoted table reference (i.e. [<quoted-schema>.]<quoted-table-name>)

7.6. Statement maximum field size (maxFieldSize) support

Support for truncating values returned by a result set to the maxFieldSize property of a Statement was implemented. This is a required JDBC feature, but in previous Jaybird 6 and older, the statement implementation only recorded the value, and then ignored it.

The maxFieldSize value is defined in bytes, and is applied when the value is greater than zero. Truncation occurs for CHAR, VARCHAR, BINARY, VARBINARY, BLOB SUB_TYPE TEXT (JDBC LONGVARCHAR), and BLOB SUB_TYPE BINARY and other Firebird built-in (positive) blob subtypes (JDBC LONGVARBINARY), but not custom (negative) subtypes (Jaybird considers those JDBC BLOB, and JDBC specifies that type should not be limited by maxFieldSize).

In case of CHAR, VARCHAR, BINARY, and VARBINARY, the truncation is performed when fetching a row (in the GDS-ng layer) if it is not an RDB$DB_KEY column. This is a client-side truncation, and does not reduce the number of bytes transferred, only the number of bytes retained in memory and returned from the result set.

In the case of built-in (non-negative) blob subtypes, the truncation is performed in the result set field implementation in the JDBC layer. This is a client-side truncation, but it may reduce the number of bytes transferred if the blob wasn’t already transferred as an inline blob.

For these blob subtypes, the truncation will not occur for methods returning a Blob, Clob, InputStream or Reader if the result set is not cached locally (cached result sets are used for holdable result sets and emulated scrollable result sets). In the case of InputStream and Reader, this doesn’t conform to the JDBC requirements, but avoided complications in the implementation. We may address this in the future.

Caveats:

  • Given the truncation happens at a set number of bytes, values in a multibyte character set (UTF8) might end in the Unicode replacement character (U+FFFD, ‘�’) due to truncation before the end of the encoded codepoint.

  • Jaybird will accept any non-negative value for maxFieldSize. The JDBC apidoc recommends using values greater than 256.

  • A too small maxFieldSize may result in “wrong” values being returned without error for numeric and Boolean getters; for datetime getters it may result in missing precision without errors, or parse errors.

  • Setting the max field size after execute may not be immediately applied to the current result set for CHAR, VARCHAR, BINARY, and VARBINARY:

    • For a locally cached result set: never, as the rows were truncated to the maxFieldSize on execute.

    • Otherwise, already fetched rows are truncated to the maxFieldSize on their fetch, and only rows returned by a subsequent fetch will apply the new limit.

  • For LONGVARCHAR/LONGVARBINARY, the value will be truncated on access, with the following caveats:

    • For cached blobs, the limit is applied on retrieval, and applies to all methods (as the cached value is truncated).

    • The value of a cached blob (holdable result set or emulated scrollable result set) will be truncated to the initial maxFieldSize. Subsequent use of a larger maxFieldSize will continue to return the shorter value.

  • The detection of RDB$DB_KEY columns includes “normal” BINARY/CHAR CHARACTER SET OCTETS columns called DB_KEY.

For further details, see jdp-2025-07: Statement Max Field Size.

7.7. Connection property escapeProcessing

A Boolean connection property escapeProcessing was added to control the default JDBC escape processing behaviour of Statement objects created by a Connection. This connection property is defined in JDBC 4.2. Support is available through DriverManager and on Jaybird’s data source implementations.

It’s default value is true, meaning JDBC escape processing is enabled. When set to false, JDBC escapes are not processed, and sent as is to the server (which will usually result in a syntax error like a “Token unknown”).

Use of this property is the only way to disable escape processing for PreparedStatement and CallableStatement. For Statement — but not PreparedStatement and CallableStatement (but see note below) — the escape processing behaviour can be changed dynamically using Statement#setEscapeProcessing(boolean).

Disabling escape processing can have a small performance benefit when your statements never contain any JDBC escapes.

Note
CallableStatement deviation for JDBC call-escape

In its current implementation, the escape processing behaviour of CallableStatement has a deviation from the JDBC-specified behaviour. Specifically, when escapeProcessing=false, Connection#prepareCall(…​) will parse and transform the JDBC call escape ({[?=]call procedure-name[(<parameters>)]}) anyway. It will not process other JDBC escapes when escape processing is disabled.

Given further changes to and potentially a fundamental rewrite of the CallableStatement implementation are in the works, we didn’t want to touch the code responsible for this deviation at this time. This non-standard behaviour may change before Jaybird 7.0.0 release, or in a later major release.

7.8. Other fixes and changes

  • Changed the documentation of FirebirdDatabaseMetaData methods getProcedureSourceCode, getTriggerSourceCode and getViewSourceCode that the object not being found is reported by a null value, not a SQLException. With this change, the documentation reflects the actual behaviour.

  • Fixed: race condition during cancellation (#903)

    This change introduce an additional lock during transmit (sending to the server). Maintainers of Jaybird forks, or implementers of custom wire protocol implementations subclassing classes in org.firebirdsql.gds.ng.wire and related packages will need to take out this transmit lock when sending to the server. The change also lead to incompatible changes to protected methods in the various protocol implementation classes, like adding an XdrOutputStream parameter to various methods, and methods renamed for consistency.

  • Upgraded org.firebirdsql.extern.decimal to decimal-java 2.0.1

  • Support USING clause in generated keys detection (#932)

  • Add support for parenthesized queries to StatementDetector (#933)

  • …​

8. Compatibility changes

Jaybird 7 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. Potential compatibility issues due to schema support

The implementation of schema support may cause compatibility issues. In general, these changes will only impact Jaybird when connecting to Firebird 6.0 or higher.

We recommend looking over this section even if you currently do not use Firebird 6.0 or higher, so you can prepare your code to be ready for a future migration to Firebird 6.0.

8.1.1. Parameters schema and schemaPattern in methods of DatabaseMetaData

In previous versions, Jaybird ignored the schema and schemaPattern parameters of the DatabaseMetaData methods (usually the second parameter of DatabaseMetaData.getXXX(…​) methods). In Jaybird 7, it no longer ignores these parameters when querying a Firebird 6.0 or higher database.

If you currently pass the “wrong” value for these methods, especially "" (empty string, i.e. only return schemaless objects), you may get no or fewer results than expected.

schema

The schema parameter performs an exact, case-sensitive match on the schema name, unless it’s null (i.e. don’t filter by schema).

If your code currently passes "" (empty string), you need to either replace it with null (don’t filter by schema), or the desired schema name.

DatabaseMetaData methods with schema parameter

  • getBestRowIdentifier

  • getColumnPrivileges

  • getCrossReference (parameters parentSchema and foreignSchema)

  • getExportedKeys

  • getImportedKeys

  • getIndexInfo

  • getPrimaryKeys

  • getVersionColumns

(Unsupported metadata methods are not listed.)

schemaPattern

The schemaPattern parameter performs a case-sensitive LIKE match on the schema name, unless it’s null (i.e. don’t filter by schema).

If your code currently passes "" (empty string), you need to either replace it with null (don’t filter by schema), use "%" (match all schemas, effectively the same as passing null), or an appropriate LIKE pattern for the desired schemas.

DatabaseMetaData methods with schemaPattern parameter

  • getColumns

  • getFunctionColumns

  • getFunctions

  • getProcedureColumns

  • getProcedures

  • getPseudoColumns

  • getSchemas

  • getTablePrivileges

  • getTables

(Unsupported metadata methods are not listed.)

8.2. Removal of classes, packages and methods without deprecation

Below list of removals may look daunting, but if you use Jaybird only as a JDBC driver, through the JDBC API, you’re likely unaffected. Although we list them as removed without deprecation, some were marked as deprecated retroactively in Jaybird 5.0.3 or later.

This section does not include all changes to packages or classes considered internal API.

8.2.1. Removal of packages without deprecation

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

  • …​

8.2.2. Removal of methods without deprecation

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

  • …​

8.2.3. Removal of classes without deprecation

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

  • …​

8.2.4. Removal of constants without deprecation

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

  • …​

8.3. Removal of deprecated classes, packages and methods

Below list of removals may look daunting, but if you use Jaybird only as a JDBC driver, through the JDBC API, you’re likely unaffected.

8.3.1. Removal of deprecated packages

The following packages have been removed in Jaybird 7:

  • …​

8.3.2. Removal of deprecated methods

The following methods have been removed in Jaybird 7:

  • GDSFactoryPlugin (semi-internal API)

    • getTypeAliases() — use getTypeAliasList()

    • getSupportedProtocols — use getSupportedProtocolList()

  • GDSHelper (internal API)

    • startTransaction(TransactionParameterBuffer) — use FbDatabase.startTransaction(TransactionParameterBuffer) followed by GDSHelper.setCurrentTransaction(FbTransaction)

  • FirebirdStatement

    • getCurrentResultSet() — use getResultSet()

  • SqlCountHolder (internal API)

    • getLongUpdateCount() — use updateCount()

    • getLongDeleteCount() — use deleteCount()

    • getLongInsertCount() — use insertCount()

    • getLongSelectCount() — use selectCount()

8.3.3. Removal of deprecated classes

The following classes have been removed in Jaybird 7:

  • GDSException; use SQLException or one of its (normal) subclasses

  • FBSQLException; use SQLException

8.3.4. Removal of deprecated constants

The following constants have been removed in Jaybird 7:

  • ISCConstants

    • isc_isc_sql_dialect_conflict_num; use isc_sql_dialect_conflict_num

    • isc_err_max; there is no replacement

  • JaybirdErrorCodes

    • jb_stmtInErrorRequireCLose; use jb_stmtInErrorRequireClose

  • QuoteStrategy

    • NO_QUOTES; use DIALECT_1

    • QUOTES; use DIALECT_3

  • SQLStateConstants

    • SQL_STATE_CONNECTION_CLOSED (08003); use SQL_STATE_CONNECTION_FAILURE (08006).

  • ServiceManager

    • getHost/setHost; use getServerName/setServerName

    • getPort/setPort; use getPortNumber/setPortNumber

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

Note

Only changes we think are relevant to driver implementers or (internal) API users are documented. This means there may be undocumented changes to internal API. If you are confronted with such a change, let us know on firebird-java, so we can take this into account when documenting future changes.

  • FbAttachment

    • The close() method should no longer throw an exception if already closed, or not connected/attached.

  • WireConnection

    • Method writeDirect(byte[]) was removed; use the XdrOutputStream under the transmit lock.

  • FbWireAsynchronousChannel

    • connect(String, int, int) was replaced by connect(String, int)

  • FbWireOperations

    • The ProcessAttachCallback parameter of authReceiveResponse was removed, as all implementations did nothing, and since protocol 13, it wasn’t only called for the attach response

    • Interface ProcessAttachCallback was removed

    • Method writeDirect(byte[]) was removed; use the XdrOutputStream under the transmit lock.

  • The internal interface org.firdsql.jdbc.field.BlobListenableField was renamed to BlobField due to increased responsibilities

  • XdrOutputStream

  • writeDirect(byte[]) was removed; use the XdrOutputStream under the transmit lock.

  • XdrStreamAccess

    • Method withTransmitLock(TransmitAction) was added for using the XdrOutputStream under the transmit lock. This method should be preferred over calling getXdrOut(). TransmitAction is a functional interface with method transmit(XdrOutputStream xdrOut) throws IOException, SQLException.

  • Various wire protocol implementation classes (in org.firebirdsql.gds.ng.wire and “sub”-packages)

    • Methods protected XdrOutputStream getXdrOut() were removed; the replacement is protected void withTransmitLock(TransmitAction). This was done to enforce use of the transmit lock.

    • When sending data to the server, the transmit lock must be taken out, and it must be released before performing another blocking action like reading (receiving) data from the server. For this purpose, use withTransmitLock(TransmitAction).

    • Some protected methods for sending messages to the server were renamed for consistency; in general, methods of the form sendXxx, sendXxxPacket, sendXxxMessage, or doXxxPacket, or similar, to sendXxxMsg (where Xxx is a name of the message action or type).

    • Some protected methods for sending messages or (partial) data to the server received an additional XdrOutputStream parameter.

      Usually, callers of these methods are responsible for taking out the transmit lock.

    • The protected methods for sending messages to the server (the sendXxxMsg methods mentioned earlier) now consistently do not call flush() on the XdrOutputStream to simplify protocol versioning of the messages. The caller is now responsible for flushing (if needed).

    • Additional protected methods were added (or were changed from private) for sending messages to the server.

  • V10Statement

    • sendPrepareMsg (previously sendPrepare) no longer calls switchState(StatementState.PREPARING); this is now done by its callers.

      Subclasses overriding this method must ensure they do not switch state to PREPARING themselves, and callers must ensure they switch state before calling this method.

  • V16Statement

    • the sendBatchMsg protected method — accepting RowDescriptor and Collection<RowValue> — was made private. The new protected method of the same name is only responsible for sending the op_batch_msg itself, not the subsequent row data.

  • RowDescriptor

    • createRowDescriptor(FieldDescriptor[], DatatypeCoder) was removed; use constructor RowDescriptor(List<FieldDescriptor>, DatatypeCoder)

  • RowDescriptorBuilder

    • toRowDescriptor() can no longer build an incomplete row descriptor, and throws an IllegalStateException if one or more fields have not been defined. There is no replacement to build incomplete row descriptors.

  • FBCachedBlob

    • Constructor FBCachedBlob(byte[]) no longer accepts null.

  • AuthenticationPluginRegistry

    • getAuthenticationPluginSpi now returns Optional<AuthenticationPluginSpi>

  • EncryptionPluginRegistry

    • getEncryptionPluginSpi now returns Optional<EncryptionPluginSpi>

  • EncryptionInitInfo

    • Success and failure are now represented by two sealed subclasses instead of the enum InitResult. Methods to obtain the ciphers are only available in the Success subclass, the cause (exception) only in Failure.

8.5. Unlikely breaking changes

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

  • Native connections now use isc_dpb_utf8_filename or isc_spb_utf8_filename and UTF-8 for the database and service parameter buffer during attach if the client is Firebird 3.0 or higher.

8.6. Breaking changes for Jaybird 8

With Jaybird 8 the following breaking changes will be introduced.

8.6.1. Removal of deprecated classes, packages and methods

Removal of deprecated methods

The following methods will be removed in Jaybird 8:

  • WireConnection.getProtocolMinimumType() — use WireConnection.getProtocolType()

    This method might still be removed before Jaybird 7 final release as this is internal API, and unlikely to be used in user code.

  • XdrOutputStream.write(byte[], int, int, int) — if really needed, use write(byte[], int, int), and writeSpacePadding(int) or writeZeroPadding(int)

Removal of deprecated classes

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

  • …​

8.6.2. Removal of deprecated constants

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

  • …​

9. Compatibility notes

9.1. Type 2 (native) and embedded driver

Since Jaybird 6, the native and embedded part of the driver has been moved to a separate artifact, jaybird-native. The Jaybird Native GDS Factory plugin uses JNA to access the client library. If you want to use the Type 2 driver, or Firebird embedded, then you need to include jaybird-native-{version_example} and jna-jpms-5.18.1.jar on the classpath.

When using Maven, you need to specify the dependency on jaybird-native:

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird-native</artifactId>
    <version>{version_example}</version>
</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.3.0</artifactId>
</dependency>

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

In the future we may provide JARs with the embedded libraries of a specific Firebird version.

Appendix A: License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at https://firebirdsql.org/en/public-documentation-license/.

The Original Documentation is “Jaybird {version_wo_target} Release Notes”. The Initial Writer of the Original Documentation is Mark Rotteveel, Copyright © 2012-2026. All Rights Reserved. (Initial Writer contact(s): mark (at) lawinegevaar (dot) nl).

Contributor(s): David Jencks, Rick Fincher, Roman Rokytskyy.
Portions created by David Jencks are Copyright © 2002. All Rights Reserved. (Contributor contact(s): unknown).
Portions created by Rick Fincher are Copyright © 2002-2003. All Rights Reserved. (Contributor contact(s): unknown).
Portions created by Roman Rokytskyy are Copyright © 2004-2010. All Rights Reserved. (Contributor contact(s): unknown).

The exact file history is recorded in our Git repository; see https://github.com/FirebirdSQL/jaybird

1. The wide range of the percentages is due to running the test with a single hop and two hops between client and server, and thus a wide range of latency.