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

Đang mở
  • Có gì không ổn?
#3,175 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
72/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
java
Lĩnh vực
backend, databases

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
Java
Star
1.6k
Fork
649
Merge trung bình
1 ngày 20 giờ
Pull request đã merge (30 ngày)
39

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của ClickHouse/clickhouse-java

Tất cả issue của ClickHouse/clickhouse-java

Issue tương tự

Thêm issue về Java

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.