{"owner":"sqlc-dev","repo":"sqlc","hasSkills":true,"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 and MySQL for tests. Both commands are idempotent and safe to re-run.\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 9 from Oracle's deb bundle\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- Verify both 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\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.txt`. A case that is expected to fail commits its\n`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### Example Tests\n\n- **Location:** `/examples/` directory\n- **Requirements:** Tagged with \"examples\", requires live databases\n- **Databases:** PostgreSQL, MySQL, SQLite examples\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 9** - 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- **Database Setup:** Uses `sqlc-test-setup` (not Docker) to install and start PostgreSQL and MySQL directly on the runner\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...`\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  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`\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 and MySQL for tests. Both commands are idempotent and safe to re-run.\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 9 from Oracle's deb bundle\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- Verify both 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\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.txt`. A case that is expected to fail commits its\n`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### Example Tests\n\n- **Location:** `/examples/` directory\n- **Requirements:** Tagged with \"examples\", requires live databases\n- **Databases:** PostgreSQL, MySQL, SQLite examples\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 9** - 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- **Database Setup:** Uses `sqlc-test-setup` (not Docker) to install and start PostgreSQL and MySQL directly on the runner\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...`\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  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`\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","title":"CLAUDE.md","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 and MySQL for tests. Both commands are idempotent and safe to re-run.\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 9 from Oracle's deb bundle\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- Verify both 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\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.txt`. A case that is expected to fail commits its\n`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### Example Tests\n\n- **Location:** `/examples/` directory\n- **Requirements:** Tagged with \"examples\", requires live databases\n- **Databases:** PostgreSQL, MySQL, SQLite examples\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 9** - 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- **Database Setup:** Uses `sqlc-test-setup` (not Docker) to install and start PostgreSQL and MySQL directly on the runner\n- **Test Command:** `gotestsum --junitfile junit.xml -- --tags=examples -timeout 20m ./...`\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  - `<engine>/dialect/` - The engine's type system and standard library, as\n    JSONL read by `/internal/core/seed`\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","category":"root","tokens":2353}]}