From 54363e23d9f3c899b86aed0689c6066613d4c14e Mon Sep 17 00:00:00 2001 From: Shawn Chen Date: Mon, 21 Sep 2026 02:11:07 +0000 Subject: [PATCH 1/2] Open the README with an example that runs, and needs no network The first snippet had no imports, no main, no run line, and queried a URL over the network three lines under a sentence saying there is none. It also never said that a native package has to match the platform, which is the one thing a first run gets wrong. Now: a complete file that prints 1, the classpath it needs, the four platform artifact ids, and a link to QuickStart.java for the longer version. The url() example stays, one line further down, where it can say what it is -- the engine is in-process, the data need not be. Extracted from the README and run before committing. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 39 ++++++++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6903a21..2ab6708 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,42 @@ streaming, forward-only result sets over ClickHouse SQL. > [What works today](#what-works-today). ```java -try (Connection connection = DriverManager.getConnection("jdbc:chdb::memory:"); - PreparedStatement statement = connection.prepareStatement( - "SELECT count() FROM url(?, 'JSONEachRow') WHERE status = 200")) { - statement.setString(1, "https://example.com/logs.jsonl"); - try (ResultSet rs = statement.executeQuery()) { - rs.next(); - System.out.println(rs.getLong(1)); +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.ResultSet; +import java.sql.Statement; + +public class Hello { + public static void main(String[] args) throws Exception { + try (Connection connection = DriverManager.getConnection("jdbc:chdb::memory:"); + Statement statement = connection.createStatement(); + ResultSet results = statement.executeQuery("SELECT 1")) { + results.next(); + System.out.println(results.getInt(1)); + } } } ``` +```bash +java -cp chdb-jdbc.jar:chdb-native-.jar Hello +``` + +No `Class.forName`: the driver registers itself. You need the driver **and the native package +for the platform you run on** — `chdb-native-linux-x86_64-gnu`, `chdb-native-linux-aarch64-gnu`, +`chdb-native-macos-aarch64` or `chdb-native-macos-x86_64`. See [Installing](#installing). + +A query can still reach the network when you ask it to — it is the engine that is in-process, +not the data: + +```java +"SELECT count() FROM url('https://example.com/logs.jsonl', 'JSONEachRow') WHERE status = 200" +``` + +[`QuickStart.java`](chdb-examples/src/main/java/org/chdb/examples/QuickStart.java) is the +longer version — parameters, types, streaming — runnable from a source checkout with +`mvn -pl chdb-examples exec:java -Dexec.mainClass=org.chdb.examples.QuickStart`. + ## Support matrix Every one of the four platforms builds, passes the full test suite on Java 11, 17, 21 and 25, From 4a5744d316d8ab330a48ccc8f7823901a7c8c336 Mon Sep 17 00:00:00 2001 From: Shawn Chen Date: Mon, 21 Sep 2026 02:14:34 +0000 Subject: [PATCH 2/2] Make the README's run commands ones that work Review of #30, all three right. The jars in a bundle carry versions, so bare chdb-jdbc.jar names nothing; `java -cp` without `.` cannot find Hello.class even when it exists; and the class was never compiled. The QuickStart line had the same shape of problem -- exec:java in a fresh checkout has no native package to load -- so it now carries the full sequence from QuickStart's own javadoc. Run verbatim against an installed preview before committing: javac, then java with the versioned jar names, prints 1. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2ab6708..12a9fd3 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,15 @@ public class Hello { ``` ```bash -java -cp chdb-jdbc.jar:chdb-native-.jar Hello +javac Hello.java +java -cp .:chdb-jdbc-.jar:chdb-native--.jar Hello ``` No `Class.forName`: the driver registers itself. You need the driver **and the native package for the platform you run on** — `chdb-native-linux-x86_64-gnu`, `chdb-native-linux-aarch64-gnu`, -`chdb-native-macos-aarch64` or `chdb-native-macos-x86_64`. See [Installing](#installing). +`chdb-native-macos-aarch64` or `chdb-native-macos-x86_64`. See [Installing](#installing), which +is where those jars come from; in a Maven project, declare the native package and skip the +classpath entirely. A query can still reach the network when you ask it to — it is the engine that is in-process, not the data: @@ -44,8 +47,15 @@ not the data: ``` [`QuickStart.java`](chdb-examples/src/main/java/org/chdb/examples/QuickStart.java) is the -longer version — parameters, types, streaming — runnable from a source checkout with -`mvn -pl chdb-examples exec:java -Dexec.mainClass=org.chdb.examples.QuickStart`. +longer version — parameters, types, streaming. From a source checkout it needs the native +package built first ([Building from source](#building-from-source)): + +```bash +mvn -pl chdb-jdbc compile +scripts/build-native.sh +mvn -pl chdb-examples -am compile +mvn -pl chdb-examples exec:java -Dexec.mainClass=org.chdb.examples.QuickStart +``` ## Support matrix