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

Aberta
  • Algo errado?
#3,175 1 comentário 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
72/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
java
Domínio
backend, databases

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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
Linguagem predominante
Java
Estrelas
1.6k
Forks
649
Merge médio
1d 20h
PRs com merge (30d)
39

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de ClickHouse/clickhouse-java

Todas as issues de ClickHouse/clickhouse-java

Issues semelhantes

Mais issues de Java

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.