{"owner":"sqlc-dev","repo":"sqlc","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":3358,"categories":["claude-rule"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# Claude Code Development Guide for sqlc\n\nThis document provides essential information for working with the sqlc codebase, including testing, development workflow, and code structure.\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.26.4+** - Required for building and testing\n- **Docker & Docker Compose** - Required for integration tests with databases (local development)\n- **Git** - For version control\n\n## Database Setup with sqlc-test-setup\n\nThe `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL, MySQL, ClickHouse, SQL Server and Spanner Omni for tests. Both commands are idempotent and safe to re-run, and take the databases to act on as arguments (`postgresql`, `mysql`, `clickhouse`, `mssql`, `spanner`); with none named they act on all five.\n\n### Install databases\n\n```bash\ngo run ./cmd/sqlc-test-setup install\n```\n\nThis will:\n- Configure the apt proxy (if `http_proxy` is set, e.g. in Claude Code remote environments)\n- Install PostgreSQL via apt\n- Download and install MySQL 26.7 from Oracle's deb bundle\n- Download the ClickHouse 25.8 release into the user cache, where goldeneye caches it too\n- Install SQL Server 2025 from Microsoft's apt repository and run its setup, accepting the EULA on your behalf (Ubuntu 22.04 and 24.04 only)\n- Download the Spanner Omni standalone server release into the user cache (linux/amd64 only)\n- Resolve all dependencies automatically\n- Skip anything already installed\n\n### Start databases\n\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\nThis will:\n- Start PostgreSQL and configure password auth (`postgres`/`postgres`)\n- Start MySQL via `mysqld_safe` and set root password (`mysecretpassword`)\n- Start a ClickHouse server in the background on localhost, with the default user's password `mysecretpassword`\n- Start SQL Server through systemd, or in the background where there is no systemd, with the sa password `Mysecretpassword1!`\n- Start a Spanner Omni single server in the background, serving plaintext gRPC on port 15000\n- Verify the connections\n- Skip steps that are already done (running services, existing config)\n\nConnection URIs after start:\n- PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`\n- MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`\n- ClickHouse: `clickhouse://default:mysecretpassword@127.0.0.1:9000` (`CLICKHOUSE_SERVER_URI`)\n- SQL Server: `sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable` (`MSSQL_SERVER_URI`)\n- Spanner Omni: `localhost:15000` (`SPANNER_SERVER_URI`)\n\nThe examples' tests for ClickHouse, SQL Server and Spanner read those variables and skip when unset. `docker-compose.yml` runs the same databases for anyone who prefers containers.\n\n### Run tests\n\n```bash\n# Full test suite (requires databases running)\ngo test --tags=examples -timeout 20m ./...\n```\n\n## Running Tests\n\n### Basic Unit Tests (No Database Required)\n\n```bash\ngo test ./...\n```\n\n### Full Test Suite with Docker (Local Development)\n\n```bash\ndocker compose up -d\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Full Test Suite without Docker (Remote / CI)\n\n```bash\ngo run ./cmd/sqlc-test-setup install\ngo run ./cmd/sqlc-test-setup start\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Running Specific Tests\n\n```bash\n# Test a specific package\ngo test ./internal/config\n\n# Run with verbose output\ngo test -v ./internal/config\n\n# Run a specific test function\ngo test -v ./internal/config -run TestConfig\n\n# Run with race detector (recommended for concurrency changes)\ngo test -race ./internal/config\n```\n\n## Testing Strategy\n\n**Cover new work with end-to-end tests, not unit tests.** A change to the\ncompiler, an engine, the analysis core or codegen is exercised by running sqlc\nthe way a user does — a schema, a query file and a committed golden output —\nso the test says what sqlc produces rather than what an internal function\nreturns. Internal APIs move around; the SQL that goes in and the output that\ncomes out is the contract worth pinning down.\n\nAdding coverage means adding a directory under `/internal/endtoend/testdata/`,\nnot a `*_test.go` next to the code. Reach for a unit test only when the\nbehavior genuinely cannot be reached through the CLI, and say why in the test.\n\nSome `*_test.go` files predate this and remain; they are not a precedent for\nnew ones.\n\n### End-to-End Tests\n\n- **Location:** `/internal/endtoend/`\n- **Requirements:** `--tags=examples` flag and running databases\n- **Tests:**\n  - `TestExamples` - Main end-to-end tests\n  - `TestReplay` - Replay tests\n  - `TestFormat` - Code formatting tests\n  - `TestJsonSchema` - JSON schema validation\n  - `TestExamplesVet` - Static analysis tests\n\nA case is a directory holding the inputs and the expected output. `exec.json`\nnames the command and its arguments — omit it and the case runs `generate`,\ncomparing the generated files against the ones committed alongside; give it\n`{\"command\": \"analyze\", \"args\": [...]}` and the case compares the command's\nstdout against `stdout.json` (or `stdout.txt` for a command that does not\nprint JSON). A case that is expected to fail commits its `stderr.txt`. Regenerate a golden by running the command in its directory and\nwriting the output back over the committed file.\n\n`TestReplay` runs the whole corpus once per *context*. `base` runs each case as\ncommitted and `managed-db` reruns it against a live database, so a context can\nchange the config a case is generated with and the experiments it is generated\nunder. A case restricts itself to some of them with `\"contexts\": [...]` in its\n`exec.json`, and commits per-context expected errors as `stderr/<context>.txt`.\nThere is only one set of committed golden files, so every context is expected\nto generate identical code.\n\nThe `core` context generates every case through the analysis core\n(`SQLCEXPERIMENT=coreanalyzer`). The two paths still disagree, so it is opt-in\nand needs no database:\n\n```bash\nSQLC_TEST_CORE=1 go test ./internal/endtoend -run 'TestReplay/core'\n```\n\nGo aborts a test binary on panic, so a case that panics the core analyzer ends\nthe run early. Run a subset to get past one (`-run 'TestReplay/core/^select'`).\n\n### Dialect Checks\n\nThe dialect seeds under `/internal/engine/<engine>/dialect/` are generated\nfrom a live database by `/internal/goldeneye`, a nested module, and its tests\nverify the committed files against one byte for byte. The same module checks\nthe `analyze_*` cases under `/internal/endtoend/testdata/` against what the\ndatabase itself reports for them, so a `fixture.sql` next to a case's schema\ngives the queries rows to run against. ClickHouse, DuckDB, MySQL, SQLite,\nSQL Server and Spanner have the check today; engines whose database is not\navailable skip.\n\n```bash\ncd internal/goldeneye\ngo run ./cmd/goldeneye install clickhouse   # download the pinned clickhouse binary once\ngo run ./cmd/goldeneye install duckdb       # download the current DuckDB 2.0 preview build once\ngo run ./cmd/goldeneye install sqlite       # build the pinned sqlite3 shells once; needs a C compiler\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable\" \\\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql\" \\\nMSSQL_SERVER_URI=\"sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable\" \\\nSPANNER_SERVER_URI=\"localhost:15000\" go test ./...\ngo run ./cmd/goldeneye generate postgresql  # rewrite the files after a change\n```\n\nThe checks are not part of CI. The `gen` workflow\n(`.github/workflows/gen.yml`) generates the files on demand and uploads\nthem as an artifact.\n\n### Example Tests\n\n- **Location:** `/examples/` directory, a Go module of its own so the\n  drivers the examples run against are not dependencies of sqlc, and so\n  cgo stays on for the DuckDB driver\n- **Requirements:** Tagged with \"examples\", requires live databases; run\n  with `cd examples && go test --tags=examples ./...`\n- **Databases:** PostgreSQL, MySQL, SQLite, ClickHouse, DuckDB, Spanner and\n  SQL Server examples; each skips when its server is not named\n\n## Database Services\n\nThe `docker-compose.yml` provides test databases:\n\n- **PostgreSQL 16** - Port 5432\n  - User: `postgres`\n  - Password: `mysecretpassword`\n  - Database: `postgres`\n\n- **MySQL 26.7** - Port 3306\n  - User: `root`\n  - Password: `mysecretpassword`\n  - Database: `dinotest`\n\n## Makefile Targets\n\n```bash\nmake test              # Basic unit tests only\nmake test-examples     # Tests with examples tag\nmake build-endtoend    # Build end-to-end test data\nmake test-ci           # Full CI suite (examples + endtoend + vet)\nmake vet               # Run go vet\nmake start             # Start database containers\n```\n\n## CI/CD Configuration\n\n### GitHub Actions Workflow\n\n- **File:** `.github/workflows/ci.yml`\n- **Go Version:** 1.26.4\n- **Jobs:** `build` cross-compiles sqlc with cgo off; `test` runs sqlc's own tests; `examples` runs the examples module against every database; `vuln_check` runs `govulncheck`\n- **Database Setup:** `sqlc-test-setup` (not Docker) installs and starts the databases directly on the runner: PostgreSQL and MySQL for `test`, and all five for `examples`\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...` in `test`, and `go test --tags=examples ./...` under `examples/` in `examples`\n- **Additional Checks:** `govulncheck` for vulnerability scanning\n\n## Development Workflow\n\n### Building Development Versions\n\n```bash\n# Build main sqlc binary for development\ngo build -o ~/go/bin/sqlc-dev ./cmd/sqlc\n\n# Build JSON plugin (required for some tests)\ngo build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json\n```\n\n### Environment Variables for Tests\n\nYou can override database connections via environment variables:\n\n```bash\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable\"\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true\"\n```\n\n## Code Structure\n\n### Key Directories\n\n- `/cmd/` - Main binaries (sqlc, sqlc-gen-json, sqlc-test-setup)\n- `/internal/cmd/` - Command implementations (vet, generate, etc.)\n- `/internal/engine/` - Database engine implementations\n  - `/postgresql/` - PostgreSQL parser and converter\n  - `/dolphin/` - MySQL parser (uses TiDB parser)\n  - `/sqlite/` - SQLite parser\n  - `/duckdb/` - DuckDB 2.0 parser (uses darkwing, the pure Go port of\n    DuckDB's PEG parser)\n  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`; the generated parts come from\n    `/internal/goldeneye`\n- `/internal/goldeneye/` - Nested module that generates the dialect seeds\n  under `/internal/engine/<engine>/dialect/` from a live database, checks\n  the committed ones against it, and checks the analyze cases under\n  `/internal/endtoend/testdata/` against what the database reports, one\n  package per engine; see its README\n- `/internal/core/` - The analysis core: catalog, analyzer and dialect seeds\n- `/internal/compiler/` - Query compilation logic\n- `/internal/codegen/` - Code generation for different languages\n- `/internal/config/` - Configuration file parsing\n- `/internal/endtoend/` - End-to-end tests\n- `/internal/sqltest/` - Test database setup (Docker, native, local detection)\n- `/examples/` - Example projects for testing\n\n### Important Files\n\n- `/Makefile` - Build and test targets\n- `/docker-compose.yml` - Database services for testing\n- `/.github/workflows/ci.yml` - CI configuration\n\n## Common Issues & Solutions\n\n### Network Connectivity Issues\n\nIf you see errors about `storage.googleapis.com`, the Go proxy may be unreachable. Use `GOPROXY=direct go mod download` to fetch modules directly from source.\n\n### Test Timeouts\n\nEnd-to-end tests can take a while. Use longer timeouts:\n```bash\ngo test -timeout 20m --tags=examples ./...\n```\n\n### Race Conditions\n\nAlways run tests with the race detector when working on concurrent code:\n```bash\ngo test -race ./...\n```\n\n### Database Connection Failures\n\nIf using Docker:\n```bash\ndocker compose ps\ndocker compose up -d\n```\n\nIf using sqlc-test-setup:\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\n## Tips for Contributors\n\n1. **Run tests before committing:** `go test --tags=examples -timeout 20m ./...`\n2. **Cover new behavior end to end:** Add a case under `/internal/endtoend/testdata/`\n3. **Check for race conditions:** Use `-race` flag when testing concurrent code\n4. **Iterate on one case:** `go test ./internal/endtoend -run 'TestReplay/base/<case>'`\n5. **Read existing cases:** `/internal/endtoend/testdata/` has one per feature\n\n## Git Workflow\n\n### Branch Naming\n\n- Feature branches should start with `claude/` for Claude Code work\n- Branch names should be descriptive and end with the session ID\n\n### Committing Changes\n\n```bash\ngit add <files>\ngit commit -m \"Brief description of changes\"\ngit push -u origin <branch-name>\n```\n\n### Rebasing\n\n```bash\ngit checkout main\ngit pull origin main\ngit checkout <feature-branch>\ngit rebase main\ngit push --force-with-lease origin <feature-branch>\n```\n\n## Resources\n\n- **Main Documentation:** `/docs/`\n- **Development Guide:** `/docs/guides/development.md`\n- **CI Configuration:** `/.github/workflows/ci.yml`\n- **Docker Compose:** `/docker-compose.yml`\n"},"files":{"CLAUDE.md":"# Claude Code Development Guide for sqlc\n\nThis document provides essential information for working with the sqlc codebase, including testing, development workflow, and code structure.\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.26.4+** - Required for building and testing\n- **Docker & Docker Compose** - Required for integration tests with databases (local development)\n- **Git** - For version control\n\n## Database Setup with sqlc-test-setup\n\nThe `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL, MySQL, ClickHouse, SQL Server and Spanner Omni for tests. Both commands are idempotent and safe to re-run, and take the databases to act on as arguments (`postgresql`, `mysql`, `clickhouse`, `mssql`, `spanner`); with none named they act on all five.\n\n### Install databases\n\n```bash\ngo run ./cmd/sqlc-test-setup install\n```\n\nThis will:\n- Configure the apt proxy (if `http_proxy` is set, e.g. in Claude Code remote environments)\n- Install PostgreSQL via apt\n- Download and install MySQL 26.7 from Oracle's deb bundle\n- Download the ClickHouse 25.8 release into the user cache, where goldeneye caches it too\n- Install SQL Server 2025 from Microsoft's apt repository and run its setup, accepting the EULA on your behalf (Ubuntu 22.04 and 24.04 only)\n- Download the Spanner Omni standalone server release into the user cache (linux/amd64 only)\n- Resolve all dependencies automatically\n- Skip anything already installed\n\n### Start databases\n\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\nThis will:\n- Start PostgreSQL and configure password auth (`postgres`/`postgres`)\n- Start MySQL via `mysqld_safe` and set root password (`mysecretpassword`)\n- Start a ClickHouse server in the background on localhost, with the default user's password `mysecretpassword`\n- Start SQL Server through systemd, or in the background where there is no systemd, with the sa password `Mysecretpassword1!`\n- Start a Spanner Omni single server in the background, serving plaintext gRPC on port 15000\n- Verify the connections\n- Skip steps that are already done (running services, existing config)\n\nConnection URIs after start:\n- PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`\n- MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`\n- ClickHouse: `clickhouse://default:mysecretpassword@127.0.0.1:9000` (`CLICKHOUSE_SERVER_URI`)\n- SQL Server: `sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable` (`MSSQL_SERVER_URI`)\n- Spanner Omni: `localhost:15000` (`SPANNER_SERVER_URI`)\n\nThe examples' tests for ClickHouse, SQL Server and Spanner read those variables and skip when unset. `docker-compose.yml` runs the same databases for anyone who prefers containers.\n\n### Run tests\n\n```bash\n# Full test suite (requires databases running)\ngo test --tags=examples -timeout 20m ./...\n```\n\n## Running Tests\n\n### Basic Unit Tests (No Database Required)\n\n```bash\ngo test ./...\n```\n\n### Full Test Suite with Docker (Local Development)\n\n```bash\ndocker compose up -d\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Full Test Suite without Docker (Remote / CI)\n\n```bash\ngo run ./cmd/sqlc-test-setup install\ngo run ./cmd/sqlc-test-setup start\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Running Specific Tests\n\n```bash\n# Test a specific package\ngo test ./internal/config\n\n# Run with verbose output\ngo test -v ./internal/config\n\n# Run a specific test function\ngo test -v ./internal/config -run TestConfig\n\n# Run with race detector (recommended for concurrency changes)\ngo test -race ./internal/config\n```\n\n## Testing Strategy\n\n**Cover new work with end-to-end tests, not unit tests.** A change to the\ncompiler, an engine, the analysis core or codegen is exercised by running sqlc\nthe way a user does — a schema, a query file and a committed golden output —\nso the test says what sqlc produces rather than what an internal function\nreturns. Internal APIs move around; the SQL that goes in and the output that\ncomes out is the contract worth pinning down.\n\nAdding coverage means adding a directory under `/internal/endtoend/testdata/`,\nnot a `*_test.go` next to the code. Reach for a unit test only when the\nbehavior genuinely cannot be reached through the CLI, and say why in the test.\n\nSome `*_test.go` files predate this and remain; they are not a precedent for\nnew ones.\n\n### End-to-End Tests\n\n- **Location:** `/internal/endtoend/`\n- **Requirements:** `--tags=examples` flag and running databases\n- **Tests:**\n  - `TestExamples` - Main end-to-end tests\n  - `TestReplay` - Replay tests\n  - `TestFormat` - Code formatting tests\n  - `TestJsonSchema` - JSON schema validation\n  - `TestExamplesVet` - Static analysis tests\n\nA case is a directory holding the inputs and the expected output. `exec.json`\nnames the command and its arguments — omit it and the case runs `generate`,\ncomparing the generated files against the ones committed alongside; give it\n`{\"command\": \"analyze\", \"args\": [...]}` and the case compares the command's\nstdout against `stdout.json` (or `stdout.txt` for a command that does not\nprint JSON). A case that is expected to fail commits its `stderr.txt`. Regenerate a golden by running the command in its directory and\nwriting the output back over the committed file.\n\n`TestReplay` runs the whole corpus once per *context*. `base` runs each case as\ncommitted and `managed-db` reruns it against a live database, so a context can\nchange the config a case is generated with and the experiments it is generated\nunder. A case restricts itself to some of them with `\"contexts\": [...]` in its\n`exec.json`, and commits per-context expected errors as `stderr/<context>.txt`.\nThere is only one set of committed golden files, so every context is expected\nto generate identical code.\n\nThe `core` context generates every case through the analysis core\n(`SQLCEXPERIMENT=coreanalyzer`). The two paths still disagree, so it is opt-in\nand needs no database:\n\n```bash\nSQLC_TEST_CORE=1 go test ./internal/endtoend -run 'TestReplay/core'\n```\n\nGo aborts a test binary on panic, so a case that panics the core analyzer ends\nthe run early. Run a subset to get past one (`-run 'TestReplay/core/^select'`).\n\n### Dialect Checks\n\nThe dialect seeds under `/internal/engine/<engine>/dialect/` are generated\nfrom a live database by `/internal/goldeneye`, a nested module, and its tests\nverify the committed files against one byte for byte. The same module checks\nthe `analyze_*` cases under `/internal/endtoend/testdata/` against what the\ndatabase itself reports for them, so a `fixture.sql` next to a case's schema\ngives the queries rows to run against. ClickHouse, DuckDB, MySQL, SQLite,\nSQL Server and Spanner have the check today; engines whose database is not\navailable skip.\n\n```bash\ncd internal/goldeneye\ngo run ./cmd/goldeneye install clickhouse   # download the pinned clickhouse binary once\ngo run ./cmd/goldeneye install duckdb       # download the current DuckDB 2.0 preview build once\ngo run ./cmd/goldeneye install sqlite       # build the pinned sqlite3 shells once; needs a C compiler\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable\" \\\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql\" \\\nMSSQL_SERVER_URI=\"sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable\" \\\nSPANNER_SERVER_URI=\"localhost:15000\" go test ./...\ngo run ./cmd/goldeneye generate postgresql  # rewrite the files after a change\n```\n\nThe checks are not part of CI. The `gen` workflow\n(`.github/workflows/gen.yml`) generates the files on demand and uploads\nthem as an artifact.\n\n### Example Tests\n\n- **Location:** `/examples/` directory, a Go module of its own so the\n  drivers the examples run against are not dependencies of sqlc, and so\n  cgo stays on for the DuckDB driver\n- **Requirements:** Tagged with \"examples\", requires live databases; run\n  with `cd examples && go test --tags=examples ./...`\n- **Databases:** PostgreSQL, MySQL, SQLite, ClickHouse, DuckDB, Spanner and\n  SQL Server examples; each skips when its server is not named\n\n## Database Services\n\nThe `docker-compose.yml` provides test databases:\n\n- **PostgreSQL 16** - Port 5432\n  - User: `postgres`\n  - Password: `mysecretpassword`\n  - Database: `postgres`\n\n- **MySQL 26.7** - Port 3306\n  - User: `root`\n  - Password: `mysecretpassword`\n  - Database: `dinotest`\n\n## Makefile Targets\n\n```bash\nmake test              # Basic unit tests only\nmake test-examples     # Tests with examples tag\nmake build-endtoend    # Build end-to-end test data\nmake test-ci           # Full CI suite (examples + endtoend + vet)\nmake vet               # Run go vet\nmake start             # Start database containers\n```\n\n## CI/CD Configuration\n\n### GitHub Actions Workflow\n\n- **File:** `.github/workflows/ci.yml`\n- **Go Version:** 1.26.4\n- **Jobs:** `build` cross-compiles sqlc with cgo off; `test` runs sqlc's own tests; `examples` runs the examples module against every database; `vuln_check` runs `govulncheck`\n- **Database Setup:** `sqlc-test-setup` (not Docker) installs and starts the databases directly on the runner: PostgreSQL and MySQL for `test`, and all five for `examples`\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...` in `test`, and `go test --tags=examples ./...` under `examples/` in `examples`\n- **Additional Checks:** `govulncheck` for vulnerability scanning\n\n## Development Workflow\n\n### Building Development Versions\n\n```bash\n# Build main sqlc binary for development\ngo build -o ~/go/bin/sqlc-dev ./cmd/sqlc\n\n# Build JSON plugin (required for some tests)\ngo build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json\n```\n\n### Environment Variables for Tests\n\nYou can override database connections via environment variables:\n\n```bash\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable\"\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true\"\n```\n\n## Code Structure\n\n### Key Directories\n\n- `/cmd/` - Main binaries (sqlc, sqlc-gen-json, sqlc-test-setup)\n- `/internal/cmd/` - Command implementations (vet, generate, etc.)\n- `/internal/engine/` - Database engine implementations\n  - `/postgresql/` - PostgreSQL parser and converter\n  - `/dolphin/` - MySQL parser (uses TiDB parser)\n  - `/sqlite/` - SQLite parser\n  - `/duckdb/` - DuckDB 2.0 parser (uses darkwing, the pure Go port of\n    DuckDB's PEG parser)\n  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`; the generated parts come from\n    `/internal/goldeneye`\n- `/internal/goldeneye/` - Nested module that generates the dialect seeds\n  under `/internal/engine/<engine>/dialect/` from a live database, checks\n  the committed ones against it, and checks the analyze cases under\n  `/internal/endtoend/testdata/` against what the database reports, one\n  package per engine; see its README\n- `/internal/core/` - The analysis core: catalog, analyzer and dialect seeds\n- `/internal/compiler/` - Query compilation logic\n- `/internal/codegen/` - Code generation for different languages\n- `/internal/config/` - Configuration file parsing\n- `/internal/endtoend/` - End-to-end tests\n- `/internal/sqltest/` - Test database setup (Docker, native, local detection)\n- `/examples/` - Example projects for testing\n\n### Important Files\n\n- `/Makefile` - Build and test targets\n- `/docker-compose.yml` - Database services for testing\n- `/.github/workflows/ci.yml` - CI configuration\n\n## Common Issues & Solutions\n\n### Network Connectivity Issues\n\nIf you see errors about `storage.googleapis.com`, the Go proxy may be unreachable. Use `GOPROXY=direct go mod download` to fetch modules directly from source.\n\n### Test Timeouts\n\nEnd-to-end tests can take a while. Use longer timeouts:\n```bash\ngo test -timeout 20m --tags=examples ./...\n```\n\n### Race Conditions\n\nAlways run tests with the race detector when working on concurrent code:\n```bash\ngo test -race ./...\n```\n\n### Database Connection Failures\n\nIf using Docker:\n```bash\ndocker compose ps\ndocker compose up -d\n```\n\nIf using sqlc-test-setup:\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\n## Tips for Contributors\n\n1. **Run tests before committing:** `go test --tags=examples -timeout 20m ./...`\n2. **Cover new behavior end to end:** Add a case under `/internal/endtoend/testdata/`\n3. **Check for race conditions:** Use `-race` flag when testing concurrent code\n4. **Iterate on one case:** `go test ./internal/endtoend -run 'TestReplay/base/<case>'`\n5. **Read existing cases:** `/internal/endtoend/testdata/` has one per feature\n\n## Git Workflow\n\n### Branch Naming\n\n- Feature branches should start with `claude/` for Claude Code work\n- Branch names should be descriptive and end with the session ID\n\n### Committing Changes\n\n```bash\ngit add <files>\ngit commit -m \"Brief description of changes\"\ngit push -u origin <branch-name>\n```\n\n### Rebasing\n\n```bash\ngit checkout main\ngit pull origin main\ngit checkout <feature-branch>\ngit rebase main\ngit push --force-with-lease origin <feature-branch>\n```\n\n## Resources\n\n- **Main Documentation:** `/docs/`\n- **Development Guide:** `/docs/guides/development.md`\n- **CI Configuration:** `/.github/workflows/ci.yml`\n- **Docker Compose:** `/docker-compose.yml`\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/sqlc-dev/sqlc/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Claude Code Development Guide for sqlc\n\nThis document provides essential information for working with the sqlc codebase, including testing, development workflow, and code structure.\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.26.4+** - Required for building and testing\n- **Docker & Docker Compose** - Required for integration tests with databases (local development)\n- **Git** - For version control\n\n## Database Setup with sqlc-test-setup\n\nThe `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL, MySQL, ClickHouse, SQL Server and Spanner Omni for tests. Both commands are idempotent and safe to re-run, and take the databases to act on as arguments (`postgresql`, `mysql`, `clickhouse`, `mssql`, `spanner`); with none named they act on all five.\n\n### Install databases\n\n```bash\ngo run ./cmd/sqlc-test-setup install\n```\n\nThis will:\n- Configure the apt proxy (if `http_proxy` is set, e.g. in Claude Code remote environments)\n- Install PostgreSQL via apt\n- Download and install MySQL 26.7 from Oracle's deb bundle\n- Download the ClickHouse 25.8 release into the user cache, where goldeneye caches it too\n- Install SQL Server 2025 from Microsoft's apt repository and run its setup, accepting the EULA on your behalf (Ubuntu 22.04 and 24.04 only)\n- Download the Spanner Omni standalone server release into the user cache (linux/amd64 only)\n- Resolve all dependencies automatically\n- Skip anything already installed\n\n### Start databases\n\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\nThis will:\n- Start PostgreSQL and configure password auth (`postgres`/`postgres`)\n- Start MySQL via `mysqld_safe` and set root password (`mysecretpassword`)\n- Start a ClickHouse server in the background on localhost, with the default user's password `mysecretpassword`\n- Start SQL Server through systemd, or in the background where there is no systemd, with the sa password `Mysecretpassword1!`\n- Start a Spanner Omni single server in the background, serving plaintext gRPC on port 15000\n- Verify the connections\n- Skip steps that are already done (running services, existing config)\n\nConnection URIs after start:\n- PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`\n- MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`\n- ClickHouse: `clickhouse://default:mysecretpassword@127.0.0.1:9000` (`CLICKHOUSE_SERVER_URI`)\n- SQL Server: `sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable` (`MSSQL_SERVER_URI`)\n- Spanner Omni: `localhost:15000` (`SPANNER_SERVER_URI`)\n\nThe examples' tests for ClickHouse, SQL Server and Spanner read those variables and skip when unset. `docker-compose.yml` runs the same databases for anyone who prefers containers.\n\n### Run tests\n\n```bash\n# Full test suite (requires databases running)\ngo test --tags=examples -timeout 20m ./...\n```\n\n## Running Tests\n\n### Basic Unit Tests (No Database Required)\n\n```bash\ngo test ./...\n```\n\n### Full Test Suite with Docker (Local Development)\n\n```bash\ndocker compose up -d\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Full Test Suite without Docker (Remote / CI)\n\n```bash\ngo run ./cmd/sqlc-test-setup install\ngo run ./cmd/sqlc-test-setup start\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Running Specific Tests\n\n```bash\n# Test a specific package\ngo test ./internal/config\n\n# Run with verbose output\ngo test -v ./internal/config\n\n# Run a specific test function\ngo test -v ./internal/config -run TestConfig\n\n# Run with race detector (recommended for concurrency changes)\ngo test -race ./internal/config\n```\n\n## Testing Strategy\n\n**Cover new work with end-to-end tests, not unit tests.** A change to the\ncompiler, an engine, the analysis core or codegen is exercised by running sqlc\nthe way a user does — a schema, a query file and a committed golden output —\nso the test says what sqlc produces rather than what an internal function\nreturns. Internal APIs move around; the SQL that goes in and the output that\ncomes out is the contract worth pinning down.\n\nAdding coverage means adding a directory under `/internal/endtoend/testdata/`,\nnot a `*_test.go` next to the code. Reach for a unit test only when the\nbehavior genuinely cannot be reached through the CLI, and say why in the test.\n\nSome `*_test.go` files predate this and remain; they are not a precedent for\nnew ones.\n\n### End-to-End Tests\n\n- **Location:** `/internal/endtoend/`\n- **Requirements:** `--tags=examples` flag and running databases\n- **Tests:**\n  - `TestExamples` - Main end-to-end tests\n  - `TestReplay` - Replay tests\n  - `TestFormat` - Code formatting tests\n  - `TestJsonSchema` - JSON schema validation\n  - `TestExamplesVet` - Static analysis tests\n\nA case is a directory holding the inputs and the expected output. `exec.json`\nnames the command and its arguments — omit it and the case runs `generate`,\ncomparing the generated files against the ones committed alongside; give it\n`{\"command\": \"analyze\", \"args\": [...]}` and the case compares the command's\nstdout against `stdout.json` (or `stdout.txt` for a command that does not\nprint JSON). A case that is expected to fail commits its `stderr.txt`. Regenerate a golden by running the command in its directory and\nwriting the output back over the committed file.\n\n`TestReplay` runs the whole corpus once per *context*. `base` runs each case as\ncommitted and `managed-db` reruns it against a live database, so a context can\nchange the config a case is generated with and the experiments it is generated\nunder. A case restricts itself to some of them with `\"contexts\": [...]` in its\n`exec.json`, and commits per-context expected errors as `stderr/<context>.txt`.\nThere is only one set of committed golden files, so every context is expected\nto generate identical code.\n\nThe `core` context generates every case through the analysis core\n(`SQLCEXPERIMENT=coreanalyzer`). The two paths still disagree, so it is opt-in\nand needs no database:\n\n```bash\nSQLC_TEST_CORE=1 go test ./internal/endtoend -run 'TestReplay/core'\n```\n\nGo aborts a test binary on panic, so a case that panics the core analyzer ends\nthe run early. Run a subset to get past one (`-run 'TestReplay/core/^select'`).\n\n### Dialect Checks\n\nThe dialect seeds under `/internal/engine/<engine>/dialect/` are generated\nfrom a live database by `/internal/goldeneye`, a nested module, and its tests\nverify the committed files against one byte for byte. The same module checks\nthe `analyze_*` cases under `/internal/endtoend/testdata/` against what the\ndatabase itself reports for them, so a `fixture.sql` next to a case's schema\ngives the queries rows to run against. ClickHouse, DuckDB, MySQL, SQLite,\nSQL Server and Spanner have the check today; engines whose database is not\navailable skip.\n\n```bash\ncd internal/goldeneye\ngo run ./cmd/goldeneye install clickhouse   # download the pinned clickhouse binary once\ngo run ./cmd/goldeneye install duckdb       # download the current DuckDB 2.0 preview build once\ngo run ./cmd/goldeneye install sqlite       # build the pinned sqlite3 shells once; needs a C compiler\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable\" \\\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql\" \\\nMSSQL_SERVER_URI=\"sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable\" \\\nSPANNER_SERVER_URI=\"localhost:15000\" go test ./...\ngo run ./cmd/goldeneye generate postgresql  # rewrite the files after a change\n```\n\nThe checks are not part of CI. The `gen` workflow\n(`.github/workflows/gen.yml`) generates the files on demand and uploads\nthem as an artifact.\n\n### Example Tests\n\n- **Location:** `/examples/` directory, a Go module of its own so the\n  drivers the examples run against are not dependencies of sqlc, and so\n  cgo stays on for the DuckDB driver\n- **Requirements:** Tagged with \"examples\", requires live databases; run\n  with `cd examples && go test --tags=examples ./...`\n- **Databases:** PostgreSQL, MySQL, SQLite, ClickHouse, DuckDB, Spanner and\n  SQL Server examples; each skips when its server is not named\n\n## Database Services\n\nThe `docker-compose.yml` provides test databases:\n\n- **PostgreSQL 16** - Port 5432\n  - User: `postgres`\n  - Password: `mysecretpassword`\n  - Database: `postgres`\n\n- **MySQL 26.7** - Port 3306\n  - User: `root`\n  - Password: `mysecretpassword`\n  - Database: `dinotest`\n\n## Makefile Targets\n\n```bash\nmake test              # Basic unit tests only\nmake test-examples     # Tests with examples tag\nmake build-endtoend    # Build end-to-end test data\nmake test-ci           # Full CI suite (examples + endtoend + vet)\nmake vet               # Run go vet\nmake start             # Start database containers\n```\n\n## CI/CD Configuration\n\n### GitHub Actions Workflow\n\n- **File:** `.github/workflows/ci.yml`\n- **Go Version:** 1.26.4\n- **Jobs:** `build` cross-compiles sqlc with cgo off; `test` runs sqlc's own tests; `examples` runs the examples module against every database; `vuln_check` runs `govulncheck`\n- **Database Setup:** `sqlc-test-setup` (not Docker) installs and starts the databases directly on the runner: PostgreSQL and MySQL for `test`, and all five for `examples`\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...` in `test`, and `go test --tags=examples ./...` under `examples/` in `examples`\n- **Additional Checks:** `govulncheck` for vulnerability scanning\n\n## Development Workflow\n\n### Building Development Versions\n\n```bash\n# Build main sqlc binary for development\ngo build -o ~/go/bin/sqlc-dev ./cmd/sqlc\n\n# Build JSON plugin (required for some tests)\ngo build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json\n```\n\n### Environment Variables for Tests\n\nYou can override database connections via environment variables:\n\n```bash\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable\"\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true\"\n```\n\n## Code Structure\n\n### Key Directories\n\n- `/cmd/` - Main binaries (sqlc, sqlc-gen-json, sqlc-test-setup)\n- `/internal/cmd/` - Command implementations (vet, generate, etc.)\n- `/internal/engine/` - Database engine implementations\n  - `/postgresql/` - PostgreSQL parser and converter\n  - `/dolphin/` - MySQL parser (uses TiDB parser)\n  - `/sqlite/` - SQLite parser\n  - `/duckdb/` - DuckDB 2.0 parser (uses darkwing, the pure Go port of\n    DuckDB's PEG parser)\n  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`; the generated parts come from\n    `/internal/goldeneye`\n- `/internal/goldeneye/` - Nested module that generates the dialect seeds\n  under `/internal/engine/<engine>/dialect/` from a live database, checks\n  the committed ones against it, and checks the analyze cases under\n  `/internal/endtoend/testdata/` against what the database reports, one\n  package per engine; see its README\n- `/internal/core/` - The analysis core: catalog, analyzer and dialect seeds\n- `/internal/compiler/` - Query compilation logic\n- `/internal/codegen/` - Code generation for different languages\n- `/internal/config/` - Configuration file parsing\n- `/internal/endtoend/` - End-to-end tests\n- `/internal/sqltest/` - Test database setup (Docker, native, local detection)\n- `/examples/` - Example projects for testing\n\n### Important Files\n\n- `/Makefile` - Build and test targets\n- `/docker-compose.yml` - Database services for testing\n- `/.github/workflows/ci.yml` - CI configuration\n\n## Common Issues & Solutions\n\n### Network Connectivity Issues\n\nIf you see errors about `storage.googleapis.com`, the Go proxy may be unreachable. Use `GOPROXY=direct go mod download` to fetch modules directly from source.\n\n### Test Timeouts\n\nEnd-to-end tests can take a while. Use longer timeouts:\n```bash\ngo test -timeout 20m --tags=examples ./...\n```\n\n### Race Conditions\n\nAlways run tests with the race detector when working on concurrent code:\n```bash\ngo test -race ./...\n```\n\n### Database Connection Failures\n\nIf using Docker:\n```bash\ndocker compose ps\ndocker compose up -d\n```\n\nIf using sqlc-test-setup:\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\n## Tips for Contributors\n\n1. **Run tests before committing:** `go test --tags=examples -timeout 20m ./...`\n2. **Cover new behavior end to end:** Add a case under `/internal/endtoend/testdata/`\n3. **Check for race conditions:** Use `-race` flag when testing concurrent code\n4. **Iterate on one case:** `go test ./internal/endtoend -run 'TestReplay/base/<case>'`\n5. **Read existing cases:** `/internal/endtoend/testdata/` has one per feature\n\n## Git Workflow\n\n### Branch Naming\n\n- Feature branches should start with `claude/` for Claude Code work\n- Branch names should be descriptive and end with the session ID\n\n### Committing Changes\n\n```bash\ngit add <files>\ngit commit -m \"Brief description of changes\"\ngit push -u origin <branch-name>\n```\n\n### Rebasing\n\n```bash\ngit checkout main\ngit pull origin main\ngit checkout <feature-branch>\ngit rebase main\ngit push --force-with-lease origin <feature-branch>\n```\n\n## Resources\n\n- **Main Documentation:** `/docs/`\n- **Development Guide:** `/docs/guides/development.md`\n- **CI Configuration:** `/.github/workflows/ci.yml`\n- **Docker Compose:** `/docker-compose.yml`\n","isInternal":false,"tokens":3358,"sizeBytes":13237}],"systemPromptSnippet":"<yakaai_skills repo=\"sqlc-dev/sqlc\">\n<!-- File: CLAUDE.md (Tokens: ~3358 | Category: claude-rule) -->\n# Claude Code Development Guide for sqlc\n\nThis document provides essential information for working with the sqlc codebase, including testing, development workflow, and code structure.\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.26.4+** - Required for building and testing\n- **Docker & Docker Compose** - Required for integration tests with databases (local development)\n- **Git** - For version control\n\n## Database Setup with sqlc-test-setup\n\nThe `sqlc-test-setup` tool (`cmd/sqlc-test-setup/`) automates installing and starting PostgreSQL, MySQL, ClickHouse, SQL Server and Spanner Omni for tests. Both commands are idempotent and safe to re-run, and take the databases to act on as arguments (`postgresql`, `mysql`, `clickhouse`, `mssql`, `spanner`); with none named they act on all five.\n\n### Install databases\n\n```bash\ngo run ./cmd/sqlc-test-setup install\n```\n\nThis will:\n- Configure the apt proxy (if `http_proxy` is set, e.g. in Claude Code remote environments)\n- Install PostgreSQL via apt\n- Download and install MySQL 26.7 from Oracle's deb bundle\n- Download the ClickHouse 25.8 release into the user cache, where goldeneye caches it too\n- Install SQL Server 2025 from Microsoft's apt repository and run its setup, accepting the EULA on your behalf (Ubuntu 22.04 and 24.04 only)\n- Download the Spanner Omni standalone server release into the user cache (linux/amd64 only)\n- Resolve all dependencies automatically\n- Skip anything already installed\n\n### Start databases\n\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\nThis will:\n- Start PostgreSQL and configure password auth (`postgres`/`postgres`)\n- Start MySQL via `mysqld_safe` and set root password (`mysecretpassword`)\n- Start a ClickHouse server in the background on localhost, with the default user's password `mysecretpassword`\n- Start SQL Server through systemd, or in the background where there is no systemd, with the sa password `Mysecretpassword1!`\n- Start a Spanner Omni single server in the background, serving plaintext gRPC on port 15000\n- Verify the connections\n- Skip steps that are already done (running services, existing config)\n\nConnection URIs after start:\n- PostgreSQL: `postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable`\n- MySQL: `root:mysecretpassword@tcp(127.0.0.1:3306)/mysql`\n- ClickHouse: `clickhouse://default:mysecretpassword@127.0.0.1:9000` (`CLICKHOUSE_SERVER_URI`)\n- SQL Server: `sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable` (`MSSQL_SERVER_URI`)\n- Spanner Omni: `localhost:15000` (`SPANNER_SERVER_URI`)\n\nThe examples' tests for ClickHouse, SQL Server and Spanner read those variables and skip when unset. `docker-compose.yml` runs the same databases for anyone who prefers containers.\n\n### Run tests\n\n```bash\n# Full test suite (requires databases running)\ngo test --tags=examples -timeout 20m ./...\n```\n\n## Running Tests\n\n### Basic Unit Tests (No Database Required)\n\n```bash\ngo test ./...\n```\n\n### Full Test Suite with Docker (Local Development)\n\n```bash\ndocker compose up -d\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Full Test Suite without Docker (Remote / CI)\n\n```bash\ngo run ./cmd/sqlc-test-setup install\ngo run ./cmd/sqlc-test-setup start\ngo test --tags=examples -timeout 20m ./...\n```\n\n### Running Specific Tests\n\n```bash\n# Test a specific package\ngo test ./internal/config\n\n# Run with verbose output\ngo test -v ./internal/config\n\n# Run a specific test function\ngo test -v ./internal/config -run TestConfig\n\n# Run with race detector (recommended for concurrency changes)\ngo test -race ./internal/config\n```\n\n## Testing Strategy\n\n**Cover new work with end-to-end tests, not unit tests.** A change to the\ncompiler, an engine, the analysis core or codegen is exercised by running sqlc\nthe way a user does — a schema, a query file and a committed golden output —\nso the test says what sqlc produces rather than what an internal function\nreturns. Internal APIs move around; the SQL that goes in and the output that\ncomes out is the contract worth pinning down.\n\nAdding coverage means adding a directory under `/internal/endtoend/testdata/`,\nnot a `*_test.go` next to the code. Reach for a unit test only when the\nbehavior genuinely cannot be reached through the CLI, and say why in the test.\n\nSome `*_test.go` files predate this and remain; they are not a precedent for\nnew ones.\n\n### End-to-End Tests\n\n- **Location:** `/internal/endtoend/`\n- **Requirements:** `--tags=examples` flag and running databases\n- **Tests:**\n  - `TestExamples` - Main end-to-end tests\n  - `TestReplay` - Replay tests\n  - `TestFormat` - Code formatting tests\n  - `TestJsonSchema` - JSON schema validation\n  - `TestExamplesVet` - Static analysis tests\n\nA case is a directory holding the inputs and the expected output. `exec.json`\nnames the command and its arguments — omit it and the case runs `generate`,\ncomparing the generated files against the ones committed alongside; give it\n`{\"command\": \"analyze\", \"args\": [...]}` and the case compares the command's\nstdout against `stdout.json` (or `stdout.txt` for a command that does not\nprint JSON). A case that is expected to fail commits its `stderr.txt`. Regenerate a golden by running the command in its directory and\nwriting the output back over the committed file.\n\n`TestReplay` runs the whole corpus once per *context*. `base` runs each case as\ncommitted and `managed-db` reruns it against a live database, so a context can\nchange the config a case is generated with and the experiments it is generated\nunder. A case restricts itself to some of them with `\"contexts\": [...]` in its\n`exec.json`, and commits per-context expected errors as `stderr/<context>.txt`.\nThere is only one set of committed golden files, so every context is expected\nto generate identical code.\n\nThe `core` context generates every case through the analysis core\n(`SQLCEXPERIMENT=coreanalyzer`). The two paths still disagree, so it is opt-in\nand needs no database:\n\n```bash\nSQLC_TEST_CORE=1 go test ./internal/endtoend -run 'TestReplay/core'\n```\n\nGo aborts a test binary on panic, so a case that panics the core analyzer ends\nthe run early. Run a subset to get past one (`-run 'TestReplay/core/^select'`).\n\n### Dialect Checks\n\nThe dialect seeds under `/internal/engine/<engine>/dialect/` are generated\nfrom a live database by `/internal/goldeneye`, a nested module, and its tests\nverify the committed files against one byte for byte. The same module checks\nthe `analyze_*` cases under `/internal/endtoend/testdata/` against what the\ndatabase itself reports for them, so a `fixture.sql` next to a case's schema\ngives the queries rows to run against. ClickHouse, DuckDB, MySQL, SQLite,\nSQL Server and Spanner have the check today; engines whose database is not\navailable skip.\n\n```bash\ncd internal/goldeneye\ngo run ./cmd/goldeneye install clickhouse   # download the pinned clickhouse binary once\ngo run ./cmd/goldeneye install duckdb       # download the current DuckDB 2.0 preview build once\ngo run ./cmd/goldeneye install sqlite       # build the pinned sqlite3 shells once; needs a C compiler\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable\" \\\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql\" \\\nMSSQL_SERVER_URI=\"sqlserver://sa:Mysecretpassword1!@127.0.0.1:1433?encrypt=disable\" \\\nSPANNER_SERVER_URI=\"localhost:15000\" go test ./...\ngo run ./cmd/goldeneye generate postgresql  # rewrite the files after a change\n```\n\nThe checks are not part of CI. The `gen` workflow\n(`.github/workflows/gen.yml`) generates the files on demand and uploads\nthem as an artifact.\n\n### Example Tests\n\n- **Location:** `/examples/` directory, a Go module of its own so the\n  drivers the examples run against are not dependencies of sqlc, and so\n  cgo stays on for the DuckDB driver\n- **Requirements:** Tagged with \"examples\", requires live databases; run\n  with `cd examples && go test --tags=examples ./...`\n- **Databases:** PostgreSQL, MySQL, SQLite, ClickHouse, DuckDB, Spanner and\n  SQL Server examples; each skips when its server is not named\n\n## Database Services\n\nThe `docker-compose.yml` provides test databases:\n\n- **PostgreSQL 16** - Port 5432\n  - User: `postgres`\n  - Password: `mysecretpassword`\n  - Database: `postgres`\n\n- **MySQL 26.7** - Port 3306\n  - User: `root`\n  - Password: `mysecretpassword`\n  - Database: `dinotest`\n\n## Makefile Targets\n\n```bash\nmake test              # Basic unit tests only\nmake test-examples     # Tests with examples tag\nmake build-endtoend    # Build end-to-end test data\nmake test-ci           # Full CI suite (examples + endtoend + vet)\nmake vet               # Run go vet\nmake start             # Start database containers\n```\n\n## CI/CD Configuration\n\n### GitHub Actions Workflow\n\n- **File:** `.github/workflows/ci.yml`\n- **Go Version:** 1.26.4\n- **Jobs:** `build` cross-compiles sqlc with cgo off; `test` runs sqlc's own tests; `examples` runs the examples module against every database; `vuln_check` runs `govulncheck`\n- **Database Setup:** `sqlc-test-setup` (not Docker) installs and starts the databases directly on the runner: PostgreSQL and MySQL for `test`, and all five for `examples`\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...` in `test`, and `go test --tags=examples ./...` under `examples/` in `examples`\n- **Additional Checks:** `govulncheck` for vulnerability scanning\n\n## Development Workflow\n\n### Building Development Versions\n\n```bash\n# Build main sqlc binary for development\ngo build -o ~/go/bin/sqlc-dev ./cmd/sqlc\n\n# Build JSON plugin (required for some tests)\ngo build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json\n```\n\n### Environment Variables for Tests\n\nYou can override database connections via environment variables:\n\n```bash\nPOSTGRESQL_SERVER_URI=\"postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable\"\nMYSQL_SERVER_URI=\"root:mysecretpassword@tcp(127.0.0.1:3306)/mysql?multiStatements=true&parseTime=true\"\n```\n\n## Code Structure\n\n### Key Directories\n\n- `/cmd/` - Main binaries (sqlc, sqlc-gen-json, sqlc-test-setup)\n- `/internal/cmd/` - Command implementations (vet, generate, etc.)\n- `/internal/engine/` - Database engine implementations\n  - `/postgresql/` - PostgreSQL parser and converter\n  - `/dolphin/` - MySQL parser (uses TiDB parser)\n  - `/sqlite/` - SQLite parser\n  - `/duckdb/` - DuckDB 2.0 parser (uses darkwing, the pure Go port of\n    DuckDB's PEG parser)\n  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`; the generated parts come from\n    `/internal/goldeneye`\n- `/internal/goldeneye/` - Nested module that generates the dialect seeds\n  under `/internal/engine/<engine>/dialect/` from a live database, checks\n  the committed ones against it, and checks the analyze cases under\n  `/internal/endtoend/testdata/` against what the database reports, one\n  package per engine; see its README\n- `/internal/core/` - The analysis core: catalog, analyzer and dialect seeds\n- `/internal/compiler/` - Query compilation logic\n- `/internal/codegen/` - Code generation for different languages\n- `/internal/config/` - Configuration file parsing\n- `/internal/endtoend/` - End-to-end tests\n- `/internal/sqltest/` - Test database setup (Docker, native, local detection)\n- `/examples/` - Example projects for testing\n\n### Important Files\n\n- `/Makefile` - Build and test targets\n- `/docker-compose.yml` - Database services for testing\n- `/.github/workflows/ci.yml` - CI configuration\n\n## Common Issues & Solutions\n\n### Network Connectivity Issues\n\nIf you see errors about `storage.googleapis.com`, the Go proxy may be unreachable. Use `GOPROXY=direct go mod download` to fetch modules directly from source.\n\n### Test Timeouts\n\nEnd-to-end tests can take a while. Use longer timeouts:\n```bash\ngo test -timeout 20m --tags=examples ./...\n```\n\n### Race Conditions\n\nAlways run tests with the race detector when working on concurrent code:\n```bash\ngo test -race ./...\n```\n\n### Database Connection Failures\n\nIf using Docker:\n```bash\ndocker compose ps\ndocker compose up -d\n```\n\nIf using sqlc-test-setup:\n```bash\ngo run ./cmd/sqlc-test-setup start\n```\n\n## Tips for Contributors\n\n1. **Run tests before committing:** `go test --tags=examples -timeout 20m ./...`\n2. **Cover new behavior end to end:** Add a case under `/internal/endtoend/testdata/`\n3. **Check for race conditions:** Use `-race` flag when testing concurrent code\n4. **Iterate on one case:** `go test ./internal/endtoend -run 'TestReplay/base/<case>'`\n5. **Read existing cases:** `/internal/endtoend/testdata/` has one per feature\n\n## Git Workflow\n\n### Branch Naming\n\n- Feature branches should start with `claude/` for Claude Code work\n- Branch names should be descriptive and end with the session ID\n\n### Committing Changes\n\n```bash\ngit add <files>\ngit commit -m \"Brief description of changes\"\ngit push -u origin <branch-name>\n```\n\n### Rebasing\n\n```bash\ngit checkout main\ngit pull origin main\ngit checkout <feature-branch>\ngit rebase main\ngit push --force-with-lease origin <feature-branch>\n```\n\n## Resources\n\n- **Main Documentation:** `/docs/`\n- **Development Guide:** `/docs/guides/development.md`\n- **CI Configuration:** `/.github/workflows/ci.yml`\n- **Docker Compose:** `/docker-compose.yml`\n</yakaai_skills>"}