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

Ouverte
  • Quelque chose ne va pas ?
#3,175 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
72/100
Type d'issue
Bug
Clarté
Clairement spécifiée
Activité
Active
Stack technique
java
Domaine
backend, databases

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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
Langage dominant
Java
Étoiles
1.6k
Forks
649
Merge moyen
1 j 20 h
PR mergées (30 j)
39

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de ClickHouse/clickhouse-java

Toutes les issues de ClickHouse/clickhouse-java

Issues similaires

Plus d'issues Java

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.