1.1 Jaybird 4.0.10

Jaybird 4.0.10 is the last release of Jaybird 4, and Jaybird 4 is now end-of-life. We recommend upgrading to Jaybird 5.

The following has been changed or fixed since Jaybird 4.0.9

• Fixed: Reconnect transaction with a transaction id exceeding 0x7FFF_FFFF did not work (jaybird#734)
• Fixed: CallableStatement.getXXX(String) could return value from wrong column — backported from Jaybird 6 (jaybird#773)
• Updated: error messages updated from Firebird 5.0.0.1272

1.2 Jaybird 4.0.9

The following has been changed or fixed since Jaybird 4.0.8

• Fixed: Some methods of FBClob threw NullPointerException when attempting to use after implicit or explicit free() (jaybird#719)
• Improvement: If the default JVM time zone is a GMT offset, e.g. GMT-08:00, configure sessionTimeZone with offset only, e.g. -08:00 (jaybird#720)
• 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 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.3 Jaybird 4.0.8

The following has been changed or fixed since Jaybird 4.0.7

• Improvement: Backported new generated keys parser from Jaybird 5 to remove dependency on ANTLR (jaybird#718)
  With this change, Jaybird no longer relies on antlr-runtime-4.7.2.jar, if you don't need it yourself, you can remove this library from the classpath. See New parser for generated keys handling for more information.

1.4 Jaybird 4.0.7

The following has been changed or fixed since Jaybird 4.0.6

• Improvement: (VAR)CHAR is now sent to the server with blr_varying2 or blr_text2 which includes the character set information (jaybird#692)
• Changed: Usages of String.toUpperCase and String.toLowerCase now use Locale.ROOT to prevent locale-sensitivity issues (jaybird#697)
• 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 backported from Jaybird 5.
• Fixed: Calling PreparedStatement.setClob or PreparedStatement.setBlob with a null Clob, Reader, Blob, or InputStream would result in a NullPointerException (jaybird#712)
  As part of this change the behaviour of setClob methods accepting a Reader was changed to be identical to setCharacterStream, and setBlob accepting an InputStream to setBinaryStream. The end result before and after this change is identical, but it can result in different memory and performance characteristics, as the stream is now consumed on execute, and not on set.

1.5 Jaybird 4.0.6

The following has been changed or fixed since Jaybird 4.0.5

• Improvement: Connection.isValid(int) now uses the timeout as a network
  timeout, if possible (jaybird#685)
  This is only supported for pure Java connections. For native connections, the timeout is ignored (and a SQLWarning is registered).
• NativeResourceUnloadWebListener would fail in Servlet containers with a NoClassDefFoundError if JNA wasn't on the classpath (jaybird#686)
• Fixed: Calling isBeforeFirst(), isAfterLast(), isFirst(), or isLast() on a closed result set resulted in a NullPointerException instead of a SQLException (jaybird#689)

1.6 Jaybird 4.0.5

The following has been changed or fixed since Jaybird 4.0.4

• Fixed: JnaService implementation call to isc_service_query incorrectly includes type (jaybird#678)
  This could lead to service requests not completing successfully for native connections.

1.7 Jaybird 4.0.4

The following has been changed or fixed since Jaybird 4.0.3

• Fixed: ResultSet.updateRow() sets fields to null in result set only (jaybird#37)
  The updateRow() method did not correctly update local data of the result set. As a result, calling getXXX for that row after the update would return null for the updated rows. The update was correctly persisted to the database.
• 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 backported from Jaybird 5.
• Fixed: Logic error could lead to incorrect logging of "Specified statement was not created by this connection" (jaybird#674)
• Changed: Updated Firebird 4.0 reserved words based on 4.0.0.2496 (jaybird#597)
• Fixed: Protocol 15 and 16 had same priority, so Firebird 4.0 might select protocol 15, leading to timeout support not available. (jaybird#676)

1.8 Jaybird 4.0.3

The following has been changed or fixed since Jaybird 4.0.2

• Changed: Closing a statement will now be sent to the server immediately (JDBC-638)
  For the v11 protocol and up (Firebird 2.1 or higher), Jaybird applied an optimization copied from Firebird to not flush 'free' packets that are used to close a cursor or close a statement. The packet will then be sent at a later time when something else is sent to the server.   Unfortunately, this has the side effect that if the statement close is the last thing to happen in a long time (e.g. the connection is idle, or returned to a pool), then the statement may retain locks on metadata objects longer than necessary, which can prevent DDL from succeeding.
  This change only affects Jaybird's implementation of the Firebird wire protocol; connections with the 'native' protocol will still delay sending the 'free' packet.

1.9 Jaybird 4.0.2

The following has been changed or fixed since Jaybird 4.0.1

• Fixed: First letter of JDBC escape was case-sensitive (JDBC-632)
  This was a regression compared to 2.2.x. Fix was also back-ported to 3.0.10.
• Fixed: Some usernames cannot authenticate using SRP (JDBC-635)
  Fix was also back-ported to 3.0.10.
• Fixed: ServiceConfigurationError while loading plugins could prevent Jaybird from loading (JDBC-636)
  Fix was also back-ported to 3.0.10.

1.10 Jaybird 4.0.1

The following has been changed or fixed since Jaybird 4.0.0

• 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 (JDBC-386)
  This change introduces a binary incompatibility as method setTransactionParameters(int, TransactionParameterBuffer) in FBManagedConnection can now throw ResourceException where previously it did not. Under the assumption that most users of Jaybird are not directly using this class, the change should not break anything.
• Fixed: Search index of Javadoc in Java 11 version used incorrect links (JDBC-619)
• Fixed: The cleanup of native resources didn't dispose the native library held by JNA, as a change in implementation no longer allowed directly access to the JNA NativeLibrary (JDBC-620)
• Fixed: When updating a row through an updatable result set, selected but not updated blob fields were set to NULL (JDBC-623)
• Added: Support for type INT128 (reported as JDBC type NUMERIC) (JDBC-624)
  See also Firebird 4 INT128 support.
• Added: A static utility method FBDriver.normalizeProperties which, given a JDBC url and a Properties object, returns a Map<String, String> containing the merged properties normalized to common property name. (JDBC-627)
  The current implementation normalizes known property names to the long-form isc_dpb name, and removes the database property. These are both implementation details that might change in future versions.
  This feature is also back-ported to Jaybird 3.0.10.
• Fixed: Use of isc_dpb_no_db_triggers no longer logs a warning (JDBC-628)
• Incompatible change: While making changes to time zone support, the API of org.firebirdsql.gds.ng.tz.TimeZoneDatatypeCoder was made almost entirely private. This should not affect normal user code.
  Although we try to avoid these types of incompatible changes in point releases, we explicitly allow them for the org.firebirdsql.gds.ng package and sub-packages.
• Changed: conversions from TIME WITH TIME ZONE now use 2020-01-01 as base date for named zones (JDBC-629)
  There are some caveats with this conversion, especially between OffsetTime and OffsetDateTime for named zones. For OffsetTime, we will always use the offset as it was on 2020-01-01, while for OffsetDateTime we will first rebase the time in the named zone to the current date, and then derive the offset.
  See also jdp-2020-06 OffsetTime derivation for named zone
• New feature: Added support for java.time.ZonedDateTime for the WITH TIME ZONE types (JDBC-630)
  To preserve named zones, we have added support for getting and setting both TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE as a ZonedDateTime.
  For TIME WITH TIME ZONE, the returned value is rebased on the current date.
• Fixed: Connection.setNetworkTimeout incorrectly used the provided Executor to set the timeout (JDBC-631)
  This caused a race condition where the timeout was possibly applied too late, and when connection.close() was called immediately after, this could trigger a NullPointerException that would bubble up into the executor.

1.11 Jaybird 4.0.0

The following has been changed or fixed since Jaybird 4.0.0-beta-2

• Changed: The 'DEC_FIXED' extended numeric precision support (for Firebird 4.0.0-beta-1) has been removed (JDBC-596)
  Now only the 'INT128' extended numeric precision (for Firebird 4.0.0-beta-2 and higher, or snapshot 4.0.0.1604 or higher) is supported.
• Changed: Updated dependency on JNA from 5.3.0 to 5.5.0 (JDBC-509)
  Make sure to replace jna-4.4.0.jar (or jna-5.3.0.jar when coming from an earlier test version of Jaybird 4) with jna-5.5.0.jar.
• New feature: Support for EXTENDED TIME(STAMP) WITH TIME ZONE types introduced in Firebird 4.0.0.1795 (JDBC-611)
  The 'extended' time zone types are a 'bind-only' data type that provides an additional offset, so an offset is also known for values using a named zone. Jaybird ignores this information and handles these types exactly the same as normal time zone types.
  See also jdp-2020-01: Extended Time Zone Types Support
• Fixed: Problem connecting to Firebird 4.0.0.1737 and higher with SQLException with message "Unexpected tag type: 3" (JDBC-612)

1.12 Jaybird 4.0.0-beta-2

The following has been changed or fixed since Jaybird 4.0.0-beta-1

• New feature: support for DatabaseMetaData.getFunctions (JDBC-552)
  See also DatabaseMetaData getFunctions implemented.
• New feature: support for DatabaseMetaData.getFunctionColumns (JDBC-552)
  See also DatabaseMetaData getFunctionColumns implemented.
• Fixed: Connection property defaultIsolation/isolation did not work through DriverManager, but only on DataSource implementations. (JDBC-584)
• Changed: Changed version numbering and naming scheme (JDBC-585)
  See Changes in artifact and library names
• Fixed: attempts to use a blob after it was freed or after transaction end could throw a NullPointerException or just work depending on whether the connection had a new transaction. (JDBC-587)
  The lifetime of a blob is now restricted to the transaction that created it, or - for blobs created using Connection.createBlob() - to the transaction that populated it. Attempts to use the blob after the transaction ends will now throw a SQLException with message "Blob is invalid. Blob was freed, or closed by transaction end." This restriction does not apply to cached blobs, see also next item.
• Fixed: Instances of java.sql.Blob and java.sql.Clob obtained from a result set were freed after calls to ResultSet.next(). (JDBC-588)
  Normal blobs will now remain valid until transaction end. You will need to call Blob.free() if you want to invalidate them earlier.
  Cached blobs (in auto-commit, holdable or scrollable result sets) will not be automatically freed at transaction end. You will need to explicitly call Blob.free() or rely on the garbage collector.
• New feature: Support for Connection.setNetworkTimeout and getNetworkTimeout (JDBC-589)
  This JDBC feature is only supported on pure Java connections, not in native or embedded. Calling setNetworkTimeout will override the timeout set with the soTimeout connection property. When a timeout occurs, the connection will be closed.
• Changed: Procedures in packages are no longer returned from DatabaseMetaData.getProcedures and getProcedureColumns (JDBC-590)
  See also Excluding procedures from packages.
• Changed: On Firebird 4 and higher, precision of FLOAT and DOUBLE PRECISION are reported using binary precision (24 and 53 respectively), instead of decimal precision (7 and 15 respectively) (JBC-591)
  See also Precision reported for FLOAT and DOUBLE PRECISION on Firebird 4.
• Improvement: added binary literal prefix (x') and suffix (') to DatabaseMetaData.getTypeInfo for LONGVARBINARY, VARBINARY and BINARY (JDBC-593)
• New feature: added FBEventManager.createFor(Connection) to create an EventManager for an existing connection. Back-ported to Jaybird 3.0.7. (JDBC-594)
  The created event manager does not allow setting properties (other than waitTimeout). It is still required to use connect() and disconnect(), to start respectively stop listening for events.
  Due to implementation limitations, the lifetime is tied to the physical connection. When using a connection pool, this means that the event manager works as long as the physical pooled connection remains open, which can be (significantly) longer than the logical connection used to create the event manager.
  This feature was contributed by Vasiliy Yashkov.
• Changed: Firebird 4.0.0.1604 and later changed the format of extended numeric precision from a Decimal128 to an Int128, increasing the maximum decimal precision from 34 to 38. The Int128 format is now supported. (JDBC-595)
  Support for the old format will be removed after Jaybird 4.0.0-beta-2. See also Firebird 4 extended numeric precision support.
• New experimental feature: A way to monitor driver operations (specifically statement executes and fetches). (JDBC-597)
  See Operation monitoring for details.
  This feature was contributed by Vasiliy Yashkov.
• Fixed: On Firebird 3 and 4 with WireCrypt = Enabled, the connection could hang or throw exceptions like "Unsupported or unexpected operation code". (JDBC-599)
  The implementation could read wrong data, followed by either a read blocked waiting for more data or an exception.
  The underlying problem was how buffer padding was skipped using InputStream.skip, which in CipherInputStream never skips beyond its current buffer. If that buffer was at (or 1 or 2 bytes from) the end, Jaybird was reading less bytes than it should. This caused subsequent reads to read wrong data, reading too little or too much data.
• New feature: Support for the v15 protocol (Firebird 3.0.2 and higher). (JDBC-601)
  The v15 protocol supports database encryption key callbacks during the authentication phase, supporting encrypted security databases. We decided to implement the v14 changes only as part of the v15 implementation.
  See also Database encryption support.
• New feature: Jaybird now supports UTF-8 URL encoding for connection properties in the JDBC url. (JDBC-604)
  This introduce a minor incompatibility, see also URL encoding in query part of JDBC URL.
  This feature was back-ported to Jaybird 3.0.9.
• New feature: Firebird 4 data type bind configuration support (JDBC-603)
  This change also removes the timeZoneBind and decfloatBind connection properties. This feature requires Firebird 4 beta 2 or snapshot Firebird 4.0.0.1683 or higher.
  See also Firebird 4 data type bind configuration support.
  This feature was partially back-ported to Jaybird 3.0.9.
• New feature: Support for statement timeouts through java.sql.Statement.setQueryTimeout for the v16 protocol (Firebird 4 and higher) (JDBC-602)
  See also Firebird 4 statement timeout support.
• New feature: Support for zlib wire compression in the pure Java wire protocol implementation (Firebird 3 and higher) (JDBC-606)
  See also Wire compression support.
• New feature: Support for JDBC escape DAYNAME, will always return day names in English (JDBC-607)
• New feature: Support for JDBC escape MONTHNAME, will always return month names in English (JDBC-608)
• New feature: Support for JDBC escape DATABASE (JDBC-609)

4.1 About this version

Jaybird 4 is - compared to Jaybird 3 - an incremental release that builds on the foundations of Jaybird 3. The focus of this release has been on further improving JDBC support and adding support for the new data types and features of Firebird 4.

The main new features are:

• Wire encryption support (back-ported to Jaybird 3.0.4)
• Database encryption support (back-ported to Jaybird 3.0.4)
• Wire compression support
• Authentication plugin improvements
• Firebird 4 data type bind configuration support (since Jaybird 4.0.0-beta-2)
• Firebird 4 DECFLOAT support
• Firebird 4 extended numeric precision support
• Firebird 4 time zone support
• Firebird 4 statement timeout support (since Jaybird 4.0.0-beta-2)
• JDBC RowId support
• DatabaseMetaData getPseudoColumns implemented
• DatabaseMetaData getVersionColumns implemented
• DatabaseMetaData getFunctions implemented (since Jaybird 4.0.0-beta-2)
• DatabaseMetaData getFunctionColumns implemented (since Jaybird 4.0.0-beta-2)
• Improved JDBC function escape support
• New JDBC protocol prefix jdbc:firebird:
• URL encoding in query part of JDBC URL (back-ported to Jaybird 3.0.9)
• Generated keys support improvements
• Operation monitoring

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

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

4.2 Supported Firebird versions

Jaybird 4.0.10 was tested against Firebird 2.5.9, 3.0.11, and 4.0.4, and a recent snapshot of Firebird 5.0, but should also support other Firebird versions from 2.5 and up.

Formal support for Firebird 2.0 and 2.1 has been dropped (although in general we expect the driver to work). The Type 2 and embedded server JDBC drivers use JNA to access the Firebird client or embedded library.

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 4 supports Java 7 (JDBC 4.1), 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 7, 8, 11, 17, and 21¹.

Jaybird 4 provides libraries for Java 7, Java 8 and Java 11. The Java 8 builds have the same source and all JDBC 4.3 related functionality as the Java 11 build and can be used on Java 9 and higher as well.

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

See als Java support in What's new in Jaybird 4.

4.4 Specification support

Jaybird supports the following specifications:

5.1 Jaybird 4.0.10

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird</artifactId>
    <version>4.0.10.java8</version>
</dependency>

<dependency>
    <groupId>org.firebirdsql.jdbc</groupId>
    <artifactId>jaybird</artifactId>
    <version>4.0.10.java8</version>
    <exclusions>
        <exclusion>
            <groupId>javax.resource</groupId>
            <artifactId>connector-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>javax.resource</groupId>
    <artifactId>connector-api</artifactId>
    <version>1.5</version>
    <scope>provided</scope>
</dependency>

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

6.1 Maven

Change the artifact id from jaybird-jdkXX to jaybird, and change the version of the dependency to 4.0.10.javaXX (where XX is your Java version, 7 for Java 7, 8 for Java 8 and 11 for Java 11). If you use native or embedded verify that you upgrade JNA (net.java.dev.jna:jna) from 4.4.0 to 5.5.0.

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

6.2 Manual install

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

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

   • jaybird-3.0.x.jar with jaybird-4.0.10.javaXX.jar (where XX is 7, 8 or 11)
   • jaybird-full-3.0.x.jar with jaybird-full-4.0.10.javaXX.jar

2. If installed, remove antlr-runtime-4.7.jar or antlr-runtime-4.7.2.jar (unless of course your application itself needs these libraries). Since Jaybird 4.0.8, Jaybird no longer relies on ANTLR.

3. If installed, remove jna-4.4.0.jar and replace it with jna-5.5.0.jar. This library is only necessary for native, local or embedded connections. If you use pure-java connections (the default), you don't need JNA.

6.3 Gotchas

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.1 Changes in artifact and library names

Historically, the naming of Jaybird artifacts and libraries has been a bit inconsistent. With the rapid release cycle of Java, naming collisions are imminent with the old naming convention. For example, the Maven artifact jaybird-jdk15 was used for Java 1.5 and with this naming convention, this would be reused for Java 15.

Forced by this issue, we have overhauled the naming convention entirely to bring more consistency between Maven artifacts and the Jaybird zip distribution. The full naming convention is documented in jdp-2019-04: Version Number and Naming Scheme.

This new naming convention has been changed compared to the one from Jaybird 4.0.0-beta-1.

This new naming convention has the following effects:

• The targeted Java version is no longer part of the Maven artifact id. The artifact id is now jaybird for all Java versions. We provide a relocation artifact for jaybird-jdk17 and jaybird-jdk18 for backwards compatibility.
• The targeted Java version is now part of the version (eg 4.0.0.java11)
• Names of libraries in the distribution zip are now consistent with the Maven naming convention

As a result of these new naming conventions, the following has been changed:

• Maven artifact: jaybird (for all Java versions) (was jaybird-jdk18)
• Maven version: 4.0.0.java8 (was 3.0.5)
• Distribution zip: jaybird-4.0.0.java8.zip (was Jaybird-3.0.5_JDK1.8.zip)
• Jaybird: jaybird-4.0.0.java8.jar (was jaybird-3.0.5.jar in zip distribution)
• Jaybird (full): jaybird-full-4.0.0.java8.jar (was jaybird-full-3.0.5.jar)
• Jaybird sources: jaybird-4.0.0.java8-sources.jar (was jaybird-3.0.5-sources.jar in zip distribution)
• Jaybird javadoc: jaybird-4.0.0.java8-javadoc.jar (was jaybird-3.0.5-javadoc.jar in zip distribution)

Furthermore, the client name reported to Firebird 2.5 and higher has been changed from Jaybird 3.0.5-JDK_1.8 to Jaybird jaybird-4.0.0.java8

7.2 Java support

7.3 Firebird support

Support for Firebird 2.0 and 2.1 has been dropped. See Firebird 2.0 and 2.1 no longer supported for details.

Firebird versions 2.5, 3.0 and 4.0 are supported.

7.4 Wire encryption support

Jaybird 4 adds support for the Firebird 3 ARC4 wire encryption. This feature has been back-ported to Jaybird 3.0.4. The encryption is configured using the connection property wireCrypt, with the following (case-insensitive) values:

• DEFAULT: default (value used when wireCrypt is not specified; you'd normally not specify this explicitly)
• ENABLED: enable, but not require, wire encryption
• REQUIRED: require wire encryption (only if Firebird version is 3.0 or higher)
• DISABLED: disable wire encryption

The default value acts as ENABLED for pure Java connections, for JNA (native) connections this wil use the fbclient default (either Enabled or the configured value of WireCrypt from a firebird.conf read by the native library).

Connection property wireCrypt=REQUIRED will not reject unencrypted connections when connecting to Firebird 2.5 or lower. This behavior matches the Firebird 3 client library behavior. The value will also be ignored when using native connections with a Firebird 2.5 client library.

Using wireCrypt=DISABLED when Firebird 3 or higher uses setting WireCrypt = Required (or vice versa) will yield error "Incompatible wire encryption levels requested on client and server" (error: isc_wirecrypt_incompatible / 335545064).

The same error is raised when connecting to Firebird 3 and higher with a legacy authentication user with connection property wireCrypt=REQUIRED.

Alternative wire encryption plugins are currently not supported, although we made some preparations to support this. If you want to develop such a plugin, contact us on the Firebird-Java mailing list so we can work out the details of adding plugin support.

The new ChaCha and ChaCha64 wire encryption introduced in Firebird 4 is not yet supported.

WARNING

The implementation comes with a number of caveats:

• we cannot guarantee that the session key cannot be obtained by someone with access to your application or the machine hosting your application (although that in itself would already imply a severe security breach)
• the ARC4 encryption - the default provided by Firebird - is considered to be a weak (maybe even broken) cipher these days
• the encryption cipher uses ARCFOUR with a 160 bits key, this means that the unlimited Cryptographic Jurisdiction Policy needs to be used (or at minimum a custom policy that allows ARCFOUR with 160 bits keys). See also FAQ entry Encryption key did not meet algorithm requirements of Symmetric/Arc4 (337248282)

7.5 Database encryption support

Jaybird 4 (and 3.0.4) adds support for Firebird 3 database encryption callbacks in the pure Java implementation of the version 13 protocol. This feature was sponsored by IBPhoenix.

In addition, version 15 of the protocol (Firebird 3.0.2 and higher) was also implemented, supporting encryption callbacks during authentication for use with encrypted security databases.

The current implementation is simple and only supports replying with a static value from a connection property. Be aware that a static value response for database encryption is not very secure as it can easily lead to replay attacks or unintended key exposure.

Future versions of Jaybird may introduce plugin support for database encryption plugins that require a more complex callback.

The static response value of the encryption callback can be set through the dbCryptConfig connection property. DataSource and ServiceManager implementations have an equivalent property with the same name. This property can be set as follows:

• Absent or empty value: empty response to callback (depending on the database encryption plugin this may just work or yield an error later).
• Strings prefixed with base64:: rest of the string is decoded as base64 to bytes. The = padding characters are optional, but when present they must be valid (that is: if you use padding, you must use the right number of padding characters for the length).
  When the base64 encoded value contains +, it must be escaped as %2B in the JDBC URL. For backwards compatibility with Jaybird 3, we can't switch to the URL-safe variant of base64.
• Plain string value: string is encoded to bytes using UTF-8, and these bytes are used as the response. Avoid use of : in the plain string value.

Because of the limitation of connection URL parsing, we strongly suggest avoiding plain string values with & or ;. Likewise, avoid : so that we can support other prefixes similar to base64: in the future. If you need these characters, consider using a base64 encoded value instead, or ensure these characters are URL encoded: &: %26, ;: %3B, :: %3A, %: %25, +: %2B.

For service operations, as implemented in the org.firebirdsql.management package, Firebird requires the KeyHolderPlugin configuration to be globally defined in firebird.conf. Database-specific configuration in databases.conf will be ignored for service operations. Be aware that some service operations on encrypted databases are not supported by Firebird 3 (eg gstat equivalents other than gstat -h or gstat -e).

Other warnings and limitations

• Database encryption callback support is only available in the pure Java implementation. Support for native and embedded connections may be added in a future version.
• The database encryption callback does not require an encrypted connection, so the key can be exchanged unencrypted if wire protocol encryption has been disabled client-side or server-side, or if legacy authentication is used. Consider setting connection property wireCrypt=REQUIRED to force encryption (caveat: see the next point).
• Firebird may ask for the database encryption key before the connection has been encrypted (for example if the encrypted database itself is used as the security database). This applies to v15 and higher protocol support.
• We cannot guarantee that the dbCryptConfig value cannot be obtained by someone with access to your application or the machine hosting your application (although that in itself would already imply a severe security breach).

7.6 Wire compression support

Support for zlib wire compression was added in the pure Java wire protocol. Compression can be enabled using boolean connection property wireCompression.

The connection property only affects the pure Java wire protocol connections on Firebird 3 and higher, if the server has the zlib library. Native connections will follow the WireCompression configuration in the firebird.conf read by the client library, if the zlib library is on the search path.

Compression is currently disabled by default. We may change this in future versions of Jaybird to be enabled by default.

The wireCompression property is also available on data sources and the management classes in org.firebirdsql.management.

7.7 Authentication plugin improvements

Jaybird 4 has added support for the new SrpNNN (with NNN is 224, 256, 384 and 512) authentication plugins added in Firebird 4 (back-ported to Firebird 3.0.4 for Srp256 only).

The original Srp plugin uses SHA-1, the new Srp-variants use SHA-224, SHA-256, SHA-384 and SHA-512 respectively³.

Be aware, support for these plugins depends on support of these hash algorithms in the JVM. For example, SHA-224 is not supported in Oracle Java 7 by default and may require additional JCE libraries.

7.8 Firebird 4 data type bind configuration support

Firebird 4 (build 4.0.0.1683 or later) introduced the SET BIND statement and isc_dpb_set_bind DPB item. This allows you to define data type conversion rules for compatibility or ease of processing data.

This feature is specifically necessary for using the WITH TIME ZONE types under Java 7. See also Time zone bind configuration.

In Jaybird this feature is exposed as connection property dataTypeBind (alias set_bind). The value of this connection property is a semicolon-separated list of data type bind definitions.

A data type bind definition is of the form <from-type> TO <to-type>. A definition is the same as the second half of a SET BIND statement after the OF. See the Firebird documentation of SET BIND for more information. Invalid values or impossible mappings will result in an error on connect.

When using the dataTypeBind connection property in a JDBC URL, the semicolons of the list need to be encoded as %3B, as semicolons in the JDBC URL are an alternative to & as the separator between properties.

For example:

String jdbcUrl = "jdbc:firebirdsql://localhost/database?charSet=utf-8"
        + "&dataTypeBind=decfloat to varchar%3Btimestamp with time zone to legacy

When the property is set through a Properties object or a DataSource configuration, encoding the semicolon is not necessary and will result in errors.

For example:

Properties props = new Properties();
props.setProperty("dataTypeBind", 
        "decfloat to varchar;timestamp with time zone to legacy"

Values set through this connection property will be the session default configuration, which means that they are retained (or reverted to) when executing ALTER SESSION RESET.

This feature replaces the connection properties timeZoneBind and decfloatBind from earlier Jaybird 4 beta or snapshot versions. The timeZoneBind and decfloatBind properties are no longer supported.

7.9 Firebird 4 DECFLOAT support

Firebird 4 introduces the SQL:2016 DECFLOAT datatype, a decimal floating point with a precision of 16 or 34 digits (backed by an IEEE-754 Decimal64 or Decimal128). See the Firebird 4 release notes for details on this datatype.

Jaybird 4 adds support for this datatype. The 'default' object type for DECFLOAT is a java.math.BigDecimal, but conversion from and to the following datatypes is supported:

• java.math.BigDecimal (see note 1)
• byte (valid range -128 to 127(!); see notes 2, 3)
• short (valid range -32768 to 32767; see note 3)
• int (valid range -2³¹ to 2³¹-1; see note 3)
• long (valid range -2⁶³ to 2⁶³-1; see notes 3, 4)
• float (valid range -1 * Float.MAX_VALUE to Float.MAX_VALUE; see notes 5-9)
• double (valid range -1 * Double.MAX_VALUE to Double.MAX_VALUE; see notes 6-9)
• boolean (see notes 10, 11)
• java.lang.String (see notes 12-14)
• java.math.BigInteger (see notes 15, 16)
• org.firebirdsql.extern.decimal.Decimal32/64/128 (see notes 17, 18)

The DECFLOAT type is not yet defined in the JDBC specification. For the time being, we have defined a Jaybird specific type code with value -6001. This value is available through constant org.firebirdsql.jdbc.JaybirdTypeCodes.DECFLOAT, or - for JDBC 4.2 and higher - org.firebirdsql.jdbc.JaybirdType.DECFLOAT, which is an enum implementing java.sql.SQLType.

If you need to use the type code, we suggest you use these constants. If a DECFLOAT type constant gets added to the JDBC standard, we will update the value. The enum value will be deprecated when that version of JDBC has been released.

Jaybird uses a local copy of the FirebirdSQL/decimal-java library, with a custom package org.firebirdsql.extern.decimal. This to avoid additional dependencies.

7.10 Firebird 4 extended numeric precision support

Added support for the extended precision for NUMERIC and DECIMAL introduced in Firebird 4, increasing the maximum precision to 38. In the implementation in Firebird, this extended precision is backed by an Int128.

Any NUMERIC or DECIMAL with a precision between 19 and 38 will allow storage up to a precision of 38 (technically even 39, but not full range).

Values set on a field or parameter will be rounded to the target scale of the field using RoundingMode.HALF_UP. Values exceeding that do not fit in an Int128 after rounding will be rejected with a TypeConversionException.

7.11 Firebird 4 INT128 support

Since: Jaybird 4.0.1

After Firebird 4 beta 2 (in build 4.0.0.2076), the Int128 type used to back the extended precision numerics was exposed as SQL type INT128. As JDBC does not provide this type, we map it to JDBC type NUMERIC, with a reported precision of 38 and a scale of 0.

We think this mapping will offer the best support in tool and libraries. For further details, see jdp-2020-08 Int128 support

7.12 Firebird 4 time zone support

Added support for the Firebird 4 TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE types. See the Firebird 4 release notes and doc/sql.extensions/README.time_zone.md in the Firebird installation for details on these types.

The time zone types are supported under Java 8 and higher, using the Java 8 (or higher) version of Jaybird.

Time zone types are not supported under Java 7, you will need to enable legacy time zone bind. With legacy time zone bind, Firebird will convert to the equivalent TIME and TIMESTAMP (WITHOUT TIME ZONE) types using the session time zone. Time zone bind can be configured with connection property dataTypeBind, for more information see Time zone bind configuration.

See also jdp-2019-03: Time Zone Support

Properties props = new Properties();
props.setProperty("dataTypeBind", "time zone to legacy");

7.13 Firebird 4 statement timeout support

Support was added for Firebird 4 statement timeouts through java.sql.setQueryTimeout. On Firebird 3 and earlier or a native connection with a Firebird 3 or earlier client library, the timeout is silently ignored.

This implementation supports a maximum timeout of 4294967 seconds. Larger values will be handled as if 0 (unlimited) was set. Firebird also has attachment level and global statement timeouts. This configuration governs the statement level statement timeout only. In practice, a more stringent timeout might be applied by this attachment level or global statement timeout.

Important: Query timeouts in Firebird 4 and higher have an important caveat: for result set producing statements, the timeout covers the time from execution start until the cursor is closed. This includes the time that Firebird waits for the application to fetch more rows. This means that if you execute a SELECT and take your time processing the results, the statement may be cancelled even when Firebird itself returns rows quickly.

See Firebird 4 release notes and documentation for more information.

7.14 JDBC RowId support

Columns of type RDB$DB_KEY are now identified as java.sql.Types.ROWID, and getObject on these columns will now return a java.sql.RowId.

The getObject(int/String, Class) methods support retrieval as java.sql.RowId and org.firebirdsql.jdbc.FBRowId; the object returned is the same type (org.firebirdsql.jdbc.FBRowId) in both cases.

Updating row ids is not possible, so attempts to call updateRowId or updateObject on a RDB$DB_KEY in an updatable result set will throw an SQLFeatureNotSupportedException.

Unfortunately, this support does not extend to parameters, as parameters (e.g. in where RDB$DB_KEY = ?) cannot be distinguished from parameters of a normal binary field (char character set octets). To address this, binary fields now also accept values of type java.sql.RowId on setRowId and setObject.

Support has also been added to DatabaseMetaData:

• getBestRowIdentifier returns RDB$DB_KEY if there is no primary key (existing functionality)
• getRowIdLifetime now returns RowIdLifetime.ROWID_VALID_TRANSACTION (even if dbkey_scope=1 has been specified!)
• getPseudoColumns now returns RDB$DB_KEY

Other database metadata (eg getColumns) will not list the RDB$DB_KEY column, as it is a pseudo-column.

In result sets, Jaybird will now also automatically map request for columns by name RDB$DB_KEY (case-insensitive) to DB_KEY as Firebird automatically applies this alias for the RDB$DB_KEY column(s) in a select-list.

Be aware that result set metadata will still report DB_KEY as the column name and label.

7.15 DatabaseMetaData getPseudoColumns implemented

The DatabaseMetaData.getPseudoColumns method (introduced in JDBC 4.1) has now been implemented.

The JDBC API specifies this method as:

Retrieves a description of the pseudo or hidden columns available in a given table within the specified catalog and schema. Pseudo or hidden columns may not always be stored within a table and are not visible in a ResultSet unless they are specified in the query's outermost SELECT list. Pseudo or hidden columns may not necessarily be able to be modified. If there are no pseudo or hidden columns, an empty ResultSet is returned.

For Firebird 2.5 and earlier it will only report on RDB$DB_KEY, for Firebird 3 and higher it will also report on RDB$RECORD_VERSION.

The pseudo-column RDB$RECORD_VERSION was introduced in Firebird 3, its value is the transaction that last updated the row.

7.16 DatabaseMetaData getVersionColumns implemented

The DatabaseMetaData.getVersionColumns method has now been implemented.

The JDBC API specifies this method as:

Retrieves a description of a table's columns that are automatically updated when any value in a row is updated. They are unordered.

For Firebird 2.5 and earlier it will only report on RDB$DB_KEY, for Firebird 3 and higher it will also report on RDB$RECORD_VERSION.

The pseudo-column RDB$RECORD_VERSION was introduced in Firebird 3, its value is the transaction that last updated the row.

Jaybird only returns pseudo-column as version columns, so 'last updated' columns updated by a trigger, calculated columns, or other forms of change tracking are not reported by this method.

7.17 DatabaseMetaData getFunctions implemented

The DatabaseMetaData.getFunctions method has now been implemented.

The JDBC API specifies this method as:

Retrieves a description of the system and user functions available in the given catalog.

The implementation only returns functions that are available from the RDB$FUNCTIONS table. This means that the built-in functions are not included in the result of this method.

For Firebird 3 and higher, the result includes native UDF, PSQL and UDR functions. The result does not include functions defined in packages as JDBC does not provide support for packages.

Jaybird provides additional columns with Firebird specific information. As these columns are not defined by JDBC, they may change position when JDBC adds new columns. We recommend retrieving these columns by name.

The additional columns are:

• JB_FUNCTION_SOURCE - Source of Firebird 3+ PSQL function, this is the part after the AS clause.
• JB_FUNCTION_KIND - Kind of function, one of "UDF", "PSQL" (Firebird 3+) or "UDR" (Firebird 3+)
• JB_MODULE_NAME - Value of RDB$MODULE_NAME, is null for PSQL functions
• JB_ENTRYPOINT - Value of RDB$ENTRYPOINT, is null for PSQL functions
• JB_ENGINE_NAME - Value of RDB$ENGINE_NAME, is null for UDF and PSQL functions

7.18 DatabaseMetaData getFunctionColumns implemented

The DatabaseMetaData.getFunctionColumns method has now been implemented.

The JDBC API specifies this method as:

Retrieves a description of the given catalog's system or user function parameters and return type.

The implementation only returns columns of functions that are available from the RDB$FUNCTIONS table. This means that the built-in functions are not included in the result of this method.

For Firebird 3 and higher, the result includes native UDF, PSQL and UDR functions. The result does not include functions defined in packages as JDBC does not provide support for packages.

Where Firebird provides no column name, Jaybird generates one by combining the string PARAM_ with the value of RDB$ARGUMENT_POSITION. Names are not available for the parameters of legacy UDF functions, and for the return value of any function.

7.19 Improved JDBC function escape support

Revised support for JDBC function escapes with optional parameters, and added support for a number of previously unsupported functions or options.

If you only target Firebird, then we suggest you do not use JDBC function escapes.

7.20 New JDBC protocol prefix jdbc:firebird:

Historically, the JDBC protocols supported by Jaybird have used the prefix jdbc:firebirdsql:. We have now added support for jdbc:firebird: as an alternative prefix. This prefix was previously only supported in the OpenOffice.org/LibreOffice pure Java variant.

Jaybird now supports the following URL prefixes (or JDBC protocols):

• Pure Java
  • jdbc:firebirdsql:
  • jdbc:firebirdsql:java
  • jdbc:firebird: (new)
  • jdbc:firebird:java: (new)
• Native
  • jdbc:firebirdsql:native:
  • jdbc:firebird:native: (new)
• Embedded
  • jdbc:firebirdsql:embedded:
  • jdbc:firebird:embedded: (new)
• Local
  • jdbc:firebirdsql:local:
  • jdbc:firebird:local: (new)
• OpenOffice.org/LibreOffice pure Java variant
  • jdbc:firebird:oo:
  • jdbc:firebirdsql:oo:

7.21 URL encoding in query part of JDBC URL

Jaybird now supports UTF-8 URL encoded values (and keys) in the query part of the JDBC URL.

As a result of this change, the following previously unsupported characters can be used in a connection property value when escaped:

• ; escaped as %3B
• & escaped as %26

URL encoding can also be used to encode any unicode character in the query string. Jaybird will always use UTF-8 for decoding.

This change introduces the following backwards incompatibilities:

• + in the query part now means space (0x20), so occurrences of + (plus) need to be escaped as %2B; make sure to do this for base64 encoded values of dbCryptConfig
• % in the query part now introduces an escape, so occurrences of % (percent) need to be escaped as %25

Invalid URL encoded values will now throw a SQLNonTransientConnectionException.

The reason for this change is that the new dataTypeBind connection property requires semicolon-separated values, but Jaybird supports semicolon-separated key/value connection properties in the query part. To be able to support this new property in the connection string, we had to introduce URL encoding.

This change only applies to the JDBC URL part after the first ?. This change does not apply to connection properties set through java.util.Properties or on a javax.sql.DataSource.

7.22 Generated keys support improvements

Support for generated keys generation was improved with the following changes.

7.23 Operation monitoring

Experimental feature

Operation monitoring is an experimental feature that allows an application to monitor and - in a limited fashion - control driver operations. This feature is exposed as the interfaces org.firebirdsql.gds.ng.monitor.OperationAware and org.firebirdsql.gds.ng.monitor.Operation.

An application can implement OperationAware and register it through org.firebirdsql.gds.ng.OperationMonitor.initOperationAware(OperationAware). When a SecurityManager is active, registering an OperationAware will require the SQLPermission with name org.firebirdsql.jaybird.initOperationAware. Only one instance can be registered at a time. Setting null will clear the current instance.

Once registered, the OperationAware instance will be notified of operation start and end through the methods startOperation(Operation) and endOperation(Operation). These methods are called on the thread performing the operation, so implementations must complete these methods as soon as possible to prevent performance problems in the driver.

The Operation instance exposes the type of operation through getType() and allows the operation to be cancelled. Cancellation is only possible as long as the operation is active. Attempting to cancel when the operation is complete will throw an SQLException.

This feature is experimental and its API may be removed or changed, and operation types may be added or removed in point releases.

See also jdp-2019-06: Ability to monitor driver operations

This feature was contributed by Vasiliy Yashkov.

7.24 New parser for generated keys handling

Added in Jaybird 4.0.8, backported from Jaybird 5.

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 backport was prompted by the fact that Jaybird 4 still used ANTLR 4.7.2, while ANTLR 4.10 has introduced a backwards incompatible change, which, for example, causes problems when using Jaybird with Hibernate 6. Instead of upgrading ANTLR, we decided that replacing the parser was less invasive as it was less likely to introduce compatibility issues for users depending on older versions of ANTLR.

7.25 Potentially breaking changes

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

See also Compatibility changes for details.

7.26 Other fixes and changes

• The distribution zip no longer includes the jaybird-4.0.10.javaXX.rar. This file was an example JCA Resource Archive.

  JCA support will be removed entirely in Jaybird 5. See also Dropping JCA support.

• Added support for Firebird 4 page size 32768 (32KB) in FBManager and backup managers (back-ported to Jaybird 3.0.5) (JDBC-468)

• Changed: The value returned by ResultSetMetaData.getColumnDisplaySize was revised for REAL/FLOAT and DOUBLE PRECISION to take scientific notation into account (JDBC-514)

• Fixed: Database metadata pattern parameters now allow the pattern escape character (\) to occur unescaped, this means that patterns A\B and A\\B will both match a value of A\B. This complies with the (undocumented) JDBC expectation that patterns follow the ODBC requirements for pattern value arguments (JDBC-562)

• Upgraded antlr-runtime used for generated keys support from 4.7 to 4.7.2.

  The grammar generated for version 4.7.2 should still run on 4.7, but we suggest that you upgrade this dependency.

• Improvement: Added FBManager.setDefaultCharacterSet to set default database character set during database creation (JDBC-541)

• New Feature: Support for Firebird 3 'explained' (detailed) execution plan (JDBC-574)

  Adds FirebirdStatement.getLastExplainedExecutionPlan(), FirebirdPreparedStatement.getExplainedExecutionPlan(), and Firebird ResultSet.getExplainedExecutionPlan().

  This feature was contributed by Vasiliy Yashkov.

• Upgraded jna library used for native/embedded from 4.4 to 5.5 (JDBC-509

  The pull request to upgrade (from 4.4 to 5.2) was contributed by Julien Nabet.

• Native libraries will now be disposed on application exit (JDBC-519)

  On JVM exit or - if deployed inside a WAR - servlet context destroy (tested on Tomcat), Jaybird will call fb_shutdown on any loaded native libraries and dispose the JNA handle to the native library. This should prevent crashes (e.g. access violation / 0xc0000005 error on Windows) on library unload if there were still embedded connections open.

  Given the potential for bugs or timing issues with this feature, it can be disabled with system property org.firebirdsql.nativeResourceShutdownDisabled set to true. This property must be set before Jaybird is loaded, preferably on the Java command line.

7.27 Removal of deprecated classes and packages

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

8.1 Firebird 2.0 and 2.1 no longer supported

Support for Firebird 2.0 and 2.1 has been dropped in Jaybird 4. In general, we expect the driver to remain functional, but chances are certain metadata (eg DatabaseMetaData) will break if we use features introduced in newer versions.

In general, we will no longer fix issues that only occur with Firebird 2.1 or earlier.

As a result of changes in FBDatabaseMetaData, most result set producing methods will no longer work with Firebird 1.5 or earlier (unsupported since Jaybird 3).

8.2 Removed Legacy_Auth from default authentication plugins

The pure Java protocol in Jaybird will - by default - no longer try the Legacy_Auth plugin when connecting to Firebird 3 or higher.

See Default authentication plugins for more information.

8.3 Time zone behaviour

Using Jaybird 4 with Firebird 4 on a machine with a different time zone than the JVM, values of CURRENT_TIMESTAMP, LOCALTIMESTAMP, CURRENT_TIME and LOCALTIME will result in different values compared to Jaybird 4 with Firebird 3 (or Jaybird 3 or earlier with Firebird 4). This is caused by Jaybird 4 setting the session time zone to the JVM default time zone. As a result values will be in the time zone of the JVM and not the Firebird server time zone.

To revert to the previous behaviour, explicitly set sessionTimeZone=server. See Connection property sessionTimeZone for more information.

8.4 RDB$DB_KEY columns no longer of Types.BINARY

With the introduction of JDBC RowId support, RDB$DB_KEY columns are no longer identified as java.sql.Types.BINARY, but as java.sql.Types.ROWID. The column will behave in a backwards-compatible manner as a binary field, except getObject, which will return a java.sql.RowId instead.

Unfortunately this does not apply to parameters, see also JDBC RowId support.

Due to the method of identification, real columns of type char character set octets with the name DB_KEY will also be identified as a ROWID column.

8.5 DatabaseMetaData.getBestRowIdentifier scope handling

Previously, the Jaybird implementation of DatabaseMetaData.getBestRowIdentifier used the scope parameter to populate the SCOPE column of its result set, instead of using it to filter on the required scope.

This has been changed to instead filter on scope. In this implementation, the columns of the primary key are considered the best row identifier, with scope bestRowSession. It will be returned for all values of scope.

If a table does not have a primary key, the RDB$DB_KEY is considered the second-best alternative, with scope bestRowTransaction. It will only be returned for scopes bestRowTemporary and bestRowTransaction. See also JDBC RowId support.

If you are currently using DatabaseMetaData.getBestRowIdentifier with scope value DatabaseMetaData.bestRowSession, consider if you need to use bestRowTransaction instead.

If you are relying on the SCOPE column containing the value for the requested scope, change your logic to remove that dependency.

8.6 Precision reported for FLOAT and DOUBLE PRECISION on Firebird 4

Firebird 4 introduced support for SQL standard FLOAT(p) with 1 <= p <= 24 a synonym of FLOAT, and 25 <= p <= 53 as synonym of DOUBLE PRECISION. This precision is expressed in binary digits (or radix 2).

To bring the metadata reported by Jaybird in line for this change, on Firebird 4 and higher, we now report the precision for FLOAT and DOUBLE PRECISION in binary digits instead of decimal digits.

For example for FLOAT precision, on Firebird 3 and lower Jaybird 4 returns 7, and 24 on Firebird 4 and higher. For DOUBLE PRECISION precision, on Firebird 3 and lower Jaybird 4 returns 15, and 53 on Firebird 4 and higher. In addition, the radix reported in the metadata for these types will be 2 instead of 10 on Firebird 4 and higher.

This change affects

• DatabaseMetaData.getColumns (columns COLUMN_SIZE and NUM_PREC_RADIX),
• DatabaseMetaData.getProcedureColumns (columns PRECISION and RADIX),
• DatabaseMetaData.getTypeInfo (columns PRECISION and NUM_PREC_RADIX),
• ParameterMetaData.getPrecison,
• ResultSetMetaData.getPrecision.

8.7 Incompatibilities due to URL encoding in JDBC URL query part

With the introduction of URL encoding for the query part of the JDBC URL, the use of characters + and % in the query part of a JDBC URL now have different meaning and can lead to errors or unexpected results. This is especially relevant for base64 encoded values of dbCryptConfig.

See URL encoding in query part of JDBC URL for more information.

8.8 Stricter JDBC compliance

In Jaybird 4 a number of changes were made for stricter compliance to the JDBC specification.

8.9 Removal of character mapping

Character mapping has been removed. Character mapping (also known as translation) was a feature that allowed to remap certain characters when encoding/decoding strings. This could be used to address incompatibilities or incorrect mappings in the character set implementation of certain platforms (apparently HPUX was affected).

If you do need this feature, then you will need to use a custom encoding implementation.

Connection property useTranslation (and it's alias mapping_path) will no longer be available. As part of this change, the following parts of the implementation have been removed (note that most are internal to Jaybird):

• org.firebirdsql.encodings.CharacterTranslator will be removed entirely
• DatatypeCoder#encodeString(String value, String javaEncoding, String mappingPath)
• DatatypeCoder#encodeString(String value, Encoding encoding, String mappingPath)
• DatatypeCoder#decodeString(byte[] value, String javaEncoding, String mappingPath)
• DatatypeCoder#decodeString(byte[] value, Encoding encoding, String mappingPath)
• Encoding#withTranslation(CharacterTranslator translator)
• EncodingFactory#getEncoding(String encoding, String mappingPath)
• EncodingFactory#getEncoding(Charset charset, String mappingPath)
• FirebirdConnectionProperties#setUseTranslation(String translationPath) (and on data sources)
• FirebirdConnectionProperties#getUseTranslation (and on data sources)
• IEncodingFactory#getCharacterTranslator(String mappingPath)

8.10 Generated keys support always available

Since Jaybird 4.0.8.

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.11 Removal of constants without deprecation

The following array constants in FBDatabaseMetaData have been made private or have been removed to avoid unintended side effects of modification:

• ALL_TYPES_2_5
• ALL_TYPES_2_1
• ALL_TYPES

Instead, use DatabaseMetaData.getTableTypes() (which returns a ResultSet), or FirebirdDatabaseMetaData.getTableTypeNames() (which returns a String[]).

To access getTableTypeNames(), the DatabaseMetaData needs to be unwrapped to FirebirdDatabaseMetaData

DatabaseMetaData dbmd = connection.getDatabaseMetaData();
String[] tableTypes = dbmd
        .unwrap(FirebirdDatabaseMetaData.class)
        .getTableTypeNames();

8.12 Removal of deprecated classes, packages and methods

The following connection properties (and equivalent data source properties) have been removed:

• useTranslation: See Removal of character mapping
• octetsAsBytes: Since Jaybird 3 octets is always handled as BINARY
• noResultSetTracking: Option does nothing since Jaybird 3
• paranoia_mode: Option does nothing since Jaybird 2.2 (maybe earlier)

The following deprecated methods have been removed in Jaybird 4:

• GDSHelper.iscVaxInteger(byte[] buffer, int pos, int length) use VaxEncoding.iscVaxInteger(byte[] buffer, int startPosition, int length) instead.
• GDSHelper.iscVaxLong(byte[] buffer, int pos, int length) use VaxEncoding.iscVaxLong(byte[] buffer, int startPosition, int length) instead.
• MaintenanceManager.commitTransaction(int transactionId), use MaintenanceManager.commitTransaction(long transactionId) instead.
• MaintenanceManager.rollbackTransaction(int transactionId), use MaintenanceManager.rollbackTransaction(long transactionId) instead.
• ServiceRequestBufferImp#ServiceRequestBufferImp()
• ServiceRequestBufferImp#ServiceRequestBufferImp(int taskIdentifier)
• FBBlob#copyCharacterStream(Reader reader, long length, String encoding)
• FBBlob#copyCharacterStream(Reader reader, String encoding)
• See also Removal of character mapping for a number of removed methods

The following classes have been removed in Jaybird 4:

• org.firebirdsql.gds.ExceptionListener, use org.firebirdsql.gds.ng.listeners.ExceptionListener
• org.firebirdsql.pool.FBSimpleDataSource, use org.firebirdsql.ds.FBSimpleDataSource

8.13 Breaking changes for Jaybird 5

With Jaybird 5 the following breaking changes will be introduced.

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.5.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.5.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>4.0.3.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.