From 9b89d55450f7161f8ae25cfb8b3ff0f02ba1cfd2 Mon Sep 17 00:00:00 2001 From: Yumin Xia Date: Wed, 9 Sep 2026 15:55:25 +0000 Subject: [PATCH 1/2] docs: introduce wicked-sqlc architecture --- README.md | 112 +++++++++--------- .../2026-09-09-wicked-readme-architecture.md | 98 +++++++++++++++ 2 files changed, 157 insertions(+), 53 deletions(-) create mode 100644 docs/changelogs/2026-09-09-wicked-readme-architecture.md diff --git a/README.md b/README.md index f0880b1920..507bfb6f6f 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,74 @@ -# sqlc: A SQL Compiler +# wicked-sqlc -This is the **wicked fork** of sqlc, with a dedicated Go backend for wpgx and -dcache. See [GUIDE.md](GUIDE.md) for its schema conventions, timeout/cache options, -installation, and migration testing. The current migration is two commits on -upstream v1.31.1: core changes, then the wicked backend, preserving the v2.3.4 API. +A PostgreSQL-focused [sqlc](https://github.com/sqlc-dev/sqlc) fork that generates +type-safe Go code for [wpgx](https://github.com/Stumble/wpgx) and +[dcache](https://github.com/Stumble/dcache). Write SQL; generate query methods with +timeouts, optional caching, cache invalidation, replica access, and load/dump +helpers for tests. -![go](https://github.com/sqlc-dev/sqlc/workflows/go/badge.svg) -[![Go Report Card](https://goreportcard.com/badge/github.com/sqlc-dev/sqlc)](https://goreportcard.com/report/github.com/sqlc-dev/sqlc) +## Architecture -sqlc generates **type-safe code** from SQL. Here's how it works: +wicked-sqlc builds on upstream sqlc v1.31.1, with two layers of customization: +compiler changes in the fork and a dedicated Go backend. -1. You write queries in SQL. -1. You run sqlc to generate code with type-safe interfaces to those queries. -1. You write application code that calls the generated code. +1. **Compiler** — Parses SQL, resolves schema dependencies, and infers SQL types + and parameter nullability. In wpgx mode, the first schema file owns the primary + model; the remaining files supply dependencies and are analyzed first. +2. **Codegen contract** — sqlc's `GenerateRequest` carries the catalog, typed + queries, and comments. A small `WickedMetadata` extension adds the primary + schema source, its relation, and top-level SELECT classification. Options such + as `timeout`, `cache`, and `invalidate` travel as ordinary query comments, not + custom compiler parameters. +3. **Wicked backend** — [internal/codegen/wicked](internal/codegen/wicked) maps SQL + types to Go and renders the templates. It parses comment options and generates + cache keys, timeout handling, invalidation hooks, replica APIs, and test helpers. + The generated code uses wpgx and dcache at runtime. -Check out [an interactive example](https://play.sqlc.dev/) to see it in action, and the [introductory blog post](https://conroy.org/introducing-sqlc) for the motivation behind sqlc. +The backend runs in-process, bundled in the `sqlc` binary. There is no separate +plugin to install. `sql_package: wpgx` selects it; other Go configurations use +upstream's standard Go backend. -## Overview +Compiler fixes stay in this fork until validated with the full wicked stack, then +can be proposed upstream independently. Generation-specific conventions stay in +the wicked backend. -- [Documentation](https://docs.sqlc.dev) -- [Installation](https://docs.sqlc.dev/en/latest/overview/install.html) -- [Playground](https://play.sqlc.dev) -- [Website](https://sqlc.dev) -- [Downloads](https://downloads.sqlc.dev/) -- [Community](https://discord.gg/EcXzGe5SEs) +## Use it -## Supported languages +Build the current `main` branch with the Go version specified in [go.mod](go.mod): -- [sqlc-gen-go](https://github.com/sqlc-dev/sqlc-gen-go) -- [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) -- [sqlc-gen-python](https://github.com/sqlc-dev/sqlc-gen-python) -- [sqlc-gen-typescript](https://github.com/sqlc-dev/sqlc-gen-typescript) +```sh +git clone https://github.com/Stumble/sqlc.git +cd sqlc +make install +``` -Additional languages can be added via [plugins](https://docs.sqlc.dev/en/latest/reference/language-support.html#community-language-support). +Select the backend in `sqlc.yaml`: -## Sponsors +```yaml +version: '2' +sql: + - engine: postgresql + schema: books/schema.sql + queries: books/query.sql + gen: + go: + sql_package: wpgx + package: books + out: books +``` -Development is possible thanks to our sponsors. If you would like to support sqlc, -please consider [sponsoring on GitHub](https://github.com/sponsors/kyleconroy). +Every query requires a timeout. Caching is opt-in: -

- Riza.io -

+```sql +-- name: GetBook :one +-- -- timeout: 500ms +-- -- cache: 10m +SELECT * FROM books WHERE id = @id; +``` -

- Coder.com - Mint.fun - Mux.com -

+Run `sqlc generate` to generate code, or `sqlc diff` to check that it is up to date. +Existing wicked projects keep the same configuration and commands. -

- Cyberax - - NaNuNaNu - - Stumble - - WestfalNamur - - alecthomas - - cameronnewman - - danielbprice - - davherrmann - - dvob - - gilcrest - - gzuidhof - - jeffreylo - - mmcloughlin - - ryohei1216 - - sgielen -

+See the [guide](GUIDE.md) for schema conventions, query options, and runtime setup, +or [bookstore](https://github.com/Stumble/bookstore) for a working example. +[Upstream documentation](https://docs.sqlc.dev) covers standard sqlc features. diff --git a/docs/changelogs/2026-09-09-wicked-readme-architecture.md b/docs/changelogs/2026-09-09-wicked-readme-architecture.md new file mode 100644 index 0000000000..6d0063423b --- /dev/null +++ b/docs/changelogs/2026-09-09-wicked-readme-architecture.md @@ -0,0 +1,98 @@ +# wicked-sqlc README architecture + +## 1. Current State + +The README still presents upstream sqlc's homepage with a short fork preface. +`main` now contains the validated compiler changes and dedicated wicked backend, +but the homepage does not explain that architecture or how to select it. + +## 2. Intended Behavior + +- B1: Introduce wicked-sqlc in concise, natural English. +- B2: Explain compiler ownership, the codegen contract, backend responsibilities, + and the single-binary installation model. +- B3: Show the existing build, configuration, and query-comment workflow; link to + the guide and working example for details. +- F1: Do not imply that a separate plugin, custom option protocol, or proven + read-only analysis exists. + +## 3. Decisions and Risks + +- D1: Replace the inherited homepage with a fork-specific introduction while + crediting and linking upstream. +- D2: Describe the implementation on `main`, not the completed migration's branch + mechanics. Preserve the guide and historical migration record unchanged. +- R1: Architecture prose can overstate implementation guarantees. Check each + claim against the compiler, request shim/proto, dispatcher, and backend. + +## 4. Scope and Checklist + +The user's request authorizes a README rewrite and a new PR against `main`. +No architecture or runtime changes are proposed. + +- [x] Inspect the merged implementation and existing documentation. +- [x] Rewrite `README.md` and add this change record. +- [x] Verify examples, links, whitespace, and scope; review the complete diff. + +Publication follows the normal secret-scan, commit, PR, and CI/review monitoring +workflow, with live results recorded on the PR. + +## 5. Verification Plan + +E2E Required: no. Only Markdown changes; no source, templates, configuration, +dependencies, or generated output changes. + +- Inspect `internal/compiler/compile.go`, `internal/compiler/wicked.go`, + `internal/cmd/shim.go`, `protos/plugin/codegen.proto`, + `internal/cmd/generate.go`, and `internal/codegen/wicked` for architecture claims. +- Generate and diff a temporary fixture using the README's exact YAML/query + blocks and a minimal books schema with the verified main-equivalent binary. +- Check README relative links and fenced code blocks; run `git diff --check`. +- Review `git diff origin/main` and confirm only README and this record changed. +- No `make lint-fix` target exists; lint is unavailable. Do not substitute another + linter. Full local runtime tests are unnecessary for this docs-only change; + monitor the existing GitHub workflows after publication. + +## 6. Human Decisions + +User requested succinct, native English and a PR. Keep the implementation, +generated API, and installation entrypoints unchanged. No additional decision +or migration is required. + +## 7. Outcome and Evidence + +The README is now a 357-word introduction covering the architecture and a small +working example. Only the README and this record change. + +| Item | Evidence | Status | +| --- | --- | --- | +| B1, D1 | Concise fork-specific homepage with upstream attribution | DONE | +| B2, F1, R1 | Checked compiler, shim/proto, in-process handler, and backend | DONE | +| B3 | Exact README YAML/query fixture generates and passes `sqlc diff` | DONE | +| D2 | Guide and historical migration record unchanged | DONE | + +Checks on the final README: + +- In `/home/forge/worktrees/sqlc-wicked-readme`, `git diff --check` passed; + `make -n install` confirmed the existing installation command without changing + the installed binary. No `make lint-fix` target exists. +- `node /tmp/sqlc-readme-validation.1zZzaq/verify.mjs` passed: all relative links + exist, code fences are balanced, and the YAML/SQL fixture exactly matches the + README blocks. +- In `/tmp/sqlc-readme-validation.1zZzaq`, both + `/home/forge/worktrees/sqlc-wicked-on-upstream/bin/sqlc generate` and + `/home/forge/worktrees/sqlc-wicked-on-upstream/bin/sqlc diff` exited 0. + Inspected generated `GetBook`, its 500 ms timeout, 10-minute cache TTL, replica + method, and load/dump helpers. The fixture adds only a minimal books schema. +- The binary is the previously verified `v2.4.0-dev-wicked-fork` build from + `41bb4c1581bcd0eb86a968f480594603f7953602`; a non-Markdown diff against the merged + base `e40892b969f75131c219b5adbda4dc570e406e08` is empty. No runtime retest or new + binary build is claimed for this documentation change. +- Reviewed the complete diff for scope, architecture accuracy, example validity, + compatibility, operations, and prose. No unresolved findings. No migrations, + dependency changes, or API changes; full local E2E is not required. + +## 8. Remaining Work + +None for the documentation change. Publication and current-head CI/review status +are tracked on the PR; no runtime follow-up is introduced. From b6a1a57387f837aa542c85ae054b341dd7d2c578 Mon Sep 17 00:00:00 2001 From: Yumin Xia Date: Wed, 9 Sep 2026 17:32:19 +0000 Subject: [PATCH 2/2] docs: preserve upstream README and describe ongoing rebases --- README.md | 72 ++++++++++++++++++- .../2026-09-09-wicked-readme-architecture.md | 44 ++++++++++-- 2 files changed, 109 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 507bfb6f6f..3c3e8b7e56 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ helpers for tests. ## Architecture -wicked-sqlc builds on upstream sqlc v1.31.1, with two layers of customization: -compiler changes in the fork and a dedicated Go backend. +We regularly rebase wicked-sqlc onto upstream sqlc releases. Our changes fall into +two layers: compiler changes in the fork and a dedicated Go backend. 1. **Compiler** — Parses SQL, resolves schema dependencies, and infers SQL types and parameter nullability. In wpgx mode, the first schema file owns the primary @@ -72,3 +72,71 @@ Existing wicked projects keep the same configuration and commands. See the [guide](GUIDE.md) for schema conventions, query options, and runtime setup, or [bookstore](https://github.com/Stumble/bookstore) for a working example. [Upstream documentation](https://docs.sqlc.dev) covers standard sqlc features. + +--- + +The original upstream README is preserved below. + +# sqlc: A SQL Compiler + +![go](https://github.com/sqlc-dev/sqlc/workflows/go/badge.svg) +[![Go Report Card](https://goreportcard.com/badge/github.com/sqlc-dev/sqlc)](https://goreportcard.com/report/github.com/sqlc-dev/sqlc) + +sqlc generates **type-safe code** from SQL. Here's how it works: + +1. You write queries in SQL. +1. You run sqlc to generate code with type-safe interfaces to those queries. +1. You write application code that calls the generated code. + +Check out [an interactive example](https://play.sqlc.dev/) to see it in action, and the [introductory blog post](https://conroy.org/introducing-sqlc) for the motivation behind sqlc. + +## Overview + +- [Documentation](https://docs.sqlc.dev) +- [Installation](https://docs.sqlc.dev/en/latest/overview/install.html) +- [Playground](https://play.sqlc.dev) +- [Website](https://sqlc.dev) +- [Downloads](https://downloads.sqlc.dev/) +- [Community](https://discord.gg/EcXzGe5SEs) + +## Supported languages + +- [sqlc-gen-go](https://github.com/sqlc-dev/sqlc-gen-go) +- [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) +- [sqlc-gen-python](https://github.com/sqlc-dev/sqlc-gen-python) +- [sqlc-gen-typescript](https://github.com/sqlc-dev/sqlc-gen-typescript) + +Additional languages can be added via [plugins](https://docs.sqlc.dev/en/latest/reference/language-support.html#community-language-support). + +## Sponsors + +Development is possible thanks to our sponsors. If you would like to support sqlc, +please consider [sponsoring on GitHub](https://github.com/sponsors/kyleconroy). + +

+ Riza.io +

+ +

+ Coder.com + Mint.fun + Mux.com +

+ +

+ Cyberax - + NaNuNaNu - + Stumble - + WestfalNamur - + alecthomas - + cameronnewman - + danielbprice - + davherrmann - + dvob - + gilcrest - + gzuidhof - + jeffreylo - + mmcloughlin - + ryohei1216 - + sgielen +

diff --git a/docs/changelogs/2026-09-09-wicked-readme-architecture.md b/docs/changelogs/2026-09-09-wicked-readme-architecture.md index 6d0063423b..fabf644754 100644 --- a/docs/changelogs/2026-09-09-wicked-readme-architecture.md +++ b/docs/changelogs/2026-09-09-wicked-readme-architecture.md @@ -13,13 +13,18 @@ but the homepage does not explain that architecture or how to select it. and the single-binary installation model. - B3: Show the existing build, configuration, and query-comment workflow; link to the guide and working example for details. +- B4: Describe regular rebases onto upstream releases without tying the + architecture to a specific upstream version. +- B5: Preserve the original upstream README at the end, including its badges, + links, and sponsors. - F1: Do not imply that a separate plugin, custom option protocol, or proven read-only analysis exists. ## 3. Decisions and Risks -- D1: Replace the inherited homepage with a fork-specific introduction while - crediting and linking upstream. +- D1: Lead with a fork-specific introduction while crediting and linking upstream. + Following user review, preserve the original upstream homepage below it rather + than replacing it. - D2: Describe the implementation on `main`, not the completed migration's branch mechanics. Preserve the guide and historical migration record unchanged. - R1: Architecture prose can overstate implementation guarantees. Check each @@ -33,6 +38,8 @@ No architecture or runtime changes are proposed. - [x] Inspect the merged implementation and existing documentation. - [x] Rewrite `README.md` and add this change record. - [x] Verify examples, links, whitespace, and scope; review the complete diff. +- [x] Apply the user's version-neutral wording and upstream-preservation feedback; + verify exact preservation and re-review the complete PR diff. Publication follows the normal secret-scan, commit, PR, and CI/review monitoring workflow, with live results recorded on the PR. @@ -48,6 +55,9 @@ dependencies, or generated output changes. - Generate and diff a temporary fixture using the README's exact YAML/query blocks and a minimal books schema with the verified main-equivalent binary. - Check README relative links and fenced code blocks; run `git diff --check`. +- Compare the appended upstream section byte-for-byte with the upstream README + inherited by `main`. Preserve its existing whitespace and check the net diff + against `origin/main` for newly introduced whitespace issues. - Review `git diff origin/main` and confirm only README and this record changed. - No `make lint-fix` target exists; lint is unavailable. Do not substitute another linter. Full local runtime tests are unnecessary for this docs-only change; @@ -59,10 +69,17 @@ User requested succinct, native English and a PR. Keep the implementation, generated API, and installation entrypoints unchanged. No additional decision or migration is required. +In follow-up review, the user requested version-neutral architecture wording that +states the regular upstream-rebase policy, and the original upstream README at +the end as acknowledgment of upstream's work. This supersedes the initial +replacement-only layout. + ## 7. Outcome and Evidence -The README is now a 357-word introduction covering the architecture and a small -working example. Only the README and this record change. +The initial revision was a 357-word introduction covering the architecture and a +small working example. The follow-up keeps that concise introduction, removes +the specific upstream version, and restores the original upstream README beneath +it. Only the README and this record change. | Item | Evidence | Status | | --- | --- | --- | @@ -70,8 +87,10 @@ working example. Only the README and this record change. | B2, F1, R1 | Checked compiler, shim/proto, in-process handler, and backend | DONE | | B3 | Exact README YAML/query fixture generates and passes `sqlc diff` | DONE | | D2 | Guide and historical migration record unchanged | DONE | +| B4 | Version-neutral wording states regular upstream-release rebases | DONE | +| B5 | Appended upstream README matches the inherited original byte-for-byte | DONE | -Checks on the final README: +Initial revision checks (revalidated as applicable after user feedback below): - In `/home/forge/worktrees/sqlc-wicked-readme`, `git diff --check` passed; `make -n install` confirmed the existing installation command without changing @@ -92,6 +111,21 @@ Checks on the final README: compatibility, operations, and prose. No unresolved findings. No migrations, dependency changes, or API changes; full local E2E is not required. +Follow-up verification after user feedback: + +- `node /tmp/sqlc-readme-validation.1zZzaq/verify.mjs` passed again, now also + checking version-neutral wording and exact equality of the appended section + with `git show a95e91d70ad9e1181253c333a1cfdd75ae4b95a5:README.md`. + This SHA identifies the inherited document for the preservation check, not an + ongoing version constraint on the fork. +- Re-ran the fixture's `sqlc generate` and `sqlc diff` commands above; both + exited 0. The YAML and SQL examples remain unchanged. +- `git diff --check origin/main` passed. Upstream's original trailing spaces + are deliberately preserved; the net PR diff introduces no whitespace errors. +- Re-reviewed the entire PR diff against `origin/main`, including the restored + upstream text, updated decisions, and unchanged implementation boundary. + No unresolved findings. The follow-up is an additive commit on PR #18. + ## 8. Remaining Work None for the documentation change. Publication and current-head CI/review status