# Jaybird 5.0.7 Release Notes

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

The following has been changed or fixed since Jaybird 5.0.6:

- Improvement: backported deferred blob open optimization from Jaybird 7 (#841)

  See also Deferred blob open.

- Fixed: `NullPointerException` in `getGeneratedKeys()` with blob columns after (auto)commit (#846)

  As part of this fix, there was an incompatible change in the internal GDS-ng API. Various methods and constructors involved in blob handle creation now throw a `SQLException` if the database is not attached or the transaction is null or not active. See also Breaking changes internal API for 5.0.7.

  This fix was backported from Jaybird 6.0.1.

- Fixed: Fetch response with status=0 (FETCH_OK) and count=0 was logged on DEBUG as an unexpected response (#848)

  This fix was backported from Jaybird 6.0.1.

- Improvement: backported performance improvements for blob reading and writing from Jaybird 6 (#850)

  For details see:

  - Reading blobs

  - Writing blobs

  - Minimum `blobBufferSize` 512 bytes

  - Maximum segment size raised

  - Effectiveness of `blobBufferSize` larger than maximum segment size

  - Internal API changes for `FbBlob`

- Improvement: backported fetching all known blob info items on open from Jaybird 7 (#852)

  See also Requesting known info items on open.

- Dependency update: updated `net.java.dev.jna:jna-jpms` from 5.15.0 to 5.17.0 (used by `jaybird-native`) (#855)

### 1.2. Jaybird 5.0.6

The following has been changed or fixed since Jaybird 5.0.5:

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

  This fix was backported from Jaybird 6.

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

  This fix was backported from Jaybird 6.

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

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

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

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

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

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

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

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

### 1.3. Jaybird 5.0.5

The following has been changed or fixed since Jaybird 5.0.4:

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

  This fix was backported from Jaybird 6.

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

  This improvement was backported from Jaybird 6.

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

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

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

  This feature was backported from Jaybird 6.

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

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

  This feature was backported from Jaybird 6.

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

  This improvement was backported from Jaybird 6.

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

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

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

  This improvement was backported from Jaybird 6.

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

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

### 1.4. Jaybird 5.0.4

The following has been changed or fixed since Jaybird 5.0.3:

- Firebird 5.0 is now formally supported

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

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

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

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

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

### 1.5. Jaybird 5.0.3

The following has been changed or fixed since Jaybird 5.0.2:

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

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

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

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

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

- Updated: error messages updated from Firebird 5.0.0.1272

### 1.6. Jaybird 5.0.2

The following has been changed or fixed since Jaybird 5.0.1:

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

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

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

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

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

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

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

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

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

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

### 1.7. Jaybird 5.0.1

The following has been changed or fixed since Jaybird 5.0.0:

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

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

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

### 1.8. Jaybird 5.0.0

First release of Jaybird 5.

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

### 1.9. Jaybird 5.0.0-beta-1

Initial release for evaluation.

## 2. Known issues

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

  Possible workarounds:

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

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

  - Use a Firebird 2.5 or earlier `fbclient`.

  This is caused by firebird#4971

- In Java 24, 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. 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.

See also Where to get help

## 4. General Notes

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

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

### 4.1. About this version

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

The major changes and new features in Jaybird 5 are:

- Java 7 support dropped

- Java Connector Architecture (JCA) support removed

- ChaCha wire protocol encryption support (Java 11 and higher only)

- Changes to properties

- Unification of database and service addressing

- Changes to JDBC URL syntax

- Removal of LOCAL protocol implementation

- Stream blobs are now the default

- New parser for generated keys handling (backported to Jaybird 4.0.8)

- Firebird 4.0 server-side batch updates

- Firebird 5.0 multi-row RETURNING support

- Firebird Embedded locator service provider (experimental)

- Table statistics of a connection (experimental)

- Blob performance improvements (since Jaybird 5.0.7)

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

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

### 4.2. Supported Firebird versions

Jaybird 5.0.7 was tested against Firebird 2.5.9, 3.0.12, 4.0.5, and 5.0.2, but should also support other Firebird versions from 2.5 and up.

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

### 4.3. Supported Java versions

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

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

| Jaybird 5 will be the last version to support Java 8 and 11. Jaybird 6 will use Java 17 as the baseline (minimum) version. We highly recommend upgrading to Java 17 or higher. Jaybird 5 will serve as a “long-term support” version for Java 8 and 11, with maintenance releases at least until the release of Jaybird 7.

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

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

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

### 4.4. Specification support

Jaybird supports the following specifications:

Specification | Notes
--- | ---
JDBC 4.3 | All JDBC 4.3 methods for features supported by Firebird; Java 9 and higher supported using the Java 8 or Java 11 driver.
JDBC 4.2 | All JDBC 4.2 methods for features supported by Firebird.
JTA 1.0.1 | Implementation of `javax.transaction.xa.XAResource` interface via `XADataSource` implementation.

## 5. Getting Jaybird 5

### 5.1. Jaybird 5.0.7

#### 5.1.1. Maven

Jaybird 5.0.7 is available on Maven Central:

groupId | `org.firebirdsql.jdbc`
artifactId | `jaybird`
version | `5.0.7.<java>` (where `<java>` is `java11` or `java8`)

For example:

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

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

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

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

See also Type 2 (native) and embedded driver.

#### 5.1.2. Download

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

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

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

## 6. Upgrading from Jaybird 4 to Jaybird 5

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

### 6.1. Maven

Change the version of the dependency to `5.0.7.<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.17.0 (Jaybird 5 requires at least JNA 5.0, but we recommend using JNA 5.17.0).

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

### 6.2. Manual install

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

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

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

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

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

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

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

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

### 6.3. Gotcha’s

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

For known issues, consult Known issues.

## 7. What’s new in Jaybird 5

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

### 7.1. Java support

#### 7.1.1. Java 7 support dropped

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

#### 7.1.2. Java 8

The driver supports Java 8.

Jaybird 5 is the last version to support Java 8

#### 7.1.3. Java 9 and higher

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

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

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

For compatibility with Java 9 modules, Jaybird defines the automatic module name `org.firebirdsql.jaybird`. This guarantees a stable module name for Jaybird, and allows for future modularization of Jaybird. If you need “real” module support, upgrade to Jaybird 6.

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

### 7.2. Firebird support

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

Jaybird 5 is the last version to support Firebird 2.5.

### 7.3. Java Connector Architecture (JCA) support removed

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

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

### 7.4. ChaCha wire protocol encryption support

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

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

Jaybird does not support the `ChaCha64` wire protocol encryption. Support for `ChaCha64` has been introduced in Jaybird 6.

### 7.5. Changes to properties

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

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

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

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

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

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

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

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

   - `get/setConnectionDialect()`— use `get/setSqlDialect()`.

   - `get/setBuffersNumber`— use `get/setPageCacheSize`.

   - `get/setBlobBufferLength`— use `get/setBlobBufferSize`.

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

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

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

### 7.6. Unification of database and service addressing

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

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

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

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

Some examples that all identify the same database:

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

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

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

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

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

Some examples that all identify the same service:

- `(serverName = "localhost", portNumber = 3050, serviceName = "service_mgr")`

- `(serverName = "localhost", portNumber = 3050, serviceName = null)`

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

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

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

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

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

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

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

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

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

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

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

### 7.7. Changes to JDBC URL syntax

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

1. More lenient syntax

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

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

#### 7.7.1. More lenient syntax

The syntax of JDBC URLs is now more lenient.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

| Support for the WNET protocol is removed in Firebird 5.0.

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

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

Some examples:

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

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

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

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

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

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

| Just because you can do this, doesn’t mean you should! We recommend not to specify `serverName`, `portNumber` and `databaseName` as explicit connection properties when using `DriverManager`, but instead only use the URL itself to define the address of the database. The behaviour defined in this section is the result of unification and simplification of connection property handling across JDBC URLs, data sources and internals of Jaybird.

### 7.8. Removal of LOCAL protocol implementation

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

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

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

### 7.9. Stream blobs are now the default

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

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

### 7.10. New parser for generated keys handling

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

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

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

This change was also backported to Jaybird 4.0.8.

### 7.11. Firebird 4.0 server-side batch updates

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

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

Two new properties have been added for this feature:

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

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

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

  This property supports the following value ranges:

  `< 0` | use server-side default (16MB as of Firebird 4.0)
  `0` | (default) use server-side maximum (256MB as of Firebird 4.0)
  `> 0` | use specified size, capped at server-side maximum

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

This support comes with a number of limitations:

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

- Only supported on `PreparedStatement`.

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

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

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

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

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

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

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

### 7.12. Firebird 5.0 multi-row RETURNING support

Jaybird supports multi-row `RETURNING` introduced in Firebird 5.0.

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

### 7.13. Firebird 5.0 scrollable cursor support

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

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

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

`EMULATED`

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

`SERVER`

  Use server-side scrollable cursors, if possible

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

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

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

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

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

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

See also jdp-2021-04.

### 7.14. Firebird Embedded locator service provider (experimental)

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

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

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

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

### 7.15. Table statistics of a connection (experimental)

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

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

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

### 7.16. Blob performance improvements

#### 7.16.1. Reading blobs

Added in: Jaybird 5.0.7, backported from Jaybird 6

Performance of reading blobs has been improved, especially when using `getBytes` on `ResultSet` or `Blob`, or `getString` on `ResultSet` or `Clob`, or reading from a blob input stream with `read(byte[], int, int)` and similar methods with a byte array and requested length greater than 50% of the configured `blobBufferSize`.

Testing on a local network (Wi-Fi) shows an increase in throughput of roughly 50-100% for reading large blobs with the default `blobBufferSize` of 16384.

These throughput improvements were only realised in the pure Java protocol, because there we had the opportunity to avoid all additional allocations by writing directly from the network stream into the destination byte array, and this allows us to ignore the configured `blobBufferSize` and use up to the maximum request size of 65535 bytes instead.

This is not possible for the JNA-based protocols (native/embedded), as the implementation requires a direct byte buffer to bridge to the native API, and thus we can’t ignore the `blobBufferSize`. We were able to realise some other optimizations (in both pure Java and JNA), by avoiding allocation of a number of intermediate objects, but this has only marginal effects on the throughput.

#### 7.16.2. Writing blobs

Added in: Jaybird 5.0.7, backported from Jaybird 6

Performance of writing blobs was improved, especially when using `setBytes` on `PreparedStatement`, `ResultSet` or `Blob`, or `setString` on `PreparedStatement`, `ResultSet` or `Clob`, or writing to a blob output stream with `write(byte[], int, int)` and similar methods with a byte array larger than the configured `blobBufferSize`. A smaller improvement was made when using arrays larger than 50% of the `blobBufferSize`.

Testing on a local network (Wi-Fi) shows an increase in throughput of roughly 300-400% for writing large blobs with the default `blobBufferSize` of 16384. The improvement is not available for all methods of writing blobs, for example using `ResultSet.setBinaryStream` does not see this improvement, as it relies on the `blobBufferSize` for transferring the blob content.

Most of these throughput improvements were only realised in the pure Java protocol, because there we had the opportunity to avoid all additional allocations by writing directly from the source byte array to the network stream, and this allows us to ignore the configured `blobBufferSize` and use up to the maximum segment size of 65535 bytes instead.

For the JNA-based protocols (native/embedded) a smaller throughput improvement was realised, by using the maximum segment size for the first roundtrip if the array write used offset `0`. If the length is larger than the maximum segment size, or if the offset is non-zero, we need to allocate a buffer (for subsequent segments in case offset is `0`), and thus cannot ignore the `blobBufferSize`.

Similar to the improvements for reading, we were also able to realise some other optimizations (in both pure Java and JNA), by avoiding allocation of a number of intermediate objects, but this has only marginal effects on the throughput.

#### 7.16.3. Deferred blob open

Added in: Jaybird 5.0.7, backported from Jaybird 7

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

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

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.16.4. Requesting known info items on open

Added in: Jaybird 5.0.7, backported from Jaybird 7

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.

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

#### 7.16.5. Minimum `blobBufferSize` 512 bytes

Added in: Jaybird 5.0.7, backported from Jaybird 6

As part of the performance improvements, a minimum `blobBufferSize` of 512 bytes was introduced. Configuring values less than 512 will be ignored and use 512 instead.

#### 7.16.6. Maximum segment size raised

Added in: Jaybird 5.0.7, backported from Jaybird 6

For connections to Firebird 3.0 and higher, the maximum segment size was raised from 32765 to 65535 bytes to match the maximum segment size supported by Firebird.

The maximum segment size is the maximum size for sending segments (put) to the server. Due to protocol limitations, retrieving segments from the server (get) is two bytes (or multiples of two bytes) shorter[1].

#### 7.16.7. Effectiveness of `blobBufferSize` larger than maximum segment size

Added in: Jaybird 5.0.7, backported from Jaybird 6

Previously, when reading blobs, a `blobBufferSize` larger than the maximum segment size was effectively ignored. Now, when reading through an input stream, a `blobBufferSize` larger than the maximum segment size can be used.

Jaybird will use one or more roundtrips to fill the buffer. To avoid inefficient fetches, a minimum of 90% of the buffer size will be filled up to the `blobBufferSize`. This change is not likely to improve performance, but it may allow for optimizations when reading or transferring data in large chunks.

In general, setting the `blobBufferSize` larger than 65535 bytes will likely not improve performance.

#### 7.16.8. Internal API changes for `FbBlob`

Added in: Jaybird 5.0.7, backported from Jaybird 6

Three new methods were added to `FbBlob`:

`int get(byte[] b, int off, int len)`

  populates the array `b`, starting at `off`, for the requested `len` bytes from the blob, and returns the actual number of bytes read. This method will read until `len` bytes have been read, and only return less than `len` when end-of-blob was reached.

`int get(byte[] b, int off, int len, float minFillFactor)`

  populates the array `b`, starting at `off`, for at least `minFillFactor` * `len` bytes (up to `len` bytes) from the blob, and returns the actual number of bytes read.

`void put(byte[] b, int off, int len)`

  sends data from array `b` to the blob, starting at `off`, for the requested `len` bytes.

The documentation of method `FbBlob.putSegment(byte[])` contradicted itself, by requiring implementations to batch larger arrays, but also requiring them to throw an exception for larger arrays, and the actual implementations provided by Jaybird threw an exception. This contradiction has been removed, and the implementations will now send arrays longer than the maximum segment size to the server in multiple put requests.

### 7.17. Potentially breaking changes

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

See also Compatibility changes for details.

### 7.18. Other fixes and changes

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

  Backported to Jaybird 3.0.9 and 4.0.1.

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

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

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

- Improvement: Optimization of `ResultSet.next()` (#663)

  This change was contributed by Vasiliy Yashkov.

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

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

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

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

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

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

  This feature was also backported to Jaybird 4.0.4.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  This feature was also backported to Jaybird 4.0.7.

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

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

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

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

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

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

### 7.19. Removal of deprecated classes and packages

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

## 8. Compatibility changes

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

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

### 8.1. Support for Java 7 dropped

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

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

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

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

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

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

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

### 8.3. Changes to connection properties

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

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

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

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

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

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

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

#### 8.3.1. Changes to setNonStandardString(String)

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

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

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

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

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

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

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

### 8.4. Generated keys support always available

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

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

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

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

There are two possible solutions for this error:

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

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

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

### 8.6. Changes affecting metadata compatibility

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

### 8.7. Removal of classes, packages and methods without deprecation

#### 8.7.1. Removal of packages without deprecation

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

- `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 its constructor

- `GDSHelper`

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

  - `openBlob(long, boolean)`, use `openBlob(long, BlobConfig)`

  - `createBlob(boolean)`, use `createBlob(BlobConfig)`

  - `getJavaEncoding()`; there is no replacement

  - `getBlobBufferLength()`, use `getConnectionProperties().getBlobBufferSize()`

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

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

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

- constructor `FBCachedClob(FBCachedBlob, String)`, use `FBCachedClob(FBCachedBlob, FBBlob.Config)`

- constructor `FBProcedureParam()`, use `FBProcedureParam(int, String)`

The following methods had their visibility reduced:

- `FBTpbMapper.getDefaultTransactionIsolation()` to default access.

- `FBTpbMapper.setDefaultTransactionIsolation(int)` to default access.

- `FBProcedureParam`

  - `isParam()` made final

  - `getPosition()` made final

  - `getParamValue()` made final

#### 8.7.3. Removal of classes without deprecation

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

- `ParameterBufferHelper`

- `ParameterBufferHelper.DpbParameterType`

- `ParameterBufferHelper.DpbValueType`

- `DatabaseParameterBufferExtension`

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

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

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

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

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

The following classes are no longer accessible in Jaybird 5:

- `FBUpdatableCursorFetcher` is now package private.

- `FBRowUpdater` is now package private and final.

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

- `FBRowUpdater` is now final

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

- `FBBlob` is now final

- `FBClob` is now final

- `FBCachedClob` is now final

- `FBConnectionProperties` is now final

- `FBRowId` is now final

- `FBSavePoint` is now final

- `FBTpbMapper` is now final

- `ExecutionPlanProcessor` is now final

- `BlobLengthProcessor` is now final

- `FBEscapedFunctionHelper` is now final and can no longer be instantiated

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

#### 8.7.4. Removal of constants without deprecation

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

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

- `ISCConstants`

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

  - `jaybirdMinIscDpbValue`

  - `jaybirdMaxIscDpbValue`

- `IAttachProperties.DEFAULT_PORT`

- `IAttachProperties.DEFAULT_SERVER_NAME`

- `FBBlob.SEGMENTED`

### 8.8. Removal of deprecated classes, packages and methods

#### 8.8.1. Removal of deprecated packages

The following packages have been removed in Jaybird 5:

- `org.firebirdsql.jca`; its replacement is in `org.firebirdsql.jaybird.xca`, but this API is not binary compatible and is considered internal API. See also Java Connector Architecture (JCA) support removed.

#### 8.8.2. Removal of deprecated methods

The following methods have been removed in Jaybird 5:

- `MaintenanceManager.listLimboTransactions()`, use `MaintenanceManager.limboTransactionsAsList()` or `MaintenanceManager.getLimboTransactions()` instead.

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

- `FBDatabaseMetaData.hasNoWildcards(String pattern)`

- `FBDatabaseMetaData.stripEscape(String pattern)`

- `FbStatement.getFieldDescriptor()`, use `FbStatement.getRowDescriptor()`

- `AbstractFbStatement.setFieldDescriptor(RowDescriptor fieldDescriptor)`, use `AbstractFbStatement.setRowDescriptor(RowDescriptor rowDescriptor)`

- `FBField.isType(FieldDescriptor, int)`, use `JdbcTypeConverter.isJdbcType(FieldDescriptor, int)`

- `EncodingFactory`

  - `getCharacterSetSize(int)`, use `getEncodingDefinitionByCharacterSetId(int)` and then `getMaxBytesPerChar()`

  - `getEncoding(String)`, use `getEncodingForCharsetAlias(String, Encoding)`

  - `getEncoding(Charset)`, use `getEncodingForCharset(Charset, Encoding)` or `getOrCreateEncodingForCharset(Charset)`

  - `getIscEncoding(String)`, use `getEncodingDefinitionByCharsetAlias(String)` and then `getFirebirdEncodingName()`

  - `getIscEncoding(Charset)`, use `getEncodingDefinitionByCharset(Charset)` and then `getFirebirdEncodingName()`

  - `getIscEncodingSize(String)`, use `getEncodingDefinitionByFirebirdName(String)` and then `getMaxBytesPerChar()`

  - `getJavaEncoding(String)`, use `getEncodingDefinitionByFirebirdName(String)` and then `getJavaEncodingName()`

  - `getJavaEncodingForAlias(String)`, use `getEncodingDefinitionByCharsetAlias(String)` and then `getJavaEncodingName()`

#### 8.8.3. Removal of deprecated classes

The following classes have been removed in Jaybird 5:

- `FBMissingParameterException`, exception is no longer used.

#### 8.8.4. Removal of deprecated constants

The following constants have been removed in Jaybird 5:

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

### 8.9. Removal of UDF support for JDBC escapes

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

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

- Connection property `useStandarUdf`[sic] and its alias `use_standard_udf`

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

- Constants

  - `FBConnectionProperties.USE_STANDARD_UDF_PROPERTY`

  - `DatabaseParameterBufferExtension.USE_STANDARD_UDF`

  - `ISCConstants.isc_dpb_use_standard_udf`

- Enum `EscapeParserMode` and its usages in `FBEscapedCallParser` and `FBEscapedParser`

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

### 8.10. Breaking changes internal API

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

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

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

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

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

  - `FbAttachment`

  - `FbBlob`

  - `AbstractFbStatement`

  - `AbstractFbTransaction`

  - `AbstractWireOperations`

- Class `SyncObject` has been removed

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

- `FbConnectionProperties.fromDpb(DatabaseParameterBuffer)`; there is no replacement.

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

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

- `DatatypeCoder`

  - `encodeTimestamp(Timestamp, Calendar)`— use `encodeTimestamp(Timestamp, Calendar, boolean)`

  - `encodeTimestamp(Timestamp)`— use `encodeTimestampCalendar(Timestamp, Calendar)`

  - `decodeTimestamp(Timestamp, Calendar)`— use `decodeTimestamp(Timestamp, Calendar, boolean)`

  - `decodeTimestamp(byte[]`) — use `decodeTimestampCalendar(byte[], Calendar)`

  - `encodeTime(Time)`— use `encodeTimeCalendar(Time, Calendar)`

  - `decodeTime(byte[])`— use `decodeTimeCalendar(byte[], Calendar)`

  - `encodeDate(Date)`— use `encodeDateCalendar(Date, Calendar)`

  - `decodeDate(byte[])`— use `decodeDateCalendar(byte[], Calendar)`

  - `encodeLocalTime(int, int, int, int)`— use `encodeLocalTime(LocalTime)`

  - `encodeLocalDate(int, int, int)`— use `encodeLocalDate(LocalDate)`

  - `encodeLocalDateTime(int, int, int, int, int, int, int)`— use `encodeLocalDateTime(LocalDateTime)`

- `V10Statement`

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

  - `processInfoSqlResponse(GenericResponse)`— use `GenericResponse.getData()`

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

- `StatementListener.allRowsFetched(FbStatement)`— use `afterLast(FbStatement)`

- `AbstractFbStatement`

  - `setAllRowsFetched(boolean)`— use `setAfterLast()`

  - `isAllRowsFetched()`—`isAfterLast()`

- `FbWireOperations.readSingleResponse`— use `FbWireOperations.readResponse`

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

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

- `FBDatabaseMetaData`

  - `getWantsSystemTables(String[])`— there is no replacement

  - `getWantsTables(String[])`— there is no replacement

  - `getWantsViews(String[])`— there is no replacement

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

- `FBBlob.getGdsHelper()` has been removed

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

#### 8.10.1. Additional statement state `PREPARING`

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

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

#### 8.10.2. Breaking changes internal API for 5.0.7

Bug fixes in Jaybird 5.0.7 introduced the following breaking changes in the GDS-ng API and its implementations. As this is an internal API, our policy allows breaking changes in point releases. This should only affect maintainers of Jaybird forks, or people using the internal API directly.

- `FbDatabase`

  - `createInputBlob` and `createOutputBlob` now throw `SQLException`

- `ProtocolDescriptor`

  - `createInputBlob` and `createOutputBlob` now throw `SQLException`

- `AbstractFbWireBlob` and subclasses

  - Constructors now throw `SQLException` if the provided database is null or not attached, or the provided transaction is null or not active. Previously, passing in a null transaction would result in a `NullPointerException`.

### 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 `ResultSet`s would previously return the untrimmed value through `getObject(..)`, but now return the trimmed value.

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

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

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

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

### 8.12. Breaking changes for Jaybird 6

With Jaybird 6 the following breaking changes will be introduced.

#### 8.12.1. Dropping support for Firebird 2.5

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

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

#### 8.12.2. Dropping support for Java 8 and 11

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

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

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

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

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

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

#### 8.12.4. Removal of deprecated classes, packages and methods

##### Removal of deprecated methods

The following methods will be removed in Jaybird 6:

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

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

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

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

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

  - `getBuffersNumber` and all its implementations, use `DatabaseConnectionProperties.getPageCacheSize`

  - `setBuffersNumber` and all its implementations, use `DatabaseConnectionProperties.setPageCacheSize`

- `IConnectionProperties`

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

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

- `FBSimpleDataSource.get/setBlobBufferLength`, use `get/setBlobBufferSize`

- `EventManager`

  - `get/setHost`, use `get/setServerName`

  - `get/setPort`, use `get/setPortNumber`

  - `get/setDatabase`, use `get/setDatabaseName`

- `GDSFactory.getJdbcUrl(GDSType, String)`, use `GDSFactory.getJdbcUrl(GDSType, DatabaseConnectionProperties)`

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

- `GDSHelper.getIscEncoding()`; there is no replacement

- `FirebirdConnection.getIscEncoding`; there is no replacement

##### Removal of deprecated classes

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

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

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

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

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

#### 8.12.5. Removal of deprecated constants

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 9. Compatibility notes

### 9.1. Type 2 (native) and embedded driver

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

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

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

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

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

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

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

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

1. For get the maximum segment size is actually the maximum buffer size to receive one or more segments which are prefixed with two bytes for the length