Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@ A JDBC driver for [chDB](https://github.com/chdb-io/chdb-core), the embedded bui
ClickHouse. It runs the engine in your JVM's process — no server, no network — and gives you
streaming, forward-only result sets over ClickHouse SQL.

> **Status: release candidate.** The current Maven release candidate is `v1.0.0-rc.2`, built with
> chDB Core `26.11.0-rc.2`. RC artifacts are available from the public chDB Maven repository; the
> public API is not frozen. This development branch targets stable core `26.11.1` and adds an
> optional `chdb-arrow` module for the proposed `v1.1.0-rc.1` validation release ahead of
> `v1.1.0` stable; those artifacts are not published yet. See the
> **Status: release candidate.** The current Maven release candidate is `v1.1.0-rc.1`, built
> with stable chDB Core `26.11.1` and including the optional `chdb-arrow` module. It is
> available from the public chDB Maven repository; the public API is not frozen. The stable
> `v1.1.0` release remains gated. See the
> [Arrow Java getting-started guide](chdb-arrow/README.md#getting-started) for examples
> and [What works today](#what-works-today) for the JDBC release status.

Expand All @@ -26,9 +25,9 @@ try (Connection connection = DriverManager.getConnection("jdbc:chdb::memory:");

## Support matrix

The existing JDBC binding has built and passed its full suite on these four platforms and
Java 11, 17, 21 and 25 in CI. The new Arrow module is added to the PR matrix for `1.1.0`,
but is not yet a published-platform claim:
The JDBC and Arrow suites pass on these four platforms in CI, with Java 11, 17, 21 and 25
covered by the branch build matrix. The tagged RC also built and tested all four native pairs;
the published macOS arm64 artifact was independently consumed from `maven.chdb.io`:

| | Linux glibc | macOS |
|---|---|---|
Expand All @@ -45,7 +44,8 @@ but is not yet a published-platform claim:
`manifest.properties`, and CI runs the whole test suite on AlmaLinux 8 to demonstrate the
floor rather than infer it from symbol versions.
- **Engine in this source branch:** chDB Core **26.11.1**, pinned. Published Java
`1.0.0-rc.2` still uses core `26.11.0-rc.2`. The C ABI is version-locked, so the driver
`1.1.0-rc.1` uses this core; the older `1.0.0-rc.2` uses `26.11.0-rc.2`. The C ABI is
version-locked, so the driver
refuses to run against a different engine build rather than risking a struct-layout mismatch.
This stable core meets the engine-release requirement for the planned Java `1.1.0`, but the
remaining Java release gates still apply ([work plan §4.3](CHDB_JAVA_V1_WORK_PLAN.md)).
Expand All @@ -60,7 +60,7 @@ on. The native package pulls in the driver, so declaring it alone is enough.
<dependency>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-native-linux-x86_64-gnu</artifactId>
<version>1.0.0-rc.2</version>
<version>1.1.0-rc.1</version>
</dependency>
```

Expand All @@ -82,7 +82,7 @@ architecture — declare the driver plus each native package you need:
<dependency>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-bom</artifactId>
<version>1.0.0-rc.2</version>
<version>1.1.0-rc.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
Expand All @@ -107,10 +107,9 @@ architecture — declare the driver plus each native package you need:

The BOM keeps the driver and every native package on one version, which they must be.

**A native package is large**, because it contains the whole engine: 112 MB for macOS arm64,
144 MB for macOS x86_64, 158 MB for Linux aarch64 and 177 MB for Linux x86_64 on engine
26.11.0-rc.2 (unchanged from rc.1), and about 350 to 545 MB unpacked. There is no
all-platforms package, on purpose: it would be the sum of those four.
**A native package is large**, because it contains the whole engine: about 110 MiB for macOS
arm64, 127 MiB for macOS x86_64, 157 MiB for Linux aarch64 and 176 MiB for Linux x86_64
in `1.1.0-rc.1`. There is no all-platforms package, on purpose: it would be the sum of those four.

### Versioning

Expand Down
27 changes: 17 additions & 10 deletions chdb-arrow/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,25 +17,32 @@ This module README is the Java binding's Arrow entry point. See the [core owners

## Getting started

`chdb-arrow` is **not published yet**. The published Java `1.0.0-rc.2` and its
native packages cannot run this branch's Arrow API. To try it now, build the
matching `1.1.0-SNAPSHOT` Java and native artifacts from this checkout (see
[Testing from source](#testing-from-source) below). Once a matching set of
artifacts is available, a Maven consumer needs the optional Arrow module and
`chdb-arrow` is published as `1.1.0-rc.1` at `https://maven.chdb.io`. The older
`1.0.0-rc.2` native packages cannot run this Arrow module: keep all binding
artifacts on the same version. Add the public repository (no credentials required):

```xml
<repository>
<id>chdb-rc</id>
<url>https://maven.chdb.io</url>
</repository>
```

A Maven consumer needs the optional Arrow module and
**one** native package for its runtime platform, at the same binding version:

```xml
<dependencies>
<dependency>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-arrow</artifactId>
<version>1.1.0-SNAPSHOT</version>
<version>1.1.0-rc.1</version>
</dependency>
<!-- Example for macOS arm64; choose the package for your runtime platform. -->
<dependency>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-native-macos-aarch64</artifactId>
<version>1.1.0-SNAPSHOT</version>
<version>1.1.0-rc.1</version>
</dependency>
</dependencies>
```
Expand Down Expand Up @@ -228,9 +235,9 @@ associated copy/allocation cost.
## Testing from source

The test `ArrowSessionTest` is opt-in (`-Dchdb.arrow.it=true`) and requires a matching
engine and JNI shim in the directory given by `-Dchdb.library.path`. The previously
published Java `1.0.0-rc.2` platform JAR has JNI ABI 2 and cannot run this work-in-progress
ABI 5 module. Arrow Java 19.0.0 on classpath also requires
engine and JNI shim in the directory given by `-Dchdb.library.path`. The published
`1.1.0-rc.1` platform JAR has JNI ABI 5; the older `1.0.0-rc.2` ABI 2 package is not
interchangeable. Arrow Java 19.0.0 on classpath also requires
`--add-opens=java.base/java.nio=ALL-UNNAMED` on supported JDKs.

The current source pins stable chDB core `26.11.1`. For a macOS arm64 release-asset
Expand Down
11 changes: 8 additions & 3 deletions docs/publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,9 +405,9 @@ Each step can invalidate the next, so:

## 8. RCs on maven.chdb.io

`1.0.0-rc.1` and `1.0.0-rc.2` were earlier test versions. The next proposed test version is
`v1.1.0-rc.1`, before the planned `v1.1.0` stable release. The development POMs stay at
`1.1.0-SNAPSHOT`; `.github/workflows/rc-release.yml` derives `1.1.0-rc.1` from the tag and
`1.0.0-rc.1` and `1.0.0-rc.2` were earlier test versions. `v1.1.0-rc.1` was published to
`maven.chdb.io` on 2026-11-17, before the planned `v1.1.0` stable release. The development
POMs stay at `1.1.0-SNAPSHOT`; `.github/workflows/rc-release.yml` derives `1.1.0-rc.1` from the tag and
sets it in the build workspace. The Central release workflow explicitly excludes `-rc.*`
tags, so the same tag cannot start both publication routes.

Expand All @@ -418,6 +418,11 @@ inspecting that artifact, use the [Vercel Maven gateway runbook](../deploy/verce
to upload it manually. `scripts/publish-rc-repository.sh` checks all versioned paths before
upload and refuses to overwrite a previously published artifact.

The [RC build](https://github.com/chdb-io/chdb-java/actions/runs/43980175644) passed on all
four platforms. Its 70 immutable Maven files were uploaded manually; the public copies of
all 14 JAR/POM files matched the staged SHA-256 values, and a fresh-cache macOS arm64 consumer
ran JDBC and Arrow against the published `1.1.0-rc.1` package.

Consumers add `https://maven.chdb.io` as a Maven repository and specify the exact RC version;
no GitHub PAT is needed. This RC remains a pre-release and does not satisfy the stable release
gates in `docs/release-readiness.md`.
11 changes: 7 additions & 4 deletions docs/v1-progress.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,10 @@ green.

The baseline subsequently moved to **engine 26.7.2-rc.2** (issue #8), **26.7.3**,
**26.11.0-rc.1** and **26.11.0-rc.2**. This development branch now targets
**26.11.1**, the stable release after the Arrow registration fixes. The sixteen-way result
above describes 26.7.0; the new baseline needs its own four-platform CI matrix.
**26.11.1**, the stable release after the Arrow registration fixes. The `1.1.0-rc.1` tag
passed its four-platform build and Arrow checks, and its Maven repository was published on
2026-11-17. The older sixteen-way result above describes 26.7.0; the new baseline also passed
the main branch Java 11/17/21/25 platform matrix before tagging.

26.7.3 is a **stable** chdb-core release, which cleared the [work plan §4.3
](../CHDB_JAVA_V1_WORK_PLAN.md) bar that 26.7.2-rc.2 could not: a binding built on an engine
Expand All @@ -37,8 +39,9 @@ has to be pinned before the first stable Java version (now planned as `1.1.0`).
zero and `stress` survives 6 of 6 on Linux x86_64.

26.11.0-rc.3 includes chdb-core #323's Arrow registration-schema and failed array-wrapper
cleanup fixes. Stable v26.11.1 includes them. The optional `chdb-arrow` module is being
prepared for the next Java RC; local macOS arm64 tests do not substitute for its four-platform CI run.
cleanup fixes. Stable v26.11.1 includes them. The optional `chdb-arrow` module is included in
published Java `1.1.0-rc.1`; its four-platform RC tests passed, and a public Maven macOS arm64
consumer check completed after upload.

---

Expand Down
Loading