chdb-io · wudidapaopao · Sep 21, 2026 · Sep 21, 2026 · Sep 21, 2026 · Sep 21, 2026
diff --git a/.github/workflows/rc-release.yml b/.github/workflows/rc-release.yml
@@ -0,0 +1,172 @@
+name: Maven RC release
+
+# RCs are published to GitHub Packages while Maven Central Publisher Pro is being arranged.
+# The permanent Maven coordinates are used from the first RC, so the later Central migration
+# changes only the repository URL, not users' dependencies.
+on:
+  push:
+    tags:
+      - 'v*-rc.*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing RC tag to build and publish
+        required: true
+        type: string
+
+concurrency:
+  group: rc-release-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  actions: read
+
+env:
+  MAVEN_ARGS: '--batch-mode --no-transfer-progress'
+
+jobs:
+  build:
+    name: build ${{ matrix.platform }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux-x86_64-gnu
+            runner: ubuntu-22.04
+          - platform: linux-aarch64-gnu
+            runner: ubuntu-22.04-arm
+          - platform: macos-aarch64
+            runner: macos-15
+          - platform: macos-x86_64
+            runner: macos-15-intel
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '11'
+          cache: maven
+
+      - name: Resolve and validate RC version
+        run: |
+          set -eu
+          TAG='${{ inputs.tag || github.ref_name }}'
+          case "$TAG" in
+            v*-rc.*) ;;
+            *) echo "Expected a tag like v1.0.0-rc.1, got $TAG" >&2; exit 1 ;;
+          esac
+          VERSION="${TAG#v}"
+          echo "RC_TAG=$TAG" >> "$GITHUB_ENV"
+          echo "RC_VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Set the Maven RC version
+        run: |
+          # shellcheck disable=SC2086
+          mvn $MAVEN_ARGS org.codehaus.mojo:versions-maven-plugin:2.17.0:set \
+            -DnewVersion="$RC_VERSION" -DgenerateBackupPoms=false
+
+      - name: Compile and run unit tests
+        run: |
+          # shellcheck disable=SC2086
+          mvn $MAVEN_ARGS -pl chdb-jdbc -am test
+
+      - name: Fetch the engine and build the native shim
+        run: |
+          case '${{ matrix.platform }}' in
+            linux-*) scripts/build-native-in-container.sh '${{ matrix.platform }}' ;;
+            *)       scripts/build-native.sh '${{ matrix.platform }}' ;;
+          esac
+
+      - 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
+          mkdir -p "maven/${{ matrix.platform }}"
+          cp "chdb-jdbc/target/chdb-jdbc-${RC_VERSION}.jar" "maven/${{ matrix.platform }}/"
+          cp "chdb-native-${{ matrix.platform }}/target/chdb-native-${{ matrix.platform }}-${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-native-${{ matrix.platform }}/pom.xml" "maven/${{ matrix.platform }}/chdb-native-${{ matrix.platform }}.pom"
+          cp chdb-bom/pom.xml "maven/${{ matrix.platform }}/chdb-bom.pom"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: maven-${{ matrix.platform }}
+          path: maven/${{ matrix.platform }}
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: publish RC to GitHub Packages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '11'
+          server-id: github
+          server-username: GITHUB_ACTOR
+          server-password: GITHUB_TOKEN
+
+      - name: Resolve RC version
+        run: |
+          TAG='${{ inputs.tag || github.ref_name }}'
+          case "$TAG" in
+            v*-rc.*) ;;
+            *) echo "Expected a tag like v1.0.0-rc.1, got $TAG" >&2; exit 1 ;;
+          esac
+          echo "RC_VERSION=${TAG#v}" >> "$GITHUB_ENV"
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: maven-*
+          path: maven
+
+      - name: Publish Maven artifacts
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_ACTOR: ${{ github.actor }}
+        run: |
+          set -eu
+          REPOSITORY_URL="https://maven.pkg.github.com/${GITHUB_REPOSITORY_OWNER,,}/chdb-java"
+          PARENT_POM=$(find maven -name chdb-java-parent.pom -print -quit)
+          JDBC_POM=$(find maven -name chdb-jdbc.pom -print -quit)
+          BOM_POM=$(find maven -name chdb-bom.pom -print -quit)
+
+          mvn $MAVEN_ARGS org.apache.maven.plugins:maven-deploy-plugin:3.1.3:deploy-file \
+            -Dfile="$PARENT_POM" -DgroupId=com.clickhouse.chdb -DartifactId=chdb-java-parent \
+            -Dversion="$RC_VERSION" -Dpackaging=pom -DgeneratePom=false \
+            -DrepositoryId=github -Durl="$REPOSITORY_URL"
+
+          mvn $MAVEN_ARGS org.apache.maven.plugins:maven-deploy-plugin:3.1.3:deploy-file \
+            -Dfile="$(find maven -name "chdb-jdbc-${RC_VERSION}.jar" -print -quit)" \
+            -DpomFile="$JDBC_POM" -DgeneratePom=false \
+            -DrepositoryId=github -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)
+            mvn $MAVEN_ARGS org.apache.maven.plugins:maven-deploy-plugin:3.1.3:deploy-file \
+              -Dfile="$NATIVE_JAR" -DpomFile="$NATIVE_POM" -DgeneratePom=false \
+              -DrepositoryId=github -Durl="$REPOSITORY_URL"
+          done
+
+          mvn $MAVEN_ARGS org.apache.maven.plugins:maven-deploy-plugin:3.1.3:deploy-file \
+            -Dfile="$BOM_POM" -DpomFile="$BOM_POM" -Dpackaging=pom \
+            -DgroupId=com.clickhouse.chdb -DartifactId=chdb-bom -Dversion="$RC_VERSION" \
+            -DgeneratePom=false \
+            -DrepositoryId=github -Durl="$REPOSITORY_URL"
diff --git a/CHDB_JAVA_V1_WORK_PLAN.md b/CHDB_JAVA_V1_WORK_PLAN.md
@@ -165,12 +165,12 @@ What "multiple ClassLoaders" means in V1: several child ClassLoaders can share o
 ### 4.1 V1 artifacts
 
 ```text
-org.chdb:chdb-jdbc:<version>
-org.chdb:chdb-native-linux-x86_64-gnu:<version>
-org.chdb:chdb-native-linux-aarch64-gnu:<version>
-org.chdb:chdb-native-macos-x86_64:<version>
-org.chdb:chdb-native-macos-aarch64:<version>
-org.chdb:chdb-bom:<version>
+com.clickhouse.chdb:chdb-jdbc:<version>
+com.clickhouse.chdb:chdb-native-linux-x86_64-gnu:<version>
+com.clickhouse.chdb:chdb-native-linux-aarch64-gnu:<version>
+com.clickhouse.chdb:chdb-native-macos-x86_64:<version>
+com.clickhouse.chdb:chdb-native-macos-aarch64:<version>
+com.clickhouse.chdb:chdb-bom:<version>
 ```
 
 - `chdb-jdbc`: the pure Java API, the JDBC implementation and the native loader. It does not contain the chDB engine.
@@ -219,16 +219,17 @@ a break in the Java API could ship as a trailing `.2`.
 | Fix in the driver, loader or JNI shim | `1.0.1` |
 | New engine baseline, no Java API change | `1.1.0` |
 | Breaking change to the Java API | `2.0.0` |
-| Preview of `1.0.0` | `1.0.0-preview.1` |
+| 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.
 - 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 a preview and cannot be V1 GA.
+- A binding built on an engine RC is an RC and cannot be V1 GA.
 - `-SNAPSHOT` is for development and never reaches Maven Central.
-- **`-preview.<n>` sorts *above* the release it previews.** Maven's `ComparableVersion` orders unknown qualifiers after the final release, so `1.0.0-preview.1` compares newer than `1.0.0` — measured, not assumed. It costs nothing here because previews are installed by hand into a local repository and never published beside a GA, and consumers name exact versions. If a preview ever has to live in a shared repository, use `-rc.<n>`, which Maven does order below the release.
+- **`-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.
 
 To remove string-parsing ambiguity, every artifact manifest records these separately:
 

diff --git a/README.md b/README.md
@@ -4,10 +4,9 @@ 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: pre-release.** V1 is under construction against the work plan in
-> [`CHDB_JAVA_V1_WORK_PLAN.md`](CHDB_JAVA_V1_WORK_PLAN.md). Nothing is on Maven Central yet
-> and the public API is not frozen; releases ship as
-> [preview bundles](#a-preview-from-a-github-release). See
+> **Status: release candidate.** The first Maven release candidate is `v1.0.0-rc.1`, built with
+> chDB Core `26.7.3`. RC artifacts are published to GitHub Packages until Maven Central is ready;
+> the public API is not frozen. See
 > [What works today](#what-works-today).
 
 ```java
@@ -58,35 +57,34 @@ on. The native package pulls in the driver, so declaring it alone is enough.
 
 ```xml
 <dependency>
-  <groupId>org.chdb</groupId>
+  <groupId>com.clickhouse.chdb</groupId>
   <artifactId>chdb-native-linux-x86_64-gnu</artifactId>
-  <version>1.0.0</version>
+  <version>1.0.0-rc.1</version>
 </dependency>
 ```
 
-**These coordinates do not resolve yet, and `org.chdb` is provisional** — nothing is on Maven
-Central, and the published group id may end up being `com.clickhouse`. See
-[docs/release-readiness.md](docs/release-readiness.md). Until then, install a preview.
+GitHub Packages requires a GitHub classic PAT with `read:packages` in `~/.m2/settings.xml`:
 
-### A preview from a GitHub Release
-
-Previews ship as one zip per platform, holding the same artifacts a Central release would:
-
-```bash
-curl -fsSL -o /tmp/install-chdb-java-preview.sh \
-  https://raw.githubusercontent.com/chdb-io/chdb-java/main/scripts/install-preview.sh
-chmod +x /tmp/install-chdb-java-preview.sh
-/tmp/install-chdb-java-preview.sh v1.0.0-preview.1
+```xml
+<settings>
+  <servers>
+    <server>
+      <id>github</id>
+      <username>YOUR_GITHUB_USERNAME</username>
+      <password>YOUR_GITHUB_PAT</password>
+    </server>
+  </servers>
+</settings>
 ```
 
-It downloads the bundle for this platform, verifies it against the release's `SHA256SUMS`,
-installs it with `mvn install-file`, and prints the coordinates. Use `--maven-repo PATH` for a
-repository other than `~/.m2/repository`. Then declare the dependency as above with
-`1.0.0-preview.1`; because the bundle carries its own POMs, a later change of group id does
-not strand an installed preview.
+Add the repository to the consuming project:
 
-Each preview tag is a commit on `main`, built and tested on all four platforms by
-[`preview-release.yml`](.github/workflows/preview-release.yml).
+```xml
+<repository>
+  <id>github</id>
+  <url>https://maven.pkg.github.com/chdb-io/chdb-java</url>
+</repository>
+```
 
 Building for several platforms — a CI matrix, or a distribution your users install on either
 architecture — declare the driver plus each native package you need:
@@ -95,7 +93,7 @@ architecture — declare the driver plus each native package you need:
 <dependencyManagement>
   <dependencies>
     <dependency>
-      <groupId>org.chdb</groupId>
+      <groupId>com.clickhouse.chdb</groupId>
       <artifactId>chdb-bom</artifactId>
       <version>1.0.0</version>
       <type>pom</type>
@@ -106,15 +104,15 @@ architecture — declare the driver plus each native package you need:
 
 <dependencies>
   <dependency>
-    <groupId>org.chdb</groupId>
+      <groupId>com.clickhouse.chdb</groupId>
     <artifactId>chdb-jdbc</artifactId>
   </dependency>
   <dependency>
-    <groupId>org.chdb</groupId>
+    <groupId>com.clickhouse.chdb</groupId>
     <artifactId>chdb-native-linux-x86_64-gnu</artifactId>
   </dependency>
   <dependency>
-    <groupId>org.chdb</groupId>
+    <groupId>com.clickhouse.chdb</groupId>
     <artifactId>chdb-native-macos-aarch64</artifactId>
   </dependency>
 </dependencies>
@@ -134,9 +132,9 @@ change to the Java API. The engine version is not part of it — it is in each p
 named in the release notes (`26.7.3` today), and the driver refuses to load any other build.
 See [work plan §4.3](CHDB_JAVA_V1_WORK_PLAN.md).
 
-A preview is that version with a `-preview.<n>` qualifier. Maven orders an unknown qualifier
-*after* the release, so `1.0.0-preview.1` compares newer than `1.0.0`: name the version you
-want rather than a range, and note that previews are never published beside a GA.
+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,
+so moving stable releases to Maven Central will not change dependency coordinates.
 
 ## Connecting
 

diff --git a/chdb-bom/pom.xml b/chdb-bom/pom.xml
@@ -5,9 +5,9 @@
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
-    <groupId>org.chdb</groupId>
+    <groupId>com.clickhouse.chdb</groupId>
     <artifactId>chdb-java-parent</artifactId>
-    <version>1.0.0-preview.1</version>
+    <version>1.0.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>chdb-bom</artifactId>
@@ -23,27 +23,27 @@
   <dependencyManagement>
     <dependencies>
       <dependency>
-        <groupId>org.chdb</groupId>
+        <groupId>com.clickhouse.chdb</groupId>
         <artifactId>chdb-jdbc</artifactId>
         <version>${project.version}</version>
       </dependency>
       <dependency>
-        <groupId>org.chdb</groupId>
+        <groupId>com.clickhouse.chdb</groupId>
         <artifactId>chdb-native-macos-aarch64</artifactId>
         <version>${project.version}</version>
       </dependency>
       <dependency>
-        <groupId>org.chdb</groupId>
+        <groupId>com.clickhouse.chdb</groupId>
         <artifactId>chdb-native-macos-x86_64</artifactId>
         <version>${project.version}</version>
       </dependency>
       <dependency>
-        <groupId>org.chdb</groupId>
+        <groupId>com.clickhouse.chdb</groupId>
         <artifactId>chdb-native-linux-x86_64-gnu</artifactId>
         <version>${project.version}</version>
       </dependency>
       <dependency>
-        <groupId>org.chdb</groupId>
+        <groupId>com.clickhouse.chdb</groupId>
         <artifactId>chdb-native-linux-aarch64-gnu</artifactId>
         <version>${project.version}</version>
       </dependency>

diff --git a/chdb-examples/pom.xml b/chdb-examples/pom.xml
@@ -5,9 +5,9 @@
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
-    <groupId>org.chdb</groupId>
+    <groupId>com.clickhouse.chdb</groupId>
     <artifactId>chdb-java-parent</artifactId>
-    <version>1.0.0-preview.1</version>
+    <version>1.0.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>chdb-examples</artifactId>
@@ -21,7 +21,7 @@
 
   <dependencies>
     <dependency>
-      <groupId>org.chdb</groupId>
+      <groupId>com.clickhouse.chdb</groupId>
       <artifactId>chdb-jdbc</artifactId>
       <version>${project.version}</version>
     </dependency>