Skip to content

Latest commit

 

History

History
589 lines (421 loc) · 20.5 KB

release_notes.adoc

File metadata and controls

589 lines (421 loc) · 20.5 KB
Raw

Jaybird {version_wo_target} Release Notes

Table of Contents

1. Jaybird 7.0.x changelog

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

…​

2. Known issues

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

    Possible workarounds:

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

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

    • Use a Firebird 2.5 or earlier fbclient.

    This is caused by firebird#4971

3. General Notes

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

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

3.1. About this version

The major changes and new features in Jaybird 7 are:

  • …​

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

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

3.2. Supported Firebird versions

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

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

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

This driver does not support InterBase.

3.3. Supported Java versions

Jaybird 7 supports Java 17 and higher (JDBC 4.3). Support for earlier Java versions has been dropped.

Given the limited support period for Java 9 and higher versions, we limit support to Java 17, the most recent LTS version after Java 17, and the latest Java release. Currently, that means we support Java 17, Java 21, and Java 23.

Note

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

Jaybird 7 provides libraries compiled for Java 17.

Jaybird 7 is modularized. The available modules are:

org.firebirdsql.jaybird

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

org.firebirdsql.jaybird.chacha64

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

org.firebirdsql.jna

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

3.4. Specification support

Jaybird supports the following specifications:

Specification Notes

JDBC 4.3

All JDBC 4.3 methods for features supported by Firebird.

JTA 1.0.1

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

4. Support

If you need support with Jaybird, join the Firebird-Java Google Group and mailing list. You can subscribe by sending an email to [email protected].

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

For a more complete list, see the next section.

4.1. Where to get help

4.2. Contributing

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

4.3. Reporting bugs

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

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

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

5. Getting Jaybird 7

5.1. Jaybird {version_wo_target}

5.1.1. Maven

Jaybird {version_wo_target} is available on Maven Central.

groupId

org.firebirdsql.jdbc
artifactId

jaybird
version

{version_example}

For example:

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

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

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

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

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

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

5.1.2. Gradle

See also Maven.

Examples:

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

5.1.3. Download

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

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

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

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

6. Upgrading from Jaybird 6 to Jaybird 7

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

6.1. Maven

Change the version of the dependency to {version_example}.

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

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

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

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

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

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

6.2. Manual install

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

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

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

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

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

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

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

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

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

6.3. Gotcha’s

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

For known issues, consult Known issues.

7. What’s new in Jaybird 7

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

7.1. Java support

Note

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

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

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

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

7.2. Firebird support

Note

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

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

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

Warning
No promises on Firebird 6.0 support

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

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

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

7.3. Other fixes and changes

  • …​

8. Compatibility changes

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

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

8.1. Removal of classes, packages and methods without deprecation

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

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

8.1.1. Removal of packages without deprecation

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

  • …​

8.1.2. Removal of methods without deprecation

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

  • …​

8.1.3. Removal of classes without deprecation

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

  • …​

8.1.4. Removal of constants without deprecation

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

  • …​

8.2. Removal of deprecated classes, packages and methods

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

8.2.1. Removal of deprecated packages

The following packages have been removed in Jaybird 7:

  • …​

8.2.2. Removal of deprecated methods

The following methods have been removed in Jaybird 7:

  • GDSFactoryPlugin (semi-internal API)

    • getTypeAliases() — use getTypeAliasList()

    • getSupportedProtocols — use getSupportedProtocolList()

  • GDSHelper (internal API)

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

  • FirebirdStatement

    • getCurrentResultSet() — use getResultSet()

  • SqlCountHolder (internal API)

    • getLongUpdateCount() — use updateCount()

    • getLongDeleteCount() — use deleteCount()

    • getLongInsertCount() — use insertCount()

    • getLongSelectCount() — use selectCount()

8.2.3. Removal of deprecated classes

The following classes have been removed in Jaybird 7:

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

  • FBSQLException; use SQLException

8.2.4. Removal of deprecated constants

The following constants have been removed in Jaybird 7:

  • ISCConstants

    • isc_isc_sql_dialect_conflict_num; use isc_sql_dialect_conflict_num

    • isc_err_max; there is no replacement

  • JaybirdErrorCodes

    • jb_stmtInErrorRequireCLose; use jb_stmtInErrorRequireClose

  • QuoteStrategy

    • NO_QUOTES; use DIALECT_1

    • QUOTES; use DIALECT_3

  • SQLStateConstants

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

  • ServiceManager

    • getHost/setHost; use getServerName/setServerName

    • getPort/setPort; use getPortNumber/setPortNumber

8.3. Breaking changes internal API

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

Note

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

  • …​

8.4. Unlikely breaking changes

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

8.5. Breaking changes for Jaybird 8

With Jaybird 8 the following breaking changes will be introduced.

8.5.1. Removal of deprecated classes, packages and methods

Removal of deprecated methods

The following methods will be removed in Jaybird 8:

  • …​

Removal of deprecated classes

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

  • …​

8.5.2. Removal of deprecated constants

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

  • …​

9. Compatibility notes

9.1. Type 2 (native) and embedded driver

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

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

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

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

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

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

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

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