#870 Backport to Jaybird 6: #839 Protocol 19 and native implementation for inline blobs

Author: mrotteveel

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

@@ -24,11 +24,39 @@
  */
 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 6.0.2
+     */
+    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

@@ -38,6 +38,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.
@@ -127,10 +128,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();
@@ -173,6 +174,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

@@ -54,6 +54,9 @@ The values were changed from the original default and maximum of 32,767 to:
 +
 This change improves the performance of preparing statements with a lot of columns and parameters by reducing the number of round-trips needed to retrieve the column and parameter information.
 It may also prevent truncation of "`explained plans`" for statements with very complex or extensive plans.
+* Improvement: backported inline blob support (Firebird 5.0.3 and higher) from Jaybird 7 (https://github.com/FirebirdSQL/jaybird/issues/870[#870])
++
+See also <<blob-performance-inline-blob>>.
 
 === Jaybird 6.0.1
 
@@ -833,6 +836,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.
 
 For native connections, a similar optimization -- but only for reading blobs -- is available when using a Firebird 5.0.2 or higher fbclient, independent of the Jaybird version.
@@ -854,6 +859,53 @@ This optimization is available for Firebird 2.1 and higher, but formally only su
 
 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
+
+Added in: Jaybird 6.0.2, backported from Jaybird 7
+
+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.
+
 [#blob-performance-min-buf]
 ==== Minimum `blobBufferSize` 512 bytes
 

src/jna-test/org/firebirdsql/gds/ng/jna/JnaStatementTest.java

@@ -20,17 +20,33 @@
 
 import org.firebirdsql.common.FBTestProperties;
 import org.firebirdsql.common.extension.GdsTypeExtension;
+import org.firebirdsql.gds.ClumpletReader;
+import org.firebirdsql.gds.impl.GDSServerVersion;
 import org.firebirdsql.gds.ng.AbstractStatementTest;
 import org.firebirdsql.gds.ng.DatatypeCoder;
+import org.firebirdsql.gds.ng.FbBlob;
 import org.firebirdsql.gds.ng.FbDatabase;
 import org.firebirdsql.gds.ng.fields.RowValue;
 import org.firebirdsql.gds.ng.wire.SimpleStatementListener;
+import org.firebirdsql.util.FirebirdSupportInfo;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
+import java.nio.charset.StandardCharsets;
 import java.sql.SQLException;
 
+import static org.firebirdsql.common.FbAssumptions.assumeFeature;
+import static org.firebirdsql.common.matchers.GdsTypeMatchers.isOtherNativeType;
+import static org.firebirdsql.common.matchers.MatcherAssume.assumeThat;
+import static org.firebirdsql.gds.ISCConstants.fb_info_wire_rcv_bytes;
+import static org.firebirdsql.gds.ISCConstants.isc_info_end;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.greaterThan;
+import static org.hamcrest.Matchers.hasSize;
 import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
 /**
  * Tests for JNA statement.
@@ -43,6 +59,11 @@ class JnaStatementTest extends AbstractStatementTest {
     @RegisterExtension
     static final GdsTypeExtension testType = GdsTypeExtension.supportsNativeOnly();
 
+    /**
+     * See also {@code INLINE_BLOB_TEST_MAX_SIZE} in {@link org.firebirdsql.gds.ng.wire.version19.V19StatementTest}.
+     */
+    protected static final int INLINE_BLOB_TEST_MAX_SIZE = 65531;
+
     private final AbstractNativeDatabaseFactory factory =
             (AbstractNativeDatabaseFactory) FBTestProperties.getFbDatabaseFactory();
 
@@ -234,4 +255,105 @@ public void testSelect_WithParameters_Execute_and_Fetch() throws Exception {
         assertNotNull(listener.getSqlCounts(), "Expected SQL counts");
         assertEquals(listener.getRows().size(), listener.getSqlCounts().selectCount(), "Unexpected select count");
     }
+
+    // NOTE The following tests are similar to the tests in V19StatementTest with the same name. In case of the JNA
+    // tests, they might have been more appropriate in JnaBlobTest, but for consistency with the pure Java tests, we put
+    // them here.
+
+    @ParameterizedTest
+    @ValueSource(ints = { 0, 1, 500, INLINE_BLOB_TEST_MAX_SIZE })
+    public void usesInlineBlob_defaultMax(int size) throws Exception {
+        assumeInlineBlobSupport();
+        assertFbBlob(size, true);
+    }
+
+    @Test
+    public void usesNormalBlob_defaultMax() throws Exception {
+        assumeInlineBlobSupport();
+        // First size that will produce a "normal" blob
+        final int size = INLINE_BLOB_TEST_MAX_SIZE + 1;
+        assertFbBlob(size, false);
+    }
+
+    @Test
+    public void usesInlineBlob_max16384() throws Exception {
+        assumeInlineBlobSupport();
+        replaceDbHandleWithInlineBlobConfig(16384, null);
+        final int size = 16384 - 2;
+        assertFbBlob(size, true);
+    }
+
+    @Test
+    public void usesNormalBlob_max16384() throws Exception {
+        assumeInlineBlobSupport();
+        replaceDbHandleWithInlineBlobConfig(16384, null);
+        final int size = 16384 - 1;
+        assertFbBlob(size, false);
+    }
+
+    @ParameterizedTest
+    @ValueSource(ints = { 0, 1 })
+    public void usesNormalBlob_cacheSizeZero(int size) throws Exception {
+        assumeInlineBlobSupport();
+        replaceDbHandleWithInlineBlobConfig(null, 0);
+        assertFbBlob(size, false);
+    }
+
+    private void assumeInlineBlobSupport() {
+        assumeThat("Test requires non-embedded type", FBTestProperties.GDS_TYPE, isOtherNativeType());
+        // Formally, we should also check if we make a TCP/IP connection
+        assumeFeature(FirebirdSupportInfo::supportsInlineBlobs, "Test requires inline blob support");
+        GDSServerVersion clientVersion = ((JnaDatabase) db).getClientVersion();
+        assumeTrue(clientVersion.isEqualOrAbove(5, 0, 3),
+                "Test requires fbclient version supporting inline blobs, was: " + clientVersion);
+    }
+
+    private void assertFbBlob(int size, boolean expectInlineBlob) throws SQLException {
+        allocateStatement();
+        statement.addStatementListener(listener);
+        statement.prepare(PRODUCE_BLOB);
+
+        final DatatypeCoder coder = db.getDatatypeCoder();
+        var params = RowValue.of(coder.encodeInt(size));
+        statement.execute(params);
+        statement.fetchRows(1);
+
+        assertThat("expected a row", listener.getRows(), hasSize(1));
+        RowValue rowValue = listener.getRows().get(0);
+        long blobId = coder.decodeLong(rowValue.getFieldData(0));
+        FbBlob blob = db.createBlobForInput(getOrCreateTransaction(), blobId);
+
+        assertBlobLengthAndContent(blob, size, expectInlineBlob);
+    }
+
+    private void assertBlobLengthAndContent(FbBlob blob, int size, boolean expectInlineBlob) throws SQLException {
+        long receivedBytesBefore = getReceivedBytes();
+        blob.open();
+        assertEquals(size, blob.length(), "unexpected blob size");
+        if (size > 0) {
+            byte[] data = new byte[size];
+            blob.get(data, 0, size);
+            assertEquals("x".repeat(size), new String(data, StandardCharsets.US_ASCII));
+        }
+        long receivedBytesAfter = getReceivedBytes();
+        long receivedBytesDifference = receivedBytesAfter - receivedBytesBefore;
+        if (expectInlineBlob) {
+            assertEquals(0L, receivedBytesDifference, "expected an inline blob, so no received network data");
+        } else {
+            // For server-side blob, more bytes than size will have been received (i.e. open, get segment, etc.)
+            assertThat("expected a server-side blob", receivedBytesDifference, greaterThan((long) size));
+        }
+    }
+
+    private long getReceivedBytes() throws SQLException {
+        return db.getDatabaseInfo(new byte[] { (byte) fb_info_wire_rcv_bytes, isc_info_end }, 20, infoResponse -> {
+            var reader = new ClumpletReader(ClumpletReader.Kind.InfoResponse, infoResponse);
+            if (reader.find(fb_info_wire_rcv_bytes)) {
+                return reader.getLong();
+            }
+            throw new IllegalStateException(
+                    "Did not receive item fb_info_wire_rcv_bytes (157), this is probably a 5.0.1 or older fbclient");
+        });
+    }
+
 }

src/main/module-info.java

@@ -84,7 +84,8 @@
                     org.firebirdsql.gds.ng.wire.version13.Version13Descriptor,
                     org.firebirdsql.gds.ng.wire.version15.Version15Descriptor,
                     org.firebirdsql.gds.ng.wire.version16.Version16Descriptor,
-                    org.firebirdsql.gds.ng.wire.version18.Version18Descriptor;
+                    org.firebirdsql.gds.ng.wire.version18.Version18Descriptor,
+                    org.firebirdsql.gds.ng.wire.version19.Version19Descriptor;
 
     uses org.firebirdsql.jaybird.props.spi.ConnectionPropertyDefinerSpi;
 }

src/main/org/firebirdsql/ds/AbstractConnectionPropertiesDataSource.java

@@ -516,6 +516,26 @@ public void setAsyncFetch(boolean asyncFetch) {
         FirebirdConnectionProperties.super.setAsyncFetch(asyncFetch);
     }
 
+    @Override
+    public int getMaxInlineBlobSize() {
+        return FirebirdConnectionProperties.super.getMaxInlineBlobSize();
+    }
+
+    @Override
+    public void setMaxInlineBlobSize(int maxInlineBlobSize) {
+        FirebirdConnectionProperties.super.setMaxInlineBlobSize(maxInlineBlobSize);
+    }
+
+    @Override
+    public int getMaxBlobCacheSize() {
+        return FirebirdConnectionProperties.super.getMaxBlobCacheSize();
+    }
+
+    @Override
+    public void setMaxBlobCacheSize(int maxBlobCacheSize) {
+        FirebirdConnectionProperties.super.setMaxBlobCacheSize(maxBlobCacheSize);
+    }
+
     @SuppressWarnings("deprecation")
     @Deprecated(since = "5")
     @Override

src/main/org/firebirdsql/gds/ISCConstants.java

@@ -602,6 +602,25 @@ public interface ISCConstants {
     int fb_info_username = 147;
     int fb_info_sqlrole = 148;
 
+    int fb_info_parallel_workers = 149;
+
+    // The following items are only known to fbclient 5.0.2 and higher, not to the server.
+    // The pure Java implementation is not aware of these either.
+    int fb_info_wire_out_packets = 150;
+    int fb_info_wire_in_packets = 151;
+    int fb_info_wire_out_bytes = 152;
+    int fb_info_wire_in_bytes = 153;
+    int fb_info_wire_snd_packets = 154;
+    int fb_info_wire_rcv_packets = 155;
+    int fb_info_wire_snd_bytes = 156;
+    int fb_info_wire_rcv_bytes = 157;
+    int fb_info_wire_roundtrips = 158;
+
+    // The following items are only known to fbclient 5.0.3 and higher, not to the server.
+    // The pure Java implementation is not aware of these either.
+    int fb_info_max_blob_cache_size = 159;
+    int fb_info_max_inline_blob_size = 160;
+
     int isc_info_db_impl_rdb_vms = 1;
     int isc_info_db_impl_rdb_eln = 2;
     int isc_info_db_impl_rdb_eln_dev = 3;

src/main/org/firebirdsql/gds/JaybirdSystemProperties.java

@@ -42,6 +42,8 @@ public final class JaybirdSystemProperties {
     public static final String DEFAULT_ENABLE_PROTOCOL = JDBC_PREFIX + "defaultEnableProtocol";
     public static final String DEFAULT_REPORT_SQL_WARNINGS = JDBC_PREFIX + "defaultReportSQLWarnings";
     public static final String DEFAULT_ASYNC_FETCH = JDBC_PREFIX + "defaultAsyncFetch";
+    public static final String DEFAULT_MAX_INLINE_BLOB_SIZE = JDBC_PREFIX + "defaultMaxInlineBlobSize";
+    public static final String DEFAULT_MAX_BLOB_CACHE_SIZE = JDBC_PREFIX + "defaultMaxBlobCacheSize";
     public static final String DATATYPE_CODER_CACHE_SIZE = COMMON_PREFIX + "datatypeCoderCacheSize";
     public static final String NATIVE_LIBRARY_SHUTDOWN_DISABLED = COMMON_PREFIX + "nativeResourceShutdownDisabled";
     public static final String WIRE_DEFLATE_BUFFER_SIZE = WIRE_PREFIX + "deflateBufferSize";
@@ -117,6 +119,14 @@ public static Boolean getDefaultAsyncFetch() {
         return asyncFetch.isBlank() || Boolean.parseBoolean(asyncFetch);
     }
 
+    public static Integer getDefaultMaxInlineBlobSize() {
+        return getIntegerSystemPropertyPrivileged(DEFAULT_MAX_INLINE_BLOB_SIZE);
+    }
+
+    public static Integer getDefaultMaxBlobCacheSize() {
+        return getIntegerSystemPropertyPrivileged(DEFAULT_MAX_BLOB_CACHE_SIZE);
+    }
+
     private static int getWithDefault(String propertyName, int defaultValue) {
         Integer value = getIntegerSystemPropertyPrivileged(propertyName);
         return value != null ? value : defaultValue;