examples: make the examples a module of their own, and run Spanner Omni in CI

The examples' drivers were becoming dependencies of sqlc itself, and the
DuckDB driver, being cgo, had to live in a module apart. Move every
example into one module under examples/, which requires sqlc through a
replace, so the drivers are its dependencies alone and cgo can stay on
for all of it; sqlc's own go.mod loses them, and lib/pq with them, since
only the examples imported it. The DuckDB example rejoins the authors
example beside the others, and the test helpers for ClickHouse, SQL
Server and Spanner move into the examples module, since the drivers they
need are what kept them out of sqlc. The end-to-end suite skips the
directory under examples that holds those helpers rather than treating
it as an example.

sqlc-test-setup now installs Spanner Omni from its standalone server
release, checked against a pinned SHA-256, and starts a single server in
the background on port 15000, so CI runs the Spanner example against it
alongside the ClickHouse and SQL Server services. The Makefile and CI
run the examples from their module.

Drop the clearing of a column's type expression in combineAnalysis: the
compiler builds a live-database analyzer only on the legacy path and
returns before doing so on the core path, so the two never meet and the
expression is never set where the analyzer runs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015rfiHyC4iRLyRWc3UmYEtT

Author: claude

.github/workflows/ci.yml

@@ -67,6 +67,8 @@ jobs:
       run: go build ./...
       working-directory: internal/endtoend/testdata
 
+    # Installs and starts PostgreSQL, MySQL and Spanner Omni; ClickHouse and
+    # SQL Server run as services above.
     - name: install databases
       run: go run ./cmd/sqlc-test-setup install
 
@@ -83,13 +85,20 @@ jobs:
         MYSQL_SERVER_URI: "root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true"
         CLICKHOUSE_SERVER_URI: "clickhouse://default:mysecretpassword@127.0.0.1:9000"
         MSSQL_SERVER_URI: "sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable"
+        SPANNER_SERVER_URI: "localhost:15000"
         CGO_ENABLED: "0"
 
-    # The DuckDB example is its own module: its driver is cgo, which the
-    # main module's builds keep off.
-    - name: test examples/duckdb
+    # The examples are a module of their own, so their drivers are not
+    # dependencies of sqlc, and cgo stays on for the DuckDB driver.
+    - name: test examples
       run: go test --tags=examples ./...
-      working-directory: examples/duckdb
+      working-directory: examples
+      env:
+        POSTGRESQL_SERVER_URI: "postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable"
+        MYSQL_SERVER_URI: "root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true"
+        CLICKHOUSE_SERVER_URI: "clickhouse://default:mysecretpassword@127.0.0.1:9000"
+        MSSQL_SERVER_URI: "sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable"
+        SPANNER_SERVER_URI: "localhost:15000"
 
   vuln_check:
     runs-on: ubuntu-24.04

CLAUDE.md

@@ -12,7 +12,7 @@ This document provides essential information for working with the sqlc codebase,
 
 ## Database Setup with sqlc-test-setup
 
-The `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL and MySQL for tests. Both commands are idempotent and safe to re-run.
+The `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL, MySQL and Spanner Omni for tests. Both commands are idempotent and safe to re-run.
 
 ### Install databases
 
@@ -24,6 +24,7 @@ This will:
 - Configure the apt proxy (if `http_proxy` is set, e.g. in Claude Code remote environments)
 - Install PostgreSQL via apt
 - Download and install MySQL 26.7 from Oracle's deb bundle
+- Download the Spanner Omni standalone server release into the user cache (linux/amd64 only)
 - Resolve all dependencies automatically
 - Skip anything already installed
 
@@ -36,12 +37,16 @@ go run ./cmd/sqlc-test-setup start
 This will:
 - Start PostgreSQL and configure password auth (`postgres`/`postgres`)
 - Start MySQL via `mysqld_safe` and set root password (`mysecretpassword`)
-- Verify both connections
+- Start a Spanner Omni single server in the background, serving plaintext gRPC on port 15000
+- Verify the connections
 - Skip steps that are already done (running services, existing config)
 
 Connection URIs after start:
 - PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`
 - MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`
+- Spanner Omni: `localhost:15000` (`SPANNER_SERVER_URI`)
+
+ClickHouse and SQL Server are not installed by the tool; `docker-compose.yml` runs them locally and CI runs them as services. Their tests read `CLICKHOUSE_SERVER_URI` and `MSSQL_SERVER_URI` and skip when unset.
 
 ### Run tests
 
@@ -172,9 +177,13 @@ them as an artifact.
 
 ### Example Tests
 
-- **Location:** `/examples/` directory
-- **Requirements:** Tagged with "examples", requires live databases
-- **Databases:** PostgreSQL, MySQL, SQLite examples
+- **Location:** `/examples/` directory, a Go module of its own so the
+  drivers the examples run against are not dependencies of sqlc, and so
+  cgo stays on for the DuckDB driver
+- **Requirements:** Tagged with "examples", requires live databases; run
+  with `cd examples && go test --tags=examples ./...`
+- **Databases:** PostgreSQL, MySQL, SQLite, ClickHouse, DuckDB, Spanner and
+  SQL Server examples; each skips when its server is not named
 
 ## Database Services
 

Makefile

@@ -14,10 +14,11 @@ test-managed:
 
 vet:
 	go vet ./...
+	cd ./examples && go vet --tags=examples ./...
 
 test-examples:
 	go test --tags=examples ./...
-	cd ./examples/duckdb && go test --tags=examples ./...
+	cd ./examples && go test --tags=examples ./...
 
 build-endtoend:
 	cd ./internal/endtoend/testdata && go build ./...

cmd/sqlc-test-setup/detach_other.go

@@ -0,0 +1,9 @@
+//go:build !unix
+
+package main
+
+import "syscall"
+
+func detachedProcess() *syscall.SysProcAttr {
+	return nil
+}

cmd/sqlc-test-setup/detach_unix.go

@@ -0,0 +1,11 @@
+//go:build unix
+
+package main
+
+import "syscall"
+
+// detachedProcess puts a child in a session of its own, so it outlives
+// this process and is not stopped by the signals this process gets.
+func detachedProcess() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true}
+}

cmd/sqlc-test-setup/main.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"net"
 	"net/http"
 	"os"
 	"os/exec"
@@ -19,8 +20,32 @@ import (
 const (
 	// pgVersion is the PostgreSQL version to install.
 	pgVersion = "18.2.0"
+
+	// omniVersion is the Spanner Omni release to install, from its
+	// standalone server binaries.
+	omniVersion = "2026.r2.1-beta"
+
+	// omniPort is the gRPC port a Spanner Omni single server listens on.
+	omniPort = "15000"
 )
 
+// omniBinary contains the download information for a Spanner Omni server
+// release, published at https://storage.googleapis.com/spanner-omni/ and
+// documented at https://docs.cloud.google.com/spanner-omni/download.
+type omniBinary struct {
+	URL    string
+	SHA256 string
+}
+
+// omniBinaries maps "<GOOS>/<GOARCH>" to the server download. Only linux
+// x86_64 is published; the other platforms skip Spanner Omni.
+var omniBinaries = map[string]omniBinary{
+	"linux/amd64": {
+		URL:    "https://storage.googleapis.com/spanner-omni/" + omniVersion + "/spanner-omni-server-" + omniVersion + "-linux-x86_64.tar.gz",
+		SHA256: "792ffc772d5fff8ade56a8f336993d671d22794fe9f7e88e38a6609c65e16d90",
+	},
+}
+
 // pgBinary contains the download information for a PostgreSQL binary release.
 type pgBinary struct {
 	URL    string
@@ -158,6 +183,10 @@ func runInstall() error {
 		return fmt.Errorf("installing mysql: %w", err)
 	}
 
+	if err := installSpannerOmni(); err != nil {
+		return fmt.Errorf("installing spanner omni: %w", err)
+	}
+
 	log.Println("=== Install complete ===")
 	return nil
 }
@@ -407,12 +436,164 @@ func runStart() error {
 		return fmt.Errorf("starting mysql: %w", err)
 	}
 
-	log.Println("=== Both databases are running and configured ===")
-	log.Println("PostgreSQL: postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable")
-	log.Println("MySQL:      root:mysecretpassword@tcp(127.0.0.1:3306)/mysql")
+	if err := startSpannerOmni(); err != nil {
+		return fmt.Errorf("starting spanner omni: %w", err)
+	}
+
+	log.Println("=== Databases are running and configured ===")
+	log.Println("PostgreSQL:   postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable")
+	log.Println("MySQL:        root:mysecretpassword@tcp(127.0.0.1:3306)/mysql")
+	log.Println("Spanner Omni: localhost:" + omniPort)
 	return nil
 }
 
+// omniDir is where the Spanner Omni release is unpacked: the bin directory
+// holds the spanner launcher and spanner_server, and data holds what a
+// started server writes.
+func omniDir() (string, error) {
+	cache, err := os.UserCacheDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(cache, "sqlc-spanner-omni", omniVersion), nil
+}
+
+func omniLauncher(dir string) string {
+	return filepath.Join(dir, "google", "spanner", "bin", "spanner")
+}
+
+// installSpannerOmni downloads the Spanner Omni server release into the
+// cache and unpacks it, checking the download against the pinned SHA-256.
+// It is a no-op when the release is already unpacked, and skips platforms
+// the server is not published for.
+func installSpannerOmni() error {
+	log.Printf("--- Installing Spanner Omni %s ---", omniVersion)
+
+	platform := runtime.GOOS + "/" + runtime.GOARCH
+	bin, ok := omniBinaries[platform]
+	if !ok {
+		log.Printf("spanner omni is not published for %s, skipping", platform)
+		return nil
+	}
+
+	dir, err := omniDir()
+	if err != nil {
+		return err
+	}
+	if _, err := os.Stat(omniLauncher(dir)); err == nil {
+		log.Printf("spanner omni %s is already installed in %s", omniVersion, dir)
+		return nil
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return err
+	}
+
+	archive := filepath.Join(dir, "server.tar.gz")
+	log.Printf("downloading %s", bin.URL)
+	if err := downloadFile(archive, bin.URL); err != nil {
+		return fmt.Errorf("downloading spanner omni: %w", err)
+	}
+	defer os.Remove(archive)
+
+	sum, err := sha256File(archive)
+	if err != nil {
+		return err
+	}
+	if sum != bin.SHA256 {
+		return fmt.Errorf("spanner omni download has SHA-256 %s, want %s", sum, bin.SHA256)
+	}
+
+	log.Printf("unpacking into %s", dir)
+	if err := run("tar", "-xzf", archive, "-C", dir); err != nil {
+		return fmt.Errorf("unpacking spanner omni: %w", err)
+	}
+	if _, err := os.Stat(omniLauncher(dir)); err != nil {
+		return fmt.Errorf("spanner omni release does not hold %s", omniLauncher(dir))
+	}
+	return nil
+}
+
+// startSpannerOmni starts a Spanner Omni single server in the background,
+// serving plaintext gRPC on omniPort, and waits until it accepts
+// connections. It is a no-op when a server is already listening, and skips
+// platforms the server is not installed on.
+func startSpannerOmni() error {
+	log.Println("--- Starting Spanner Omni ---")
+
+	if omniReady() {
+		log.Println("spanner omni is already running and accepting connections")
+		return nil
+	}
+
+	dir, err := omniDir()
+	if err != nil {
+		return err
+	}
+	launcher := omniLauncher(dir)
+	if _, err := os.Stat(launcher); err != nil {
+		if _, ok := omniBinaries[runtime.GOOS+"/"+runtime.GOARCH]; !ok {
+			log.Printf("spanner omni is not published for %s/%s, skipping", runtime.GOOS, runtime.GOARCH)
+			return nil
+		}
+		return fmt.Errorf("spanner omni is not installed: run `sqlc-test-setup install` first")
+	}
+
+	data := filepath.Join(dir, "data")
+	if err := os.MkdirAll(data, 0o755); err != nil {
+		return err
+	}
+	logFile, err := os.Create(filepath.Join(dir, "server.log"))
+	if err != nil {
+		return err
+	}
+	defer logFile.Close()
+
+	// The launcher supervises the server processes for as long as it runs,
+	// so it is detached from this process and left running.
+	cmd := exec.Command(launcher, "start-single-server", "--base-dir", data)
+	cmd.Stdout = logFile
+	cmd.Stderr = logFile
+	cmd.SysProcAttr = detachedProcess()
+	log.Printf("starting %s start-single-server --base-dir %s", launcher, data)
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("starting spanner omni: %w", err)
+	}
+	if err := cmd.Process.Release(); err != nil {
+		return err
+	}
+
+	log.Println("waiting for spanner omni to accept connections")
+	if err := waitForSpannerOmni(3 * time.Minute); err != nil {
+		return fmt.Errorf("spanner omni did not start in time (see %s): %w", logFile.Name(), err)
+	}
+	log.Println("spanner omni is accepting connections")
+	return nil
+}
+
+// omniReady reports whether something accepts connections on the Spanner
+// Omni gRPC port.
+func omniReady() bool {
+	conn, err := net.DialTimeout("tcp", "127.0.0.1:"+omniPort, time.Second)
+	if err != nil {
+		return false
+	}
+	conn.Close()
+	return true
+}
+
+// waitForSpannerOmni polls until the server accepts connections or the
+// timeout expires.
+func waitForSpannerOmni(timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if omniReady() {
+			return nil
+		}
+		time.Sleep(time.Second)
+	}
+	return fmt.Errorf("timed out after %s waiting for spanner omni", timeout)
+}
+
 func startPostgreSQL() error {
 	log.Println("--- Starting PostgreSQL ---")
 

docs/guides/development.md

@@ -20,10 +20,10 @@ go build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json
 go test ./...
 ```
 
-To run the tests in the examples folder, use the `examples` tag.
+To run the tests in the examples folder, which is a module of its own, use the `examples` tag from inside it.
 
 ```
-go test --tags=examples ./...
+cd examples && go test --tags=examples ./...
 ```
 
 These tests require locally-running database instances. Run these databases

examples/authors/clickhouse/db_test.go

@@ -9,7 +9,7 @@ import (
 
 	_ "github.com/ClickHouse/clickhouse-go/v2"
 
-	"github.com/sqlc-dev/sqlc/internal/sqltest/local"
+	"github.com/sqlc-dev/sqlc/examples/internal/local"
 )
 
 func TestAuthors(t *testing.T) {