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
4 changes: 2 additions & 2 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -224,15 +224,15 @@ jobs:
fi

# The optional Arrow module uses Arrow Java's C Data JNI on the same staged
# release pair. All A1/A2 registration and A5 insert tests must run on rc.3;
# release pair. All Arrow registration and insert tests must run on this baseline;
# no local-engine or skipEngineVersionCheck override is allowed in PR CI.
if mvn $MAVEN_ARGS -pl chdb-arrow -am test \
-Djvm="$HOME_DIR/bin/java" \
-Dchdb.arrow.it=true \
-Dchdb.library.path="$LIBS" \
-DargLine=--add-opens=java.base/java.nio=ALL-UNNAMED \
-DfailIfNoTests=true; then
echo "Arrow Java $VERSION passed (see report for the separate core conversion regression)"
echo "Arrow Java $VERSION passed"
else
echo "::error::Arrow integration tests failed on Java $VERSION"
failed="$failed $VERSION-arrow"
Expand Down
30 changes: 28 additions & 2 deletions .github/workflows/rc-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ jobs:
- name: Compile and run unit tests
run: |
# shellcheck disable=SC2086
mvn $MAVEN_ARGS -pl chdb-jdbc -am test
mvn $MAVEN_ARGS -pl chdb-arrow -am test

- name: Fetch the engine and build the native shim
run: |
Expand All @@ -81,11 +81,29 @@ jobs:
*) scripts/build-native.sh '${{ matrix.platform }}' ;;
esac

- name: Test Arrow against the staged release pair
run: |
set -eu
exec </dev/null
case '${{ matrix.platform }}' in
macos-*) OS=macos ;;
*) OS=linux ;;
esac
case '${{ matrix.platform }}' in
*aarch64*) ARCH=aarch64 ;;
*) ARCH=x86_64 ;;
esac
LIBS="$PWD/chdb-native-${{ matrix.platform }}/target/native/META-INF/chdb/native/$OS/$ARCH"
mvn $MAVEN_ARGS -pl chdb-arrow -am test \
-Dchdb.arrow.it=true -Dchdb.library.path="$LIBS" \
-DargLine=--add-opens=java.base/java.nio=ALL-UNNAMED \
-DfailIfNoTests=true

- name: Package the JDBC and native artifacts
run: |
set -eu
# shellcheck disable=SC2086
mvn $MAVEN_ARGS -pl chdb-jdbc,chdb-native-${{ matrix.platform }} package -DskipTests
mvn $MAVEN_ARGS -pl chdb-arrow,chdb-native-${{ matrix.platform }} -am package -DskipTests
mkdir -p "maven/${{ matrix.platform }}"
cp "chdb-native-${{ matrix.platform }}/target/chdb-native-${{ matrix.platform }}-${RC_VERSION}.jar" "maven/${{ matrix.platform }}/"
cp "chdb-native-${{ matrix.platform }}/pom.xml" "maven/${{ matrix.platform }}/chdb-native-${{ matrix.platform }}.pom"
Expand All @@ -95,8 +113,10 @@ jobs:
# artifact download order.
if [ '${{ matrix.platform }}' = linux-x86_64-gnu ]; then
cp "chdb-jdbc/target/chdb-jdbc-${RC_VERSION}.jar" "maven/${{ matrix.platform }}/"
cp "chdb-arrow/target/chdb-arrow-${RC_VERSION}.jar" "maven/${{ matrix.platform }}/"
cp pom.xml "maven/${{ matrix.platform }}/chdb-java-parent.pom"
cp chdb-jdbc/pom.xml "maven/${{ matrix.platform }}/chdb-jdbc.pom"
cp chdb-arrow/pom.xml "maven/${{ matrix.platform }}/chdb-arrow.pom"
cp chdb-bom/pom.xml "maven/${{ matrix.platform }}/chdb-bom.pom"
fi

Expand Down Expand Up @@ -141,6 +161,7 @@ jobs:
REPOSITORY_URL="file://${GITHUB_WORKSPACE}/repository"
PARENT_POM=$(find maven -name chdb-java-parent.pom -print -quit)
JDBC_POM=$(find maven -name chdb-jdbc.pom -print -quit)
ARROW_POM=$(find maven -name chdb-arrow.pom -print -quit)
BOM_POM=$(find maven -name chdb-bom.pom -print -quit)

# shellcheck disable=SC2086
Expand All @@ -155,6 +176,11 @@ jobs:
-DpomFile="$JDBC_POM" -DgeneratePom=false \
-DrepositoryId=chdb-rc -Durl="$REPOSITORY_URL"

mvn $MAVEN_ARGS org.apache.maven.plugins:maven-deploy-plugin:3.1.3:deploy-file \
-Dfile="$(find maven -name "chdb-arrow-${RC_VERSION}.jar" -print -quit)" \
-DpomFile="$ARROW_POM" -DgeneratePom=false \
-DrepositoryId=chdb-rc -Durl="$REPOSITORY_URL"

for platform in macos-aarch64 macos-x86_64 linux-x86_64-gnu linux-aarch64-gnu; do
NATIVE_POM=$(find maven -name "chdb-native-${platform}.pom" -print -quit)
NATIVE_JAR=$(find maven -name "chdb-native-${platform}-${RC_VERSION}.jar" -print -quit)
Expand Down
7 changes: 6 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,7 @@ jobs:
# preflight already checked `build` was green: the staged bytes here are new bytes.
run: |
set -euo pipefail
exec </dev/null
case "${{ matrix.platform }}" in
macos-*) OS=macos ;;
*) OS=linux ;;
Expand All @@ -323,6 +324,10 @@ jobs:
mvn $MAVEN_ARGS -pl chdb-integration-tests -am verify \
-Dchdb.it.platform=${{ matrix.platform }} \
-Dchdb.it.library.path="$LIBS"
mvn $MAVEN_ARGS -pl chdb-arrow -am test \
-Dchdb.arrow.it=true -Dchdb.library.path="$LIBS" \
-DargLine=--add-opens=java.base/java.nio=ALL-UNNAMED \
-DfailIfNoTests=true

- name: Upload the staged platform package
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -482,7 +487,7 @@ jobs:
if [ "$DRY_RUN" = "true" ]; then GOAL=verify; fi
echo "mvn -Prelease $GOAL for $VERSION ($CHANNEL)"
mvn $MAVEN_ARGS -Prelease "$GOAL" \
-pl .,chdb-bom,chdb-jdbc,chdb-native-macos-aarch64,chdb-native-macos-x86_64,chdb-native-linux-x86_64-gnu,chdb-native-linux-aarch64-gnu
-pl .,chdb-bom,chdb-jdbc,chdb-arrow,chdb-native-macos-aarch64,chdb-native-macos-x86_64,chdb-native-linux-x86_64-gnu,chdb-native-linux-aarch64-gnu

- name: What was produced
if: always()
Expand Down
22 changes: 12 additions & 10 deletions CHDB_JAVA_V1_WORK_PLAN.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# chDB Java binding V1 work plan

> Status: Draft
> Updated: 2026-09-08
> Updated: 2026-11-17
> Target repository: `chdb-io/chdb-java`

## 1. Project goal
Expand Down Expand Up @@ -201,7 +201,8 @@ META-INF/sbom/

### 4.3 Versioning rules

The binding is versioned on its own, in SemVer — `MAJOR.MINOR.PATCH`, first release `1.0.0`.
The binding is versioned on its own, in SemVer — `MAJOR.MINOR.PATCH`. The first stable
release is `1.1.0` by the release owner's 2026-11-17 decision; `1.0.0` GA is skipped.
The number describes the Java API, which is the question a consumer asks it.

The engine version is not in it. It is recorded in each native package's
Expand All @@ -215,21 +216,22 @@ a break in the Java API could ship as a trailing `.2`.

| Case | Version |
|---|---|
| First release | `1.0.0` |
| Fix in the driver, loader or JNI shim | `1.0.1` |
| New engine baseline, no Java API change | `1.1.0` |
| First stable release | `1.1.0` |
| Fix in the driver, loader or JNI shim after it | `1.1.1` |
| Subsequent engine baseline with new capability | `1.2.0` |
| Breaking change to the Java API | `2.0.0` |
| First Maven RC / first test version | `1.0.0-rc.1` |

Release rules:

- A published artifact is immutable. Never overwrite `1.0.0`; any fix ships as `1.0.1`.
- `chdb-jdbc`, the four platform packages and `chdb-bom` always carry the same version.
- A published artifact is immutable. Never overwrite `1.1.0`; any fix ships as `1.1.1`.
- `chdb-jdbc`, optional `chdb-arrow`, the four platform packages and `chdb-bom` always carry the same version.
- An engine change is a `MINOR` bump when it changes what the driver can do and a `PATCH` when it does not. It is never invisible: the manifest and the release notes name the engine.
- A binding built on an engine RC is an RC and cannot be V1 GA.
- `-SNAPSHOT` is for development and never reaches Maven Central.
- **`-rc.<n>` is the shared-repository pre-release qualifier.** The first test version is
`1.0.0-rc.1`, followed by `1.0.0-rc.2` and then the stable `1.0.0` release.
- **`-rc.<n>` is the shared-repository pre-release qualifier.** `1.0.0-rc.1` and
`1.0.0-rc.2` were published as test versions; there will be no `1.0.0` GA. The next
stable release is `1.1.0`, after the V1 gates below are satisfied.

To remove string-parsing ambiguity, every artifact manifest records these separately:

Expand Down Expand Up @@ -523,7 +525,7 @@ Exit condition: a Java user who knows nothing about the implementation can insta
- [ ] Freeze the public Java API and the JNI ABI.
- [ ] Write the release notes and the known limitations.
- [ ] Publish an RC and hold a soak and external validation window of at least one week.
- [ ] Once every V1 release gate passes, publish the first release, `1.0.0`, built on a stable engine.
- [ ] Once every V1 release gate passes, publish the first stable release, `1.1.0`, built on a stable engine.

## 6. Milestones

Expand Down
23 changes: 11 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ 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 core `26.11.0-rc.3` and adds an
> optional `chdb-arrow` module; those Java artifacts have not been published. See the
> public API is not frozen. This development branch targets stable core `26.11.1` and adds an
> optional `chdb-arrow` module for the planned `v1.1.0` stable release; those artifacts have not
> been published. 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,7 +27,7 @@ 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 rc.3,
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:

| | Linux glibc | macOS |
Expand All @@ -43,13 +44,11 @@ but is not yet a published-platform claim:
engine does. Each package records the figure it was built against in its
`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.0-rc.3**, pinned. Published Java
- **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
refuses to run against a different engine build rather than risking a struct-layout mismatch.
That release is a chdb-core *pre-release*, pinned to validate the ClickHouse 26.11 baseline;
a binding on an engine RC is itself an RC and is not the V1 GA
([work plan §4.3](CHDB_JAVA_V1_WORK_PLAN.md)), so the stable chdb-core release has to be
pinned before `1.0.0`.
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)).
- **Not supported:** Windows, musl (Alpine), 32-bit, GraalVM Native Image, Android.

## Installing
Expand Down Expand Up @@ -115,14 +114,14 @@ all-platforms package, on purpose: it would be the sum of those four.

### Versioning

SemVer, on the binding alone: `1.0.0` is the first release and a major bump means a breaking
SemVer, on the binding alone: `1.1.0` is the first stable release and a major bump means a breaking
change to the Java API. The engine version is not part of it — it is in each package's
`manifest.properties`, pinned in [`scripts/engine.properties`](scripts/engine.properties) and
named in the release notes (`26.11.0-rc.2` for the published Java RC, `26.11.0-rc.3`
named in the release notes (`26.11.0-rc.2` for the published Java RC, `26.11.1`
in this development branch), and the driver refuses to load any other build.

The first test version is the RC `1.0.0-rc.1`; later candidates increment the final number, and
the first stable Maven release is `1.0.0`. RCs use the permanent `com.clickhouse.chdb` groupId,
The first test versions were `1.0.0-rc.1` and `1.0.0-rc.2`; `1.0.0` GA is intentionally skipped.
The first stable Maven release is planned as `1.1.0`. RCs use the permanent `com.clickhouse.chdb` groupId,
so publishing stable releases to Maven Central will not change dependency coordinates.

## Connecting
Expand Down
14 changes: 7 additions & 7 deletions chdb-arrow/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This module README is the Java binding's Arrow entry point. See the [core owners

`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.0.0-rc.3-SNAPSHOT` Java and native artifacts from this checkout (see
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
**one** native package for its runtime platform, at the same binding version:
Expand All @@ -29,13 +29,13 @@ artifacts is available, a Maven consumer needs the optional Arrow module and
<dependency>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-arrow</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</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.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</dependency>
</dependencies>
```
Expand Down Expand Up @@ -233,9 +233,9 @@ published Java `1.0.0-rc.2` platform JAR has JNI ABI 2 and cannot run this work-
ABI 5 module. Arrow Java 19.0.0 on classpath also requires
`--add-opens=java.base/java.nio=ALL-UNNAMED` on supported JDKs.

The current source pins chDB core `26.11.0-rc.3`. For a macOS arm64 release-asset
The current source pins stable chDB core `26.11.1`. For a macOS arm64 release-asset
smoke test, compile the Java side (`mvn -pl chdb-jdbc -am compile`), then run
`scripts/build-native.sh macos-aarch64`. That script downloads the exact rc.3 asset,
`scripts/build-native.sh macos-aarch64`. That script downloads the exact v26.11.1 asset,
verifies its SHA-256 and stages the engine plus JNI shim in
`chdb-native-macos-aarch64/target/native/`. Run the opt-in test with the staged pair:

Expand All @@ -257,8 +257,8 @@ Choose the corresponding native module if building on another supported
platform, and run its `scripts/build-native.sh <platform-id>` first.

The earlier core `26.11.0-rc.2` omitted a `get_schema` release during registration:
a value-correct Java scan left 148 bytes in the Arrow allocator. The rc.3 release
includes that fix, so the Arrow input and insert tests run on this baseline. CI exercises the
a value-correct Java scan left 148 bytes in the Arrow allocator. The later rc.3 fix
is included in v26.11.1, so the Arrow input and insert tests run on this baseline. CI exercises the
same suite on all four native platforms and Java 11/17/21/25 without a version
override. No production deployment should use a local `--local-engine` package or
`chdb.skipEngineVersionCheck`.
2 changes: 1 addition & 1 deletion chdb-arrow/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<parent>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-java-parent</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</parent>
<artifactId>chdb-arrow</artifactId>
<name>chDB Arrow</name>
Expand Down
2 changes: 1 addition & 1 deletion chdb-bom/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-java-parent</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</parent>

<artifactId>chdb-bom</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion chdb-examples/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-java-parent</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</parent>

<artifactId>chdb-examples</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion chdb-integration-tests/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-java-parent</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</parent>

<artifactId>chdb-integration-tests</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion chdb-jdbc/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.clickhouse.chdb</groupId>
<artifactId>chdb-java-parent</artifactId>
<version>1.0.0-rc.3-SNAPSHOT</version>
<version>1.1.0-SNAPSHOT</version>
</parent>

<artifactId>chdb-jdbc</artifactId>
Expand Down
6 changes: 3 additions & 3 deletions chdb-jdbc/src/main/java/org/chdb/internal/ChdbNative.java
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ private ChdbNative() {
/** ABI version the loaded shim was built with. */
public static native int jniAbiVersion();

/** {@code chdb_version()} of the loaded libchdb, e.g. {@code "26.11.0-rc.3"}. */
/** {@code chdb_version()} of the loaded libchdb, e.g. {@code "26.11.1"}. */
public static native String engineVersion();

/** Build provenance of the shim: git commit, compiler, engine headers it compiled against. */
Expand Down Expand Up @@ -180,7 +180,7 @@ public static native long insertArrowStreamWithOptions(
* {@code chdb_classify_query_n}. Decides whether a statement has a result set to stream
* without executing it, using the engine's own parser.
*
* <p>Optional symbol: it landed in chdb-core v26.7.2-rc.2, so the pinned v26.11.0-rc.3
* <p>Optional symbol: it landed in chdb-core v26.7.2-rc.2, so the pinned v26.11.1
* baseline has it, so it is resolved by {@code dlsym} rather than linked. It is present on
* the baseline; the null path is what an older engine gets, and means the caller must fall
* back to {@code StatementShape}'s own analysis.
Expand Down Expand Up @@ -242,7 +242,7 @@ public static native long rowBinaryOpen(
* every result destroyed first, and the engine cannot be used again in this process.
*
* <p>Optional symbol, like {@link #classifyQuery(long, byte[])}: it landed in chdb-core
* v26.7.2-rc.2, so the pinned v26.11.0-rc.3 baseline has it, and it is resolved by {@code
* v26.7.2-rc.2, so the pinned v26.11.1 baseline has it, and it is resolved by {@code
* dlsym} rather than linked. Not having it is not a failure -- the threads it would join are
* reaped by process exit either way.
*
Expand Down
2 changes: 1 addition & 1 deletion chdb-jdbc/src/main/java/org/chdb/jdbc/ChdbStatement.java
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,7 @@ private void checkDeadlineSurvivedTheOpen(String sql) throws SQLException {
private StatementShape.Route route(String sql) throws SQLException {
int[] analysis;
try {
// Null when the engine predates chdb_classify_query_n, which the v26.11.0-rc.3
// Null when the engine predates chdb_classify_query_n, which the v26.11.1
// baseline does not -- but a loader pointed at another libchdb still can, in which
// case StatementShape falls back to its keyword scan.
analysis = ChdbNative.classifyQuery(connection.handle(), Utf8.encode(sql));
Expand Down
2 changes: 1 addition & 1 deletion chdb-jdbc/src/main/java/org/chdb/jdbc/StatementShape.java
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
* <ol>
* <li>{@code chdb_classify_query_n}, which parses the SQL with the engine's own parser and
* settings and executes nothing. Available from engine v26.7.2-rc.2, so present on the
* pinned v26.11.0-rc.3 baseline and asked in practice. Authoritative about
* pinned v26.11.1 baseline and asked in practice. Authoritative about
* <em>whether</em> there is a result set, but silent on <em>which door</em> delivers it:
* {@code CHDB_QUERY_READ_ONLY} covers a {@code SELECT} and a {@code SHOW} alike, so it
* cannot tell the two entry points apart. See {@link #route(int[], String)}.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
* an entry point that refuses it -- which is what issue #12 was -- so all three are covered in
* both directions.
*
* <p>The pinned v26.11.0-rc.3 baseline does export chdb_classify_query_n, so the scan is no
* <p>The pinned v26.11.1 baseline does export chdb_classify_query_n, so the scan is no
* longer the only thing deciding. It is still what decides whether a result set is streamed or
* materialized, because the classifier does not distinguish those, as well as
* deciding both halves whenever the classifier is absent or refuses the text -- hence the cases
Expand Down
Loading
Loading