perf: Native Flight SQL prepared statements, statement caching, and transport tuning (v0.7.0)

README.md

@@ -118,11 +118,55 @@ SpiceClient client = SpiceClient.builder()
 ```
 
 Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly
-handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).
+handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429). Retries use exponential backoff with jitter
+(~250ms, 500ms, 1s, ... capped at 10s). If the server reports an expired authentication token
+(UNAUTHENTICATED), the client automatically re-handshakes and retries.
+
+### Performance Tuning
+
+```java
+SpiceClient client = SpiceClient.builder()
+    // Number of gRPC connections; queries are distributed round-robin.
+    // Increase for highly concurrent workloads with large result streams.
+    .withChannelCount(4)
+    // Deadline for query planning and statement preparation RPCs
+    // (result streaming is not limited by this timeout).
+    .withQueryTimeout(Duration.ofSeconds(30))
+    // Max idle prepared statements reused by queryWithParams (default 64, 0 disables).
+    .withPreparedStatementCacheSize(128)
+    .build();
+```
+
+### Connection Pooling and HikariCP
+
+`SpiceClient` is thread-safe and multiplexes concurrent queries over shared HTTP/2 connections — use **one client instance per application** and share it across threads. It does not need an external connection pool; for high concurrency, size the built-in pool with `withChannelCount(n)`.
+
+Applications that want JDBC semantics (ORMs, existing [HikariCP](https://github.com/brettwooldridge/HikariCP) infrastructure) can connect to Spice through the [Arrow Flight SQL JDBC driver](https://arrow.apache.org/docs/java/flight_sql_jdbc_driver.html) and pool those connections with HikariCP — this combination is exercised in this repo's test suite:
+
+```java
+HikariConfig config = new HikariConfig();
+config.setJdbcUrl("jdbc:arrow-flight-sql://localhost:50051/?useEncryption=false");
+// For Spice Cloud: jdbc:arrow-flight-sql://flight.spiceai.io:443/?useEncryption=true
+// with setUsername(appId) and setPassword(apiKey) — the same credentials the SDK uses.
+config.setMaximumPoolSize(4);
+// The Flight SQL JDBC driver does not implement Connection.isValid():
+config.setConnectionTestQuery("SELECT 1");
+
+try (HikariDataSource pool = new HikariDataSource(config);
+        Connection conn = pool.getConnection();
+        PreparedStatement ps = conn.prepareStatement("SELECT * FROM taxi_trips WHERE total_amount > ?")) {
+    ps.setDouble(1, 10.0);
+    try (ResultSet rs = ps.executeQuery()) {
+        while (rs.next()) { /* ... */ }
+    }
+}
+```
+
+Requires `org.apache.arrow:flight-sql-jdbc-driver` (or `flight-sql-jdbc-core`) and `com.zaxxer:HikariCP` on your classpath. Keep the pool small — each JDBC connection opens its own Flight channel. Prefer the native `SpiceClient` where possible: it streams Arrow data without JDBC row conversion and is significantly faster for analytical results.
 
 ### Parameterized Queries (Recommended)
 
-The SDK supports parameterized queries using ADBC (Arrow Database Connectivity), which is the recommended approach for queries with user input to prevent SQL injection:
+The SDK supports parameterized queries using Arrow Flight SQL prepared statements, which is the recommended approach for queries with user input to prevent SQL injection. Prepared statements are cached and reused across repeated executions of the same SQL, and run on the same tuned connection as regular queries (DNS re-resolution, keep-alive, mTLS):
 
 ```java
 import org.apache.arrow.vector.VectorSchemaRoot;

docs/parameterized_queries.md

@@ -294,7 +294,12 @@ try {
 2. **Explicit Types**: No overhead, types are directly specified
 3. **Arrow Conversion**: Zero-copy when possible, efficient serialization
 4. **Large Data**: Use Large variants (LargeString, LargeBinary) for > 2GB data
-5. **Connection Reuse**: ADBC connection is initialized lazily and reused
+5. **Statement Reuse**: Prepared statements are cached per SQL string and reused,
+   removing the create/close round trips from repeated queries. Tune with
+   `withPreparedStatementCacheSize(n)` (default 64; 0 disables caching).
+6. **Connection Reuse**: Parameterized queries share the same gRPC channels as
+   regular queries — one connection pool, one set of keep-alive/DNS/mTLS settings.
+   Use `withChannelCount(n)` for highly concurrent workloads.
 
 ## Security Benefits
 

docs/release_notes/v0.7.0.md

@@ -0,0 +1,77 @@
+# Spice Java SDK v0.7.0
+
+## Highlights
+
+This release is a **performance overhaul**. Parameterized queries move off ADBC onto native Arrow Flight SQL prepared statements running on the same tuned connection as regular queries, prepared statements are cached and reused, retries use real exponential backoff, and the Netty/gRPC dependency stack is aligned onto supported versions.
+
+## What's New
+
+### ⚡ Native Flight SQL Prepared Statements (ADBC removed)
+
+`queryWithParams` is now implemented directly on Arrow Flight SQL prepared statements instead of the ADBC driver. This is a pure win with no API change — the method still returns an `ArrowReader`:
+
+- **One connection instead of two.** Parameterized queries previously ran on a separate ADBC-managed gRPC channel that had none of the SDK's transport tuning. They now share the primary channels, inheriting DNS re-resolution (`dns:///`), HTTP/2 keep-alive, and — new in this release for parameterized queries — **mTLS/custom CA support**.
+- **Prepared statement caching.** Statements are cached per SQL string and reused across executions, removing the `CreatePreparedStatement` and `ClosePreparedStatement` round trips from every repeated query (5 → 3 round trips per call). Configure with `withPreparedStatementCacheSize(n)` (default 64, `0` disables).
+- **Transparent recovery.** If the server no longer recognizes a cached statement handle (e.g. after a server restart), the SDK re-prepares and retries automatically.
+- **Multi-endpoint results.** The `ArrowReader` consumes every endpoint of a partitioned result.
+- Two dependencies removed (`adbc-driver-flight-sql`, `adbc-core`).
+
+### 🚀 Performance Tuning Options
+
+```java
+SpiceClient client = SpiceClient.builder()
+    .withChannelCount(4)                        // round-robin gRPC connection pool
+    .withQueryTimeout(Duration.ofSeconds(30))   // deadline for query planning RPCs
+    .withPreparedStatementCacheSize(128)        // prepared statement reuse
+    .build();
+```
+
+- **`withChannelCount(n)`** — opens `n` gRPC connections and distributes queries round-robin, lifting the single-connection ceiling (server `MAX_CONCURRENT_STREAMS`, single-TCP throughput) for highly concurrent workloads. Default 1.
+- **`withQueryTimeout(d)`** — bounds query planning, statement preparation, and parameter binding RPCs. Result streaming is intentionally not limited; dead connections during streaming are detected by keep-alive. Default: no timeout.
+- **`withPreparedStatementCacheSize(n)`** — see above.
+
+### 🔁 Real Retry Backoff
+
+Retries previously waited 1–2ms between attempts — useless against real outages. They now use exponential backoff with jitter (~250ms, 500ms, 1s, … capped at 10s), so the default 3 retries cover ~2s outages such as load-balancer failovers.
+
+### 🔐 Automatic Re-Authentication
+
+If the server reports `UNAUTHENTICATED` (e.g. an expired handshake bearer token on a long-lived client), the SDK re-handshakes once and retries the query automatically. Previously this required a manual `reset()`.
+
+### 🧹 Smaller Fixes
+
+- Fixed a race where `reset()` concurrent with `queryWithParams` could throw `NullPointerException`.
+- Parameter bind roots are sized for their single row instead of Arrow's ~3970-slot default (~48KB saved per string parameter per query).
+- `refreshDataset` now sets a 60s request timeout (previously it could hang forever) and the HTTP client is created lazily.
+- The user agent string is computed once instead of per request; fixed the OS version reported on Windows.
+- `query()` logs a warning if the server returns a multi-endpoint result (only the first endpoint is consumed by the `FlightStream` API; use `queryWithParams` to consume all).
+
+## Dependency Changes
+
+| Dependency                          | v0.6.0        | v0.7.0       |
+| ----------------------------------- | ------------- | ------------ |
+| Apache Arrow ADBC Driver Flight SQL | 0.23.0        | **removed**  |
+| Apache Arrow ADBC Core              | 0.23.0        | **removed**  |
+| netty-all                           | 4.2.12.Final  | **removed**  |
+| Netty (via netty-bom)               | 4.2.12.Final (forced) | 4.1.130.Final |
+| gRPC (via grpc-bom)                 | 1.79.0        | 1.79.0 (pinned) |
+| netty-transport-native-epoll        | —             | 4.1.130.Final (Linux runtime) |
+| BouncyCastle (bcprov/bcpkix)        | transitive    | 1.80 (explicit) |
+
+The `netty-all 4.2.12` pin forced every Netty module to the 4.2 line, which `grpc-netty 1.79` (built against Netty 4.1.130) does not support, and dragged unused codecs (HTTP/3, MQTT, SMTP, Redis, …) onto consumers' classpaths. The stack is now aligned on Netty 4.1.130.Final via `netty-bom`, with native epoll transports added for Linux. BouncyCastle (used for mTLS PEM parsing) is now an explicit dependency instead of riding on ADBC's transitives.
+
+### 🐝 HikariCP / JDBC Interop
+
+`SpiceClient` is thread-safe and needs no external pool (use `withChannelCount`), but applications with JDBC infrastructure can pool connections to Spice with HikariCP via the Arrow Flight SQL JDBC driver. This combination — including authentication and prepared statements — is now verified by `HikariCpCompatTest`, and the README documents the recommended configuration.
+
+## Testing
+
+- New in-process mock Flight SQL server (`TestFlightSqlServer`) with per-RPC counters and failure injection — the full query, prepared-statement, retry, timeout, re-auth, and multi-endpoint behavior is now covered without an external runtime.
+- New test suites: `LocalFlightServerTest`, `StatementCacheTest`, `ResilienceTest`, `FlightInfoReaderTest`, `ParamRootTest`, `RefreshHttpTest`, `HikariCpCompatTest`.
+- New `PerfBenchmarkTest` printing latency percentiles and asserting the round-trip contract (cached path: zero prepares per query; uncached: one prepare + one close per query).
+
+## Compatibility
+
+- Public API unchanged: `query`, `queryWithParams`, `refreshDataset`, `reset`, `close`, and all existing builder methods behave as before.
+- `queryWithParams` error causes are now `FlightRuntimeException` instead of `AdbcException` (both surfaced inside `ExecutionException`).
+- To restore the previous prepare-per-query behavior: `withPreparedStatementCacheSize(0)`.

pom.xml

@@ -4,7 +4,7 @@
     <groupId>ai.spice</groupId>
     <artifactId>spiceai</artifactId>
     <packaging>jar</packaging>
-    <version>0.6.0</version>
+    <version>0.7.0</version>
     <name>Java Spice SDK</name>
     <url>https://github.com/spiceai/spice-java/</url>
     <description>Spice provides a unified SQL query interface and portable runtime to locally materialize, accelerate, and query datasets from any database, data warehouse, or data lake.</description>
@@ -31,26 +31,42 @@
     <properties>
         <maven.compiler.source>11</maven.compiler.source>
         <maven.compiler.target>11</maven.compiler.target>
+        <!-- Netty 4.1.x line: grpc-netty 1.79.0 is built and tested against Netty 4.1.
+             Do NOT bump to the 4.2.x line (netty-all 4.2 previously forced an unsupported
+             gRPC/Netty combination onto the classpath). -->
+        <netty.version>4.1.130.Final</netty.version>
+        <grpc.version>1.79.0</grpc.version>
         <!-- Placeholder for JDK-version-specific JVM flags (e.g. sun.misc.Unsafe access).
              Set via -DextraArgLine="..." on the Maven command line. -->
         <extraArgLine></extraArgLine>
     </properties>
+    <dependencyManagement>
+        <dependencies>
+            <!-- Align every Netty module on a single CVE-patched 4.1.x version supported
+                 by gRPC, without pulling the entire netty-all aggregate onto the classpath. -->
+            <dependency>
+                <groupId>io.netty</groupId>
+                <artifactId>netty-bom</artifactId>
+                <version>${netty.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+            <!-- Keep all io.grpc modules converged on the version the SDK is tested with. -->
+            <dependency>
+                <groupId>io.grpc</groupId>
+                <artifactId>grpc-bom</artifactId>
+                <version>${grpc.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
     <dependencies>
         <dependency>
             <groupId>org.apache.arrow</groupId>
             <artifactId>flight-sql</artifactId>
             <version>19.0.0</version>
         </dependency>
-        <dependency>
-            <groupId>org.apache.arrow.adbc</groupId>
-            <artifactId>adbc-driver-flight-sql</artifactId>
-            <version>0.23.0</version>
-        </dependency>
-        <dependency>
-            <groupId>org.apache.arrow.adbc</groupId>
-            <artifactId>adbc-core</artifactId>
-            <version>0.23.0</version>
-        </dependency>
         <dependency>
             <groupId>com.google.code.gson</groupId>
             <artifactId>gson</artifactId>
@@ -61,10 +77,33 @@
             <artifactId>guava-retrying</artifactId>
             <version>2.0.0</version>
         </dependency>
+        <!-- PEM certificate/key parsing for mTLS (previously an undeclared
+             transitive dependency via the removed ADBC driver). -->
+        <dependency>
+            <groupId>org.bouncycastle</groupId>
+            <artifactId>bcprov-jdk18on</artifactId>
+            <version>1.80</version>
+        </dependency>
+        <dependency>
+            <groupId>org.bouncycastle</groupId>
+            <artifactId>bcpkix-jdk18on</artifactId>
+            <version>1.80</version>
+        </dependency>
+        <!-- Native epoll transport for Linux: lets gRPC/Netty use epoll instead of NIO
+             for lower-latency, lower-allocation socket I/O on Linux servers. -->
         <dependency>
             <groupId>io.netty</groupId>
-            <artifactId>netty-all</artifactId>
-            <version>4.2.12.Final</version>
+            <artifactId>netty-transport-native-epoll</artifactId>
+            <version>${netty.version}</version>
+            <classifier>linux-x86_64</classifier>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.netty</groupId>
+            <artifactId>netty-transport-native-epoll</artifactId>
+            <version>${netty.version}</version>
+            <classifier>linux-aarch_64</classifier>
+            <scope>runtime</scope>
         </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
@@ -83,6 +122,21 @@
             <version>4.13.2</version>
             <scope>test</scope>
         </dependency>
+        <!-- HikariCP interop verification: users who need JDBC pooling connect to
+             Spice through the Arrow Flight SQL JDBC driver; these tests prove the
+             combination works against the same Netty/gRPC stack this SDK ships. -->
+        <dependency>
+            <groupId>com.zaxxer</groupId>
+            <artifactId>HikariCP</artifactId>
+            <version>5.1.0</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.arrow</groupId>
+            <artifactId>flight-sql-jdbc-core</artifactId>
+            <version>19.0.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
     <build>
         <plugins>

src/main/java/ai/spice/Config.java

@@ -93,13 +93,21 @@ public static URI getCloudHttpAddressUri() throws URISyntaxException {
         return new URI(CLOUD_HTTP_ADDRESS);
     }
 
+    // Computed once: system properties are effectively immutable for the
+    // process lifetime, and this used to be recomputed on every request.
+    private static final String USER_AGENT = computeUserAgent();
+
     /**
      * Returns the Spice SDK user agent for this system, including the package
      * version, system OS, version and arch.
-     * 
+     *
      * @return the Spice SDK user agent string for this system.
      */
     public static String getUserAgent() {
+        return USER_AGENT;
+    }
+
+    private static String computeUserAgent() {
         // change the os arch to match the pattern set in other SDKs
         String osArch = System.getProperty("os.arch");
         if (osArch.equals("amd64")) {
@@ -124,7 +132,7 @@ public static String getUserAgent() {
         }
 
         return "spice-java/" + Version.SPICE_JAVA_VERSION + " (" + osName + "/"
-                + System.getProperty("os.version") + " "
+                + osVersion + " "
                 + osArch + ")";
     }
 }