feat: fork sqlc-gen-go as iodesystems/sqlc-go-codegen-metaquery

Extends sqlc-gen-go with per-query metadata emission and a runtime CTE
builder so queries can be dynamically wrapped with filters, ordering,
pagination, and aggregations without modifying the original SQL.

Scope:

- Rename module to github.com/iodesystems/sqlc-go-codegen; rename plugin
  binary to sqlc-go-codegen-metaquery.
- Emit per-query `MetaFoo` metadata vars alongside sqlc's generated query
  code (new internal/metaquery.go + internal/templates/metaqueryFile.tmpl,
  wired via internal/gen.go).
- `metaquery` runtime pkg: Query/Column/Arg/Table types, Builder with
  Where/WhereExpr/Having/OrderBy/GroupBy/Select/Agg/Paginate, and
  Build/BuildCount that wrap the original SQL as a CTE with original
  placeholders preserved.
- Typed safety layer: typed `WrapFoo(args...)` constructors, typed
  `FooCols` column refs (TextCol/IntCol/FloatCol/BoolCol/TimeCol/
  BytesCol/AnyCol) with op-appropriate methods, Op constants, and a
  ValidateFilter for JSON-driven flows.
- `metaquery/mqpgx` submodule: pgx/v5 adapter with Run (untyped
  Result), Scan[T] (typed TypedResult[T] with shape validation via
  Validate[T]), ScanOne[T], and automatic total-count population.
- `emit_metaquery` option (ladder: off|meta|wrap|cols, default cols)
  with per-query `-- metaquery: <level>` override.
- Bidirectional Filter/OrderBy/PageRequest types so HTTP handlers can
  unmarshal from request bodies straight into the builder and marshal
  the applied state back via Meta.
- Fix internal/result.go buildStructs to populate DBName and Column on
  model-struct fields (needed for metadata).

End-to-end:

- `internal/endtoend/testdata/metaquery_authors/` — authors fixture
  with real sqlc generate + unit tests that exercise every surface.
- `examples/pgx/` — docker-compose pg17, migrations, sqlc.yaml, a
  demo CLI (seed/list/search/counts) outputting JSON envelopes,
  Makefile, and README explaining the emit-level ladder.

Tests pass across all four modules (plugin, metaquery, mqpgx, fixture,
example). Live demo verified against pg17.

Author: Nthalk

.idea/.gitignore

@@ -1,18 +1,20 @@
 .PHONY: build test
 
+BIN_NAME = sqlc-go-codegen-metaquery
+
 build:
 	go build ./...
 
-test: bin/sqlc-gen-go.wasm
+test: bin/$(BIN_NAME).wasm
 	go test ./...
 
-all: bin/sqlc-gen-go bin/sqlc-gen-go.wasm
+all: bin/$(BIN_NAME) bin/$(BIN_NAME).wasm
 
-bin/sqlc-gen-go: bin go.mod go.sum $(wildcard **/*.go)
-	cd plugin && go build -o ../bin/sqlc-gen-go ./main.go
+bin/$(BIN_NAME): bin go.mod go.sum $(wildcard **/*.go)
+	cd plugin && go build -o ../bin/$(BIN_NAME) ./main.go
 
-bin/sqlc-gen-go.wasm: bin/sqlc-gen-go
-	cd plugin && GOOS=wasip1 GOARCH=wasm go build -o ../bin/sqlc-gen-go.wasm main.go
+bin/$(BIN_NAME).wasm: bin/$(BIN_NAME)
+	cd plugin && GOOS=wasip1 GOARCH=wasm go build -o ../bin/$(BIN_NAME).wasm main.go
 
 bin:
 	mkdir -p bin

Makefile

@@ -1,157 +1,182 @@
-# sqlc-gen-go
+# sqlc-go-codegen-metaquery
+
+A fork of [`sqlc-gen-go`](https://github.com/sqlc-dev/sqlc-gen-go) that emits
+per-query **metadata** alongside the usual sqlc output, plus a small runtime
+that wraps any query as a CTE so you can compose filters, ordering,
+pagination, and aggregations dynamically — without ever modifying the
+original SQL.
+
+Built for **Go + Postgres + pgx/v5 + sqlc**. Drop-in compatible with stock
+sqlc-gen-go: the existing `q.ListAuthors(ctx)` methods are unchanged; the
+metaquery surface is purely additive.
+
+```go
+// Your sqlc query:
+// -- name: ListAuthors :many
+// SELECT id, name, bio FROM authors ORDER BY name;
+
+// Wrap it, add filters/pagination, run it — all at runtime:
+res, _ := mqpgx.Scan[db.Author](ctx, conn,
+    db.WrapListAuthors().
+        ApplyFilter(db.ListAuthorsCols.Name.ILike("%ada%")).
+        ApplyOrder(db.ListAuthorsCols.CreatedAt.Desc()).
+        ApplyPagination(metaquery.PageRequest{Page: 0, Size: 20, Total: true}))
+
+// res.Data is []db.Author
+// res.Meta has the applied Filter/OrderBy/Pagination + column metadata,
+// ready to serialize as an HTTP response body.
+```
+
+See [`examples/pgx/`](examples/pgx/) for a full runnable demo (docker-compose
+pg17, migrations, seed, JSON-output CLI).
+
+## Why use this
 
-> [!IMPORTANT]  
-> This repository is read-only. It contains a working Go codegen plugin extracted from https://github.com/sqlc-dev/sqlc which you can fork and modify to meet your needs.
+Stock sqlc is great for static queries but painful once you need dynamic
+filtering, pagination, or admin UIs on top. Typical workarounds:
+- Write N variants of a query — explodes quickly
+- Drop to `database/sql` + a query builder — loses sqlc's type safety
+- Build your own metadata indirection — what this project is
 
-See [Building from source](#building-from-source) and [Migrating from sqlc's built-in Go codegen](#migrating-from-sqlcs-built-in-go-codegen) if you want to use a modified fork in your project.
+This fork keeps sqlc's compile-time query validation and generated types,
+adds a typed wrapper per query, and gives you a runtime API that's
+JSON-round-trippable for HTTP endpoints and admin consoles.
 
-## Usage
+## Installation
+
+This repo is a standalone fork, not registered as a GitHub fork. Install
+from source:
+
+```sh
+git clone https://github.com/iodesystems/sqlc-go-codegen-metaquery.git
+cd sqlc-go-codegen-metaquery
+make all       # produces bin/sqlc-go-codegen-metaquery (+ .wasm)
+```
+
+Point sqlc at the binary:
 
 ```yaml
+# sqlc.yaml
 version: '2'
 plugins:
-- name: golang
-  wasm:
-    url: https://downloads.sqlc.dev/plugin/sqlc-gen-go_1.6.0.wasm
-    sha256: 3e54bb8ba8911e939d0f67ddccb710f79799e72e0c51516586414b3f3be12cfc
+- name: metaquery
+  process:
+    cmd: /path/to/sqlc-go-codegen-metaquery
 sql:
 - schema: schema.sql
   queries: query.sql
   engine: postgresql
   codegen:
-  - plugin: golang
+  - plugin: metaquery
     out: db
     options:
       package: db
       sql_package: pgx/v5
+      emit_db_tags: true
+      emit_json_tags: true
+      emit_metaquery: cols    # off | meta | wrap | cols (default: cols)
 ```
 
-## Building from source
+Then `sqlc generate` produces the usual `db/query.sql.go` + `db/models.go` +
+a new `db/query.sql.metaquery.go` carrying the per-query metadata and typed
+helpers.
 
-Assuming you have the Go toolchain set up, from the project root you can simply `make all`.
+In your Go code, import the runtime:
 
-```sh
-make all
+```go
+import (
+    "github.com/iodesystems/sqlc-go-codegen-metaquery/metaquery"
+    "github.com/iodesystems/sqlc-go-codegen-metaquery/metaquery/mqpgx"
+)
 ```
 
-This will produce a standalone binary and a WASM blob in the `bin` directory.
-They don't depend on each other, they're just two different plugin styles. You can
-use either with sqlc, but we recommend WASM and all of the configuration examples
-here assume you're using a WASM plugin.
+The `mqpgx` adapter lives in a sibling Go module so users of the core
+`metaquery` package with a different driver aren't forced to pull in pgx.
 
-To use a local WASM build with sqlc, just update your configuration with a `file://`
-URL pointing at the WASM blob in your `bin` directory:
+## What it emits
 
-```yaml
-plugins:
-- name: golang
-  wasm:
-    url: file:///path/to/bin/sqlc-gen-go.wasm
-    sha256: ""
-```
+For each query sqlc processes, three symbols (at the default `cols` level):
 
-As-of sqlc v1.24.0 the `sha256` is optional, but without it sqlc won't cache your
-module internally which will impact performance.
+| Symbol | Purpose |
+| --- | --- |
+| `MetaListAuthors metaquery.Query` | Runtime-readable metadata: the SQL text, columns (Name, GoType, DBType, NotNull, Table, …), args, source file, etc. JSON-serializable. |
+| `WrapListAuthors(args...) *metaquery.Builder` | Typed constructor that binds the original query's positional args at compile time and returns a Builder ready for filter/order/pagination/aggregation methods. |
+| `ListAuthorsCols struct{...}` | Typed column references. `ListAuthorsCols.Name` is a `TextCol`; `ListAuthorsCols.ID` is an `IntCol`. Each exposes ops appropriate to its type (`ILike(string)` on text, `Gt(int64)`, `Between(int64, int64)` on int, etc.). Column names and op/value types are compile-time checked. |
 
-## Migrating from sqlc's built-in Go codegen
+Six column kinds ship by default (Text/Int/Float/Bool/Time/Bytes), with
+`AnyCol` as the escape hatch for arrays, enums, pgtype.Numeric, UUIDs, etc.
 
-We’ve worked hard to make switching to sqlc-gen-go as seamless as possible. Let’s say you’re generating Go code today using a sqlc.yaml configuration that looks something like this:
+## Emission levels
 
-```yaml
-version: 2
-sql:
-- schema: "query.sql"
-  queries: "query.sql"
-  engine: "postgresql"
-  gen:
-    go:
-      package: "db"
-      out: "db"
-      emit_json_tags: true
-      emit_pointers_for_null_types: true
-      query_parameter_limit: 5
-      overrides:
-      - column: "authors.id"
-        go_type: "your/package.SomeType"
-      rename:
-        foo: "bar"
-```
+You pay only for what you use. Set globally via `emit_metaquery` or per-query
+with `-- metaquery: <level>`:
 
-To use the sqlc-gen-go WASM plugin for Go codegen, your config will instead look something like this:
+| Level | Emits | Typical use |
+| --- | --- | --- |
+| `off` | nothing | Query is only called via the regular sqlc method; no dynamic wrapping needed |
+| `meta` | `Meta<Name>` only | You want runtime introspection (schema export, generic API handler) without the builder surface |
+| `wrap` | `+ Wrap<Name>(args...)` | Typed wrappers but filter against column names as strings |
+| `cols` *(default)* | `+ <Name>Cols` | Full Tier 2 — typed wrappers + typed column refs |
 
-```yaml
-version: 2
-plugins:
-- name: golang
-  wasm:
-    url: https://downloads.sqlc.dev/plugin/sqlc-gen-go_1.6.0.wasm
-    sha256: 3e54bb8ba8911e939d0f67ddccb710f79799e72e0c51516586414b3f3be12cfc
-sql:
-- schema: "query.sql"
-  queries: "query.sql"
-  engine: "postgresql"
-  codegen:
-  - plugin: golang
-    out: "db"
-    options:
-      package: "db"
-      emit_json_tags: true
-      emit_pointers_for_null_types: true
-      query_parameter_limit: 5
-      overrides:
-      - column: "authors.id"
-        go_type: "your/package.SomeType"
-      rename:
-        foo: "bar"
+Per-query override example:
+
+```sql
+-- name: TruncateAll :exec
+-- metaquery: off
+-- (Only called from seed/migration code; no builder needed.)
+TRUNCATE authors RESTART IDENTITY CASCADE;
 ```
 
-The differences are:
-* An additional top-level `plugins` list with an entry for the Go codegen WASM plugin. If you’ve built the plugin from source you’ll want to use a `file://` URL. The `sha256` field is required, but will be optional in the upcoming sqlc v1.24.0 release.
-* Within the `sql` block, rather than `gen` with `go` nested beneath you’ll have a `codegen` list with an entry referencing the plugin name from the top-level `plugins` list. All options from the current `go` configuration block move as-is into the `options` block within `codegen`. The only special case is `out`, which moves up a level into the `codegen` configuration itself.
+## Safety surface
 
-### Global overrides and renames
+| Failure mode | Caught | How |
+| --- | --- | --- |
+| Wrong wrapper arg type | compile time | `WrapGetAuthor("not an int")` won't compile |
+| Unknown column in `.Where`/`.OrderBy`/etc | compile time (via typed cols) or pre-query (via whitelist) | `ListAuthorsCols.Typo` → compile error; `.Where("typo",...)` → Build-time error |
+| Wrong op for column type | compile time (typed cols) or pre-query (ValidateFilter) | `IntCol` has no `.ILike`; `Filter{Op: OpILike}` on an int column → `op "ILIKE" not valid for column "id" (int64/int)` |
+| Wrong value type | compile time (typed cols) or pre-query (ValidateFilter) | `IntCol.Eq` takes `int64`; JSON-driven filters with string values for int columns are rejected before any query runs |
+| Scan-struct shape drift | pre-query | `Validate[T]` reflects on T and diffs against `b.OutputColumns()` |
+| Malformed raw SQL in `WhereExpr`/`Agg` | query time | Passed through to Postgres verbatim; caller owns safety |
 
-If you have global overrides or renames configured, you’ll need to move those to the new top-level `options` field. Replace the existing `go` field name with the name you gave your plugin in the `plugins` list. We’ve used `"golang"` in this example.
+The validator is also callable as a library function (`metaquery.ValidateFilter(q, f)`)
+so JSON-driven HTTP handlers can fail fast on bad client input, using the
+same rules the builder applies internally.
 
-If your existing configuration looks like this:
+## Relationship to upstream
 
-```yaml
-version: "2"
-overrides:
-  go:
-    rename:
-      id: "Identifier"
-    overrides:
-    - db_type: "timestamptz"
-      nullable: true
-      engine: "postgresql"
-      go_type:
-        import: "gopkg.in/guregu/null.v4"
-        package: "null"
-        type: "Time"
-...
+This is a clean fork of
+[`github.com/sqlc-dev/sqlc-gen-go`](https://github.com/sqlc-dev/sqlc-gen-go),
+not a registered GitHub fork. Upstream is tracked as a git remote:
+
+```sh
+git remote -v
+# origin    git@github.com:IodeSystems/sqlc-go-codegen-metaquery.git
+# upstream  https://github.com/sqlc-dev/sqlc-gen-go.git
 ```
 
-Then your updated configuration would look something like this:
+To sync upstream updates:
 
-```yaml
-version: "2"
-plugins:
-- name: golang
-  wasm:
-    url: https://downloads.sqlc.dev/plugin/sqlc-gen-go_1.6.0.wasm
-    sha256: 3e54bb8ba8911e939d0f67ddccb710f79799e72e0c51516586414b3f3be12cfc
-options:
-  golang:
-    rename:
-      id: "Identifier"
-    overrides:
-    - db_type: "timestamptz"
-      nullable: true
-      engine: "postgresql"
-      go_type:
-        import: "gopkg.in/guregu/null.v4"
-        package: "null"
-        type: "Time"
-...
+```sh
+git fetch upstream
+git merge upstream/main   # resolve conflicts in the three touched files
+                          #   (internal/gen.go, internal/result.go, go.mod + Makefile)
+                          # import-path conflicts resolve mechanically with sed.
 ```
+
+## Caveats / non-goals
+
+- **Postgres + pgx/v5 only.** MySQL and SQLite aren't blocked by the runtime
+  design but aren't implemented; the `mqpgx` adapter is pgx-specific.
+- **No WASM distribution yet.** Build the binary from source; if you need
+  WASM, `make all` produces one in `bin/`.
+- **No released versions yet.** Pin a commit sha or `main` for now.
+- **The builder wraps, never rewrites.** A filter references the *output*
+  columns of the original query. If you need to filter on a column the
+  query doesn't project, either widen the query or use `WhereExpr`.
+- **`Sum`/`Avg`/`Min`/`Max` aggregates project the source column's type
+  without null-safety** — aggregates over empty groups return NULL. Use
+  `Agg("x", "coalesce(sum(y), 0)", "int64")` as the escape hatch.
+
+## License
+
+MIT — same as upstream. See [LICENSE](LICENSE).

README.md

@@ -0,0 +1,55 @@
+.PHONY: up down wait plugin generate build seed list list-typed counts demo clean
+
+DSN ?= postgres://demo:demo@localhost:5544/demo?sslmode=disable
+SQLC ?= $(shell command -v sqlc 2>/dev/null || echo $${HOME}/go/bin/sqlc)
+PLUGIN := ../../bin/sqlc-go-codegen-metaquery
+DEMO   := ./bin/demo
+
+up:
+	docker compose up -d
+
+down:
+	docker compose down -v
+
+wait:
+	@printf "waiting for pg..."
+	@until docker compose exec -T db pg_isready -U demo -d demo >/dev/null 2>&1; do \
+		printf "."; sleep 1; \
+	done; echo " ready"
+
+plugin:
+	$(MAKE) -C ../.. bin/sqlc-go-codegen-metaquery
+
+generate: plugin
+	$(SQLC) generate
+
+build:
+	mkdir -p bin
+	go build -o $(DEMO) .
+
+seed: build
+	$(DEMO) seed --db '$(DSN)'
+
+list: build
+	$(DEMO) list --db '$(DSN)' --size 10
+
+list-typed: build
+	$(DEMO) list --typed --db '$(DSN)' --size 10
+
+counts: build
+	$(DEMO) counts --db '$(DSN)'
+
+# Full walk-through: start db, generate code, seed, and show each subcommand.
+demo: up wait generate build seed
+	@echo '---- list (untyped, page 1 of 2) ----'
+	$(DEMO) list --db '$(DSN)' --size 3 \
+		--where '[{"column":"name","op":"ILIKE","value":"%a%"}]' \
+		--order '[{"column":"name","dir":"ASC"}]'
+	@echo '---- list --typed ----'
+	$(DEMO) list --typed --db '$(DSN)' --size 3
+	@echo '---- counts (group by author_id) ----'
+	$(DEMO) counts --db '$(DSN)' \
+		--order '[{"column":"author_id","dir":"ASC"}]'
+
+clean:
+	rm -rf bin