## 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.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 (jaybird#728)

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

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

### 1.2. Jaybird 5.0.0

First release of Jaybird 5.

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

### 1.3. Jaybird 5.0.0-beta-1

Initial release for evaluation.

## 2. Known issues

• Using a native connection with a Firebird 3 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.

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

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:

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.1 was tested against Firebird 2.5.9, 3.0.10, and 4.0.2 and a recent snapshot of Firebird 5.0, but should also support other Firebird versions from 2.5 and up.

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

### 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 and the most recent LTS version after Java 17 and the latest Java release. Currently, that means we support Java 8, 11, 17 and 19.

 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.

### 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.1

#### 5.1.1. Maven

Jaybird 5.0.1 is available on Maven Central:

 groupId org.firebirdsql.jdbc artifactId jaybird version 5.0.1. (where  is java11 or java8)

For example:

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

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

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

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

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

## 6. Upgrading from Jaybird 4 to Jaybird 5

### 6.1. Maven

Change the version of the dependency to 5.0.1.<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.12.1 (Jaybird 5 requires at least JNA 5.0).

<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna</artifactId>
<version>5.12.1</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.1.<java>.jar (where <java> is java11 or java8)

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

2. Replace the jna-5.5.0.jar library with jna-5.12.1.jar

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 and 4.0, and provides tentative support for Firebird 5.0. Firebird 5.0 will become fully supported in the first release after Firebird 5.0.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.

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

### 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 in Jaybird 6

• 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 driver 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, 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.

• Firebird 4.0 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 when we retrofit the new behaviour for emulated as well.

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

 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.

### 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 (jaybird#428)

Backported to Jaybird 3.0.9 and 4.0.1.

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

• Changed: removed debug logging in AbstractFbStatement.ensureClosedCursor (jaybird#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() (jaybird#663)

This change was contributed by Vasiliy Yashkov.

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

• Improvement: Attempts to connect without username and password with 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”) (jaybird#583)

• Improvement: Don’t send cursor close to server when closing ResultSet in response to Statement close (jaybird#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 (jaybird#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 (jaybird#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 (jaybird#677)

• Fix: FBStatement allowed retrieval of update count after error, while FBPreparedStatement — correctly — did not (jaybird#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 (jaybird#684)

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

• New feature: Support for isc_spb_expected_db on service manager (jaybird#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 (jaybird#699)

• Fix: XAResource checked at most 10 records for forget or recovery operations (jaybird#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 (jaybird#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 (jaybird#705)

• New feature: Support for NBackup “clean history” option (jaybird#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 (jaybird#713)

This requires Firebird 3.0 or higher server and a Firebird 3.0 or higher fbclient. Longer statement texts were already supported for pure-java connections.

• Fixed: DatabaseMetaData.getIdentifierQuoteString() should return " " (space) for connection dialect 1 (jaybird#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 (jaybird#715)

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

## 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 mailing 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:

• org.firebirdsql.jdbc.parser; there is no compatible replacement. Its successor is the internal API in org.firebirdsql.jaybird.parser. See also New parser for generated keys handling.

#### 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 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 ALLOCATEDPREPARED is no longer valid, and must now be ALLOCATEDPREPARINGPREPARED.

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.

Possibly, wire protocol versions for Firebird 2.5 and earlier will be disabled by default to disallow connection for the pure-java protocol. If that happens, an option will be provided 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.

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

#### 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 to access the client library. If you want to use the Type 2 driver, or Firebird embedded, then you need to include jna-5.12.1.jar on the classpath.

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

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

In the future we will move the Type 2 support to a separate library and provide JNA-compatible jars that provide the embedded libraries of a specific Firebird version.