#839 Protocol 19 and native implementation for inline blobs

Author: mrotteveel

REUSE.toml

@@ -105,5 +105,5 @@ SPDX-License-Identifier = "LGPL-2.1-or-later"
 [[annotations]]
 path = "src/resources/META-INF/services/org.firebirdsql.gds.ng.wire.ProtocolDescriptor"
 precedence = "aggregate"
-SPDX-FileCopyrightText = "Copyright 2013-2021 Mark Rotteveel"
+SPDX-FileCopyrightText = "Copyright 2013-2025 Mark Rotteveel"
 SPDX-License-Identifier = "LGPL-2.1-or-later"

devdoc/jdp/jdp-2025-03-implement-protocol-19.adoc

@@ -15,24 +15,25 @@
 == Context
 
 Firebird 5.0.3 introduces protocol version 19, which will provide a significant performance improvement for small blobs.
-This improvement is achieved by sending small blobs inline during the response to cursor fetch, removing the need to explicitly open and request the blobs one by one.
+This improvement is achieved by sending small blobs inline during the response to a cursor fetch, removing the need to explicitly open and request the blobs one by one.
 
 Overview of protocol changes:
 
 * The upper limit for inline blob length is 65535 bytes (0xFFFF);
 this includes segment length(s).
 * `op_execute`/`op_execute2` has an extra (unsigned) int `p_sqldata_inline_blob_size` with the requested inline blob size sent immediately after `p_sqldata_cursor_flags`
 * We don't cover the changes for `op_exec_immediate2` as Jaybird doesn't implement it
-* The response to `op_execute2` will have zero or more `op_inline_blob` (114) responses before the `op_sql_response` packet
-* The response to `op_fetch` will have zero or more `op_inline_blob` (114) responses before each `op_fetch_response`
+* The response to `op_execute2` will have zero or more `op_inline_blob` `(114`) responses before the `op_sql_response` packet
+* The response to `op_fetch`/`op_fetch_scroll` will have zero or more `op_inline_blob` (`114`) responses before each `op_fetch_response`
 * The `op_line_blob` response is the `P_INLINE_BLOB` message with the following payload:
 ** `p_tran_id` int (formally short): transaction handle
 ** `p_blob_id` long: blob id
 ** `p_blob_info` buffer: blob info with (`isc_info_blob_num_segments`, `isc_info_blob_max_segment`, `isc_info_blob_total_length`, `isc_info_blob_type`, `isc_info_end`)
 ** `p_blob_data` buffer: blob data (including segment lengths!)
-* Two DPB items were added, `isc_dpb_max_blob_cache_size` (159) and `isc_dpb_max_inline_blob_size` (160), which are used to configure the client.
+* Two DPB items were added, `isc_dpb_max_blob_cache_size` (`159`) and `isc_dpb_max_inline_blob_size` (`160`), which are used to configure the client.
 
 The JDBC implementation in Jaybird requests blobs with a blob parameter buffer that should match the "`normal`" blob, but API-wise on the `FbDatabase` side, it could be anything.
+The fbclient implementation will not use the cached inline blob if any blob parameter buffer is passed.
 
 == Decision
 
@@ -41,7 +42,7 @@ As Jaybird 5 is the "`long-term support`" version for Java 8, and this is a cons
 === Decision details
 
 * Two connection properties, `maxBlobCacheSize` and `maxInlineBlobSize`, are added and associated with their respective DPB items.
-That way the implementation will also support configuring inline blobs for native connections (when using fbclient 5.0.3 or higher).
+That way, the implementation will also support configuring inline blobs for native connections (when using fbclient 5.0.3 or higher).
 ** If `maxInlineBlobSize` is not explicitly set, it will use a default of 64 KiB for pure Java connections;
 for native connections, it will use the fbclient default (currently also 64 KiB). +
 ** Setting `maxInlineBlobSize` to `0` will disable inline blobs
@@ -50,26 +51,19 @@ for native connections, it will use the fbclient default (currently also 10 MiB)
 ** Setting `maxBlobCacheSize` to `0` will *not* disable inline blobs.
 * The received inline blobs will be registered on the `FbWireDatabase` instance in a blob cache, to be returned from `createBlobForInput` as an inline blob instance implementing `FbWireBlob`.
 ** The blob cache tracks memory use based on the blob length and will hold the blob data *without* segment lengths.
-If the blob cache exceeds the `maxInlineBlobSize`, the inline blob will be thrown away.
-** Once requested, the blob will be removed from the cache (i.e. a subsequent call to `createBlobForInput` for the same blob id will open a server-side blob).
-** If the transaction associated with the blob is committed or rolled back (when `COMMITTED` or `ROLLED_BACK` is notified), all blobs of that transaction are removed from the cache.
-
-=== Pending decisions
-
-The following needs to be investigated in more detail before a final decision can be made.
-
-* The local blob may need to be able to open a server-side blob for info requests, or explicitly throw an exception for those cases.
-* We may need some checks on the arguments of the BPB and/or `BlobConfig` to ensure it is suitable to return the local blob, or if a server-side blob needs to be opened, check for a subtype (not available in information items), and possibly the charset id requested.
+If the blob cache exceeds the `maxInlineBlobSize`, the inline blob to be registered will be thrown away.
+** Once requested, the blob will be removed from the cache (i.e. a subsequent call to `createBlobForInput` for the same transaction and blob id will open a server-side blob).
+** If the transaction associated with the blob is committed, rolled back or prepared (when `COMMITTED`, `ROLLED_BACK` or `PREPARED` is notified), all blobs of that transaction are removed from the cache.
+* The default value of `maxBlobCacheSize` and `maxInlineBlobSize` can be overridden with system properties `org.firebirdsql.jdbc.defaultMaxBlobCacheSize` and `org.firebirdsql.jdbc.defaultMaxInlineBlobSize`
+* The information request on an inline blob (pure Java) will filter the information request (this is similar to the native implementation)
+** If a requested information item is unknown (i.e. not in the information items sent in `op_inline_blob`), no exception is thrown, and the filtered information response will not include it.
+* On opening a blob that should use the "`default`" settings, Jaybird will no longer provide a parameter buffer or `BlobConfig`.
 +
-For example, currently Jaybird will set `isc_bpb_source_type` and `isc_bpb_target_type` to the subtype of the field, and for subtype `TEXT` `isc_bpb_target_interp` to the charset id of the field.
-We could assume that if source_type and target_type have the same value, we can use the cached inline blob.
-* Alternative for previous, there needs to be some mechanism so the caller can signal that the cache *should not* be used.
+Rationale: The native implementation will not use the cached inline blob if one is opened with any blob parameter buffer.
 +
-This is probably too complex and will never actually be used.
-* Alternative for previous, there needs to be some mechanism so the caller can signal that the cache *should* be used.
+Unfortunately, this does mean undoing changes introduced in Jaybird 5 to always explicitly provide a DPB on open with `isc_bpb_source_type` and `isc_bpb_target_type` set to the known subtype, and -- for `SUB_TYPE TEXT` --  `isc_bpb_target_interp` set to the charset id of the field.
 +
-This is probably too complex, and would only get used by Jaybird itself.
-** A more
+We will retain a similar solution creating a BPB for create.
 
 === Rejected decisions
 
@@ -82,11 +76,18 @@ It also prevents overloading the meaning of `blobBufferSize`.
 * Make `maxBlobCacheSize` set to `0` disable inline blobs as well.
 +
 Having a single property control enabling and disabling inline blobs is simpler.
+* The blob config or blob parameter buffer has an extra option to communicate that the inline blob cache should (or should not) be used.
++
+Although this would be a viable solution for pure Java, and we initially implemented a Jaybird-specific BPB-item that signalled the inline cache should be bypassed.
+This does not work for the native API, as that will only use an inline blob if no blob parameter buffer is used, and open a remote blob if any blob parameter buffer is provided.
+To maintain a coherent API, we decided to do the same for pure Java.
 
 == Consequences
 
 A version 19 protocol implementation will be added.
-Inline blobs will be used by default when connecting to Firebird 5.0.3 or higher, but can be disabled by setting `maxInlineBlobSize` to `0`.
+Inline blobs will be used by default when connecting to Firebird 5.0.3 or higher, but can be disabled by setting `maxInlineBlobSize` to `0` and/or `maxBlobCacheSize` to `0`.
+
+If only the cache is disabled, the server will still send inline blobs, but the client will immediately discard them.
 
 [appendix]
 == License Notice

jaybird-native/src/main/java/org/firebirdsql/gds/ng/jna/JnaAttachment.java

@@ -1,12 +1,40 @@
-// SPDX-FileCopyrightText: Copyright 2015-2023 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2015-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later OR BSD-3-Clause
 package org.firebirdsql.gds.ng.jna;
 
+import org.firebirdsql.gds.impl.GDSServerVersion;
+import org.firebirdsql.gds.impl.GDSServerVersionException;
 import org.firebirdsql.gds.ng.FbAttachment;
 
+import java.util.List;
+
 /**
  * @author Mark Rotteveel
  * @since 3.0
  */
 public interface JnaAttachment extends FbAttachment {
+
+    /**
+     * Reports the client library version of this attachment.
+     * <p>
+     * The default implementation extracts the last raw version string of {@link #getServerVersion()} and parses that.
+     * </p>
+     *
+     * @return client version, may report {@link GDSServerVersion#INVALID_VERSION} if the implementation can't determine
+     * the client version or if parsing fails.
+     * @since 7
+     */
+    default GDSServerVersion getClientVersion() {
+        GDSServerVersion serverVersion = getServerVersion();
+        List<String> rawVersions = serverVersion.getRawVersions();
+        if (rawVersions.isEmpty()) {
+            return GDSServerVersion.INVALID_VERSION;
+        }
+        try {
+            return GDSServerVersion.parseRawVersion(rawVersions.get(rawVersions.size() - 1));
+        } catch (GDSServerVersionException e) {
+            return GDSServerVersion.INVALID_VERSION;
+        }
+    }
+
 }

jaybird-native/src/main/java/org/firebirdsql/gds/ng/jna/JnaBlob.java

@@ -22,6 +22,7 @@
 import static org.firebirdsql.gds.ISCConstants.isc_segstr_no_op;
 import static org.firebirdsql.gds.JaybirdErrorCodes.jb_blobGetSegmentNegative;
 import static org.firebirdsql.gds.JaybirdErrorCodes.jb_blobPutSegmentEmpty;
+import static org.firebirdsql.jaybird.util.ByteArrayHelper.validateBufferLength;
 
 /**
  * Implementation of {@link org.firebirdsql.gds.ng.FbBlob} for native client access.
@@ -111,10 +112,10 @@ public void open() throws SQLException {
 
             final BlobParameterBuffer blobParameterBuffer = getBlobParameterBuffer();
             final byte[] bpb;
-            if (blobParameterBuffer != null) {
-                bpb = blobParameterBuffer.toBytesWithType();
-            } else {
+            if (blobParameterBuffer == null || blobParameterBuffer.isEmpty()) {
                 bpb = ByteArrayHelper.emptyByteArray();
+            } else {
+                bpb = blobParameterBuffer.toBytesWithType();
             }
             try (var ignored = withLock()) {
                 checkDatabaseAttached();
@@ -157,6 +158,11 @@ public byte[] getSegment(int sizeRequested) throws SQLException {
             checkDatabaseAttached();
             checkTransactionActive();
             checkBlobOpen();
+
+            if (isEof()) {
+                return ByteArrayHelper.emptyByteArray();
+            }
+
             ShortByReference actualLength = new ShortByReference();
             ByteBuffer responseBuffer = getSegment0(sizeRequested, actualLength);
             throwAndClearDeferredException();

src/docs/asciidoc/release_notes.adoc

@@ -433,6 +433,8 @@ This is especially noticeable in connections with high latency.
 
 Artificial testing on local WiFi with small blobs shows around 85% increase in throughput (comparing a 6.0.1-SNAPSHOT against 6.0.0).
 
+The <<blob-performance-inline-blob>> for Firebird 5.0.3 and higher replaces this improvement for smallish blobs, but it still has benefit for blobs larger than `maxInlineBlobSize` or blobs that are discarded when the inline blob cache is full.
+
 This optimization is available for Firebird 2.1 and higher, but formally only supported for Firebird 3.0 and higher.
 
 This optimization was backported to Jaybird 5.0.7 and Jaybird 6.0.1.
@@ -456,6 +458,53 @@ This optimization was backported to Jaybird 5.0.7 and Jaybird 6.0.1.
 
 For native connections, a similar optimization is available when using a Firebird 5.0.2 or higher fbclient, independent of the Jaybird version.
 
+[#blob-performance-inline-blob]
+==== Inline blob support
+
+Introduced in Firebird 5.0.3 (protocol 19), inline blobs offer a significant performance improvement for querying smallish blobs.
+As the name suggests, blobs are sent _inline_ together with the row data, avoiding additional round trips to the server for reading the blob data and blob information.
+
+There are two connection properties affecting inline blobs:
+
+`maxInlineBlobSize` (aliases: `max_inline_blob_size`, `isc_dpb_max_inline_blob_size`)::
+Maximum size in bytes of the blob (default: `65535`). +
+A value of `0` will disable sending of inline blobs.
++
+The maximum value is decided by the Firebird server, and is currently `65535`;
+this may change in the future
++
+If a blob is smaller than the specified size, the server will send it inline.
+The size includes segment lengths, so the actual maximum blob data received is `_N_ * 2` bytes smaller, where _N_ is the number of segments of the actual blob.
++
+The default can be changed with system property `org.firebirdsql.jdbc.defaultMaxInlineBlobSize`.
+
+`maxBlobCacheSize` (aliases: `max_blob_cache_size`, `isc_dpb max_blob_cache_size`)::
+Maximum size in bytes -- per connection -- of the blob cache (default: `10485760` or 10 MiB). +
+A value of `0` will disable the cache, but does not disable sending of inline blobs.
+Set `maxInlineBlobSize` to `0` to disable sending of inline blobs.
++
+For pure Java, only the data size is counted towards the cache size.
+For native, the segment lengths also count towards the cache size.
++
+The default can be changed with system property `org.firebirdsql.jdbc.defaultMaxBlobCacheSize`.
+
+This feature works with pure Java and native connections when connecting to Firebird 5.0.3 or higher.
+For native connections, a Firebird 5.0.3 or higher client library must be used.
+
+If the maximum blob cache size is reached, received inline blobs will be discarded.
+For pure Java connections, an inline blob is removed from the cache on first use, or when the transaction associated with the blob ends.
+The native client implementation may have different cache eviction rules.
+
+As pure java connections remove the inline blob from the cache on first use, subsequent attempts to read the same blob -- by getting a different instance of `java.sql.Blob` or through multiple calls to the `ResultSet.getXXX` methods -- will use a server-side blob.
+This can also happen if multiple columns or rows, even in different result sets on the same connection, point to the same blob id in the same transaction.
+
+If you execute queries returning blobs, while those blobs are never actually opened, you may fill up the cache and later received inline blobs are then discarded.
+Especially in long-running transactions, this may reduce the effectiveness of this feature.
+
+Artificial testing on local WiFi with small blobs (200 bytes) shows a 30,000-45,000% (yes, thousand)footnote:[The wide range of the percentages is due to running the test with a single hop and two hops between client and server, and thus a wide range of latency.] increase in throughput comparing a 6.0.2-SNAPSHOT against 6.0.0, and a 15,000-25,000% increase in throughput comparing a 6.0.2-SNAPSHOT against 6.0.1.
+
+This optimization was backported to Jaybird 5.0.8 and Jaybird 6.0.2.
+
 // TODO add major changes
 
 [#other-fixes-and-changes]