docs(tests): add ClickHouse installation instructions and fix test co…

…ntext - Update CLAUDE.md with ClickHouse installation instructions using official repository (Ubuntu packages have incompatible old version) - Add ClickHouse test context to endtoend_test.go with schema migration support - Import clickhouse-go v2 driver and database/sql for test context - Add test filtering to only run ClickHouse tests under clickhouse context - Add generated test output files for clickhouse_authors test case 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
sqlc-dev · kyleconroy · Dec 24, 2025 · Dec 24, 2025 · Dec 24, 2025 · Dec 24, 2025
commit ff082bd062b9f4c6c042a329b10d107cb73208ab
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -87,9 +87,45 @@ Test the connection:
 mysql -h 127.0.0.1 -u root -pmysecretpassword -e "SELECT VERSION();"
 ```
 
-### Step 4: Run End-to-End Tests
+### Step 4: Install ClickHouse (Optional - for ClickHouse tests)
 
-With both databases running, the test framework automatically detects them:
+ClickHouse is required for ClickHouse engine tests. The ClickHouse feature is experimental and requires the `SQLCEXPERIMENT=clickhouse` flag.
+
+**Important:** Use the official ClickHouse repository, not the Ubuntu package (which has an old incompatible version).
+
+```bash
+# Add ClickHouse official repository key and source
+curl -fsSL https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
+ARCH=$(dpkg --print-architecture)
+echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
+
+# Install ClickHouse from official repo
+sudo apt-get update
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y clickhouse-server clickhouse-client
+
+# Start ClickHouse server
+sudo clickhouse start
+```
+
+Test the connection:
+
+```bash
+clickhouse-client --query "SELECT version()"
+```
+
+The native database support automatically detects ClickHouse and uses:
+- URI: `clickhouse://default:@localhost:9000/default`
+- User: `default` (no password)
+- Port: 9000
+
+**Note:** ClickHouse tests require setting the experiment flag:
+```bash
+SQLCEXPERIMENT=clickhouse go test ./internal/endtoend -run "TestReplay/clickhouse" -v
+```
+
+### Step 5: Run End-to-End Tests
+
+With the databases running, the test framework automatically detects them:
 
 ```bash
 # Run all end-to-end tests
@@ -103,11 +139,12 @@ go test --tags=examples -timeout 20m ./...
 ```
 
 The native database support (in `internal/sqltest/native/`) automatically:
-- Detects running PostgreSQL and MySQL instances
+- Detects running PostgreSQL, MySQL, and ClickHouse instances
 - Starts services if installed but not running
 - Uses standard connection URIs:
   - PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`
   - MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`
+  - ClickHouse: `clickhouse://default:@localhost:9000/default`
 
 ### Running Tests
 
@@ -193,6 +230,11 @@ The `docker-compose.yml` provides test databases:
   - Password: `mysecretpassword`
   - Database: `dinotest`
 
+- **ClickHouse** - Port 9000 (experimental, requires `SQLCEXPERIMENT=clickhouse`)
+  - User: `default`
+  - Password: (none)
+  - Database: `default`
+
 ### Managing Databases
 
 ```bash
@@ -291,6 +333,7 @@ POSTGRESQL_SERVER_URI="postgres://postgres:mysecretpassword@localhost:5432/postg
   - `/postgresql/` - PostgreSQL parser and converter
   - `/dolphin/` - MySQL parser (uses TiDB parser)
   - `/sqlite/` - SQLite parser
+  - `/clickhouse/` - ClickHouse parser (uses doubleclick parser, experimental)
 - `/internal/compiler/` - Query compilation logic
 - `/internal/codegen/` - Code generation for different languages
 - `/internal/config/` - Configuration file parsing

diff --git a/internal/endtoend/endtoend_test.go b/internal/endtoend/endtoend_test.go
@@ -3,6 +3,7 @@ package main
 import (
 	"bytes"
 	"context"
+	"database/sql"
 	"os"
 	osexec "os/exec"
 	"path/filepath"
@@ -11,6 +12,7 @@ import (
 	"strings"
 	"testing"
 
+	_ "github.com/ClickHouse/clickhouse-go/v2" // ClickHouse driver
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 
@@ -238,6 +240,39 @@ func TestReplay(t *testing.T) {
 							c.SQL[i].Database = &config.Database{
 								URI: clickhouseURI,
 							}
+							// Apply schema migrations to ClickHouse
+							for _, schemaPath := range c.SQL[i].Schema {
+								fullPath := filepath.Join(path, schemaPath)
+								schemaSQL, err := os.ReadFile(fullPath)
+								if err != nil {
+									t.Logf("Failed to read schema %s: %v", fullPath, err)
+									continue
+								}
+								db, err := sql.Open("clickhouse", clickhouseURI)
+								if err != nil {
+									t.Logf("Failed to connect to ClickHouse: %v", err)
+									continue
+								}
+								// Execute each statement separately
+								for _, stmt := range strings.Split(string(schemaSQL), ";") {
+									stmt = strings.TrimSpace(stmt)
+									if stmt == "" {
+										continue
+									}
+									// Drop table first if this is a CREATE TABLE statement
+									if strings.HasPrefix(strings.ToUpper(stmt), "CREATE TABLE") {
+										parts := strings.Fields(stmt)
+										if len(parts) >= 3 {
+											tableName := strings.TrimSuffix(parts[2], "(")
+											db.Exec("DROP TABLE IF EXISTS " + tableName)
+										}
+									}
+									if _, err := db.Exec(stmt); err != nil {
+										t.Logf("Failed to apply schema: %v", err)
+									}
+								}
+								db.Close()
+							}
 						}
 					}
 				}
@@ -281,6 +316,12 @@ func TestReplay(t *testing.T) {
 					if !slices.Contains(args.Contexts, name) {
 						t.Skipf("unsupported context: %s", name)
 					}
+				} else if name == "clickhouse" {
+					// For clickhouse context, only run tests that explicitly include it
+					// or that have ClickHouse engine (checked by having "clickhouse" in path)
+					if !strings.Contains(tc.Name, "clickhouse") {
+						t.Skipf("clickhouse context: skipping non-clickhouse test")
+					}
 				}
 
 				if len(args.OS) > 0 {

diff --git a/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/db.go b/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/db.go
diff --git a/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/models.go b/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/models.go
diff --git a/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/query.sql.go b/internal/endtoend/testdata/clickhouse_authors/clickhouse/stdlib/go/query.sql.go