[client-v2] ZSTD is the default but the zstd-jni "cloud" classifier ships no Windows or Intel-macOS natives, so every query fails there

Aperta
  • Qualcosa non va?
#3,175 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
72/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
java
Ambito
backend, databases

Direzione di ricerca

Start with client-v2/pom.xml at lines 61–66 and the parent dependency management for zstd-jni; compare the classifier and version with the other modules. Verify the resolved artifact includes win/amd64 and darwin/x86_64; the issue suggests a unit test for win/amd64 if cross-platform CI is unavailable. Done means default-compression queries work on the affected platforms without missing-native errors.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Description

client-v2 depends on zstd-jni with the cloud classifier
(client-v2/pom.xml:61-66):

<dependency>
    <groupId>com.github.luben</groupId>
    <artifactId>zstd-jni</artifactId>
    <version>1.5.7-20</version>
    <classifier>cloud</classifier>
</dependency>

The cloud classifier jar contains native libraries for only three platforms:

darwin/aarch64/libzstd-jni-1.5.7-20.dylib
linux/aarch64/libzstd-jni-1.5.7-20.so
linux/amd64/libzstd-jni-1.5.7-20.so

There is no win/* and no darwin/x86_64. The default zstd-jni artifact of the same
version contains 18 natives, including win/amd64, win/x86, win/aarch64 and
darwin/x86_64.

Because ClientConfigProperties.COMPRESSION_METHOD defaults to CompressionMethod.ZSTD
(ClientConfigProperties.java:104),
ZSTD is not an opt-in path. On Windows and on Intel macOS, client-v2 and jdbc-v2 fail on
the first query with default settings — the class initializer for
com.github.luben.zstd.Zstd throws, and every subsequent call fails with
NoClassDefFoundError.

Steps to reproduce

On Windows x86-64, against a server new enough to return ZSTD-compressed blocks (26.x):

try (Connection conn = DriverManager.getConnection("jdbc:clickhouse://localhost:8123/", "default", "");
     Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT 1")) {
    rs.next();
}

No compression setting is applied — this is the default configuration.

Equivalently, mvn -pl jdbc-v2 verify -Dit.test=DatabaseMetaDataTest on Windows against the
latest image gives 44 of 47 failures, all from this one cause. The same command with
-DclickhouseVersion=25.8 passes 47/47, because that server does not send ZSTD blocks.

Error Log or Exception StackTrace

First failure — the class initializer:

java.lang.UnsatisfiedLinkError:
Failed to open resource /win/amd64/libzstd-jni-1.5.7-20.dll as stream:
Unsupported OS/arch, cannot find /win/amd64/libzstd-jni-1.5.7-20.dll or load zstd-jni-1.5.7-20
from system libraries. Please try building from source the jar or providing
libzstd-jni-1.5.7-20 in your system.
	at com.github.luben.zstd.util.Native.load(Native.java:124)
	at com.github.luben.zstd.util.Native.load(Native.java:93)
	at com.github.luben.zstd.Zstd.<clinit>(Zstd.java:22)
	at com.clickhouse.client.api.internal.CompressedBlockInputStream.refill(CompressedBlockInputStream.java:156)
	at com.clickhouse.client.api.internal.CompressedBlockInputStream.read(CompressedBlockInputStream.java:63)
	at com.clickhouse.client.api.data_formats.internal.BinaryStreamReader.readByteOrEOF(BinaryStreamReader.java:1555)
	at com.clickhouse.client.api.data_formats.RowBinaryWithNamesAndTypesFormatReader.readSchema(RowBinaryWithNamesAndTypesFormatReader.java:41)
	at com.clickhouse.client.api.Client.newBinaryFormatReader(Client.java:2451)
	at com.clickhouse.jdbc.StatementImpl.executeQueryImpl(StatementImpl.java:325)

Every later query in the same JVM:

java.lang.NoClassDefFoundError: Could not initialize class com.github.luben.zstd.Zstd
	at com.clickhouse.client.api.internal.CompressedBlockInputStream.refill(CompressedBlockInputStream.java:156)
	...
Expected Behaviour

The default configuration should work on every platform the driver supports. A JDBC driver
that cannot run SELECT 1 on Windows out of the box is unusable there, and the failure
surfaces as NoClassDefFoundError rather than anything a user can act on.

Root cause

Introduced in 9dc6a95 ("Added ZSTD block compression support"), merged as #3157, which
fixed #3105 and #3120. Those fixes are correct; only the choice of classifier is the
problem here. The
cloud classifier is published by zstd-jni for deployments that only ever run on Linux or
Apple-silicon containers; it is a size optimisation (1.0 MB vs 6.5 MB) and is not suitable
for a general-purpose client library.

Note that clickhouse-data, clickhouse-http-client and clickhouse-jdbc already depend
on the default zstd-jni artifact through dependencyManagement
(${zstd-jni.version}, currently 1.5.5-5, no classifier), so client-v2 is the only module
using the restricted jar, and it also pins its own version instead of the managed one.

Suggested fix

Preferred — drop the classifier and use the managed version, so the module matches the rest
of the project:

<dependency>
    <groupId>com.github.luben</groupId>
    <artifactId>zstd-jni</artifactId>
</dependency>

with <zstd-jni.version> in the parent raised to 1.5.7-20. Cost is roughly 5.5 MB of jar
size; correctness on Windows and Intel macOS seems worth that, and users who need the small
jar can still exclude it and substitute the cloud artifact themselves.

Independently of the dependency choice, CompressedBlockInputStream could fail more
usefully: catching UnsatisfiedLinkError / NoClassDefFoundError when ZSTD is first
touched and reporting that the native library is missing for this platform — naming the
compression.method setting — would turn an opaque NoClassDefFoundError into something
actionable, and would protect against the same class of problem in future.

A regression test would need a non-Linux runner; the CI matrix is Linux-only, which is why
this was not caught. At minimum, a unit test asserting that the resolved zstd-jni artifact
contains win/amd64 would catch a reintroduction without needing a Windows runner.

Configuration
Environment
  • Cloud
  • Client version: 0.11.0-rc1-SNAPSHOT (main at 16dcde46)
  • Language version: JDK 21 (compiled with release 17)
  • OS: Windows 11 x86-64
ClickHouse Server
  • ClickHouse Server version: clickhouse/clickhouse-server:latest via Testcontainers
  • ClickHouse Server non-default settings, if any: none
Lingua principale
Java
Stelle
1.6k
Fork
649
Merge medio
1g 20h
PR unite (30g)
39

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ClickHouse/clickhouse-java

Tutte le issue di ClickHouse/clickhouse-java

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.