# Jaybird 5.0.1 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.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 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 (back-ported 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)

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

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

#### 5.1.1. Maven

Jaybird 5.0.1 is available on Maven Central:

groupId | `org.firebirdsql.jdbc`
artifactId | `jaybird`
version | `5.0.1.<java>` (where `<java>` 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`.

See also Type 2 (native) and embedded driver.

#### 5.1.2. Download

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

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

Please make sure to read Compatibility changes before upgrading 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`.

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.

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

See also jdp-2021-04.

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

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

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

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

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

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

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

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

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

### 7.16. Potentially breaking changes

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

See also Compatibility changes for details.

### 7.17. Other fixes and changes

- Fixed: changes to the transaction configuration (transaction parameter buffer configuration) of one connection are no longer propagated to other connections with the same connection properties (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)

### 7.18. Removal of deprecated classes and packages

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

## 8. Compatibility changes

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

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

### 8.1. Support for Java 7 dropped

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

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

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

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

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

If there turns out to be actual demand for JCA support in Jaybird after all, we will consider creating new support for JCA in a way that does not require JCA when using Jaybird as a JDBC driver. Contact us on the firebird-java 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:

- `org.firebirdsql.jca`; its replacement is in `org.firebirdsql.jaybird.xca`, but this API is not entirely 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.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.

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.

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

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