{"id":49429314,"url":"https://github.com/iodesystems/sqlc-go-codegen-metaquery","last_synced_at":"2026-04-29T11:05:20.729Z","repository":{"id":352774273,"uuid":"1216558479","full_name":"IodeSystems/sqlc-go-codegen-metaquery","owner":"IodeSystems","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-21T03:20:11.000Z","size":104,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T05:26:37.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IodeSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T02:52:26.000Z","updated_at":"2026-04-21T03:20:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/IodeSystems/sqlc-go-codegen-metaquery","commit_stats":null,"previous_names":["iodesystems/sqlc-go-codegen-metaquery"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/IodeSystems/sqlc-go-codegen-metaquery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IodeSystems%2Fsqlc-go-codegen-metaquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IodeSystems%2Fsqlc-go-codegen-metaquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IodeSystems%2Fsqlc-go-codegen-metaquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IodeSystems%2Fsqlc-go-codegen-metaquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IodeSystems","download_url":"https://codeload.github.com/IodeSystems/sqlc-go-codegen-metaquery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IodeSystems%2Fsqlc-go-codegen-metaquery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32422602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T11:05:19.629Z","updated_at":"2026-04-29T11:05:20.715Z","avatar_url":"https://github.com/IodeSystems.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sqlc-go-codegen-metaquery\n\nA fork of [`sqlc-gen-go`](https://github.com/sqlc-dev/sqlc-gen-go) that emits\nper-query **metadata** alongside the usual sqlc output, plus a small runtime\nthat wraps any query as a CTE so you can compose filters, ordering,\npagination, and aggregations dynamically — without ever modifying the\noriginal SQL.\n\nBuilt for **Go + Postgres + pgx/v5 + sqlc**. Drop-in compatible with stock\nsqlc-gen-go: the existing `q.ListAuthors(ctx)` methods are unchanged; the\nmetaquery surface is purely additive.\n\n```go\n// Your sqlc query:\n// -- name: ListAuthors :many\n// SELECT id, name, bio FROM authors ORDER BY name;\n\n// Wrap it, add filters/pagination, run it — all at runtime:\nres, _ := mqpgx.Scan[db.Author](ctx, conn,\n    db.WrapListAuthors().\n        ApplyFilter(db.ListAuthorsCols.Name.ILike(\"%ada%\")).\n        ApplyOrder(db.ListAuthorsCols.CreatedAt.Desc()).\n        ApplyPagination(metaquery.PageRequest{Page: 0, Size: 20, Total: true}))\n\n// res.Data is []db.Author\n// res.Meta has the applied Filter/OrderBy/Pagination + column metadata,\n// ready to serialize as an HTTP response body.\n```\n\nSee [`examples/pgx/`](examples/pgx/) for a full runnable demo (docker-compose\npg17, migrations, seed, JSON-output CLI).\n\n## Why use this\n\nStock sqlc is great for static queries but painful once you need dynamic\nfiltering, pagination, or admin UIs on top. Typical workarounds:\n- Write N variants of a query — explodes quickly\n- Drop to `database/sql` + a query builder — loses sqlc's type safety\n- Build your own metadata indirection — what this project is\n\nThis fork keeps sqlc's compile-time query validation and generated types,\nadds a typed wrapper per query, and gives you a runtime API that's\nJSON-round-trippable for HTTP endpoints and admin consoles.\n\n## Installation\n\n### Via WASM (recommended)\n\n\u003c!-- release:begin --\u003e\n\n### Latest release — v0.1.0\n\n```yaml\nplugins:\n- name: metaquery\n  wasm:\n    url: https://github.com/IodeSystems/sqlc-go-codegen-metaquery/releases/download/v0.1.0/sqlc-go-codegen-metaquery.wasm\n    sha256: f8d79989e58225905fd42adaa2b55e055770ac0f9e46bcdfe028fafbd865a805\n```\n\n\u003c!-- release:end --\u003e\n\n### From source\n\n```sh\ngit clone https://github.com/iodesystems/sqlc-go-codegen-metaquery.git\ncd sqlc-go-codegen-metaquery\nmake all       # produces bin/sqlc-go-codegen-metaquery (+ .wasm)\n```\n\nPoint sqlc at the binary:\n\n```yaml\n# sqlc.yaml\nversion: '2'\nplugins:\n- name: metaquery\n  process:\n    cmd: /path/to/sqlc-go-codegen-metaquery\nsql:\n- schema: schema.sql\n  queries: query.sql\n  engine: postgresql\n  codegen:\n  - plugin: metaquery\n    out: db\n    options:\n      package: db\n      sql_package: pgx/v5\n      emit_db_tags: true\n      emit_json_tags: true\n      emit_metaquery: cols    # off | meta | wrap | cols (default: cols)\n```\n\nThen `sqlc generate` produces the usual `db/query.sql.go` + `db/models.go` +\na new `db/query.sql.metaquery.go` carrying the per-query metadata and typed\nhelpers.\n\nIn your Go code, import the runtime:\n\n```go\nimport (\n    \"github.com/iodesystems/sqlc-go-codegen-metaquery/metaquery\"\n    \"github.com/iodesystems/sqlc-go-codegen-metaquery/metaquery/mqpgx\"\n)\n```\n\nThe `mqpgx` adapter lives in a sibling Go module so users of the core\n`metaquery` package with a different driver aren't forced to pull in pgx.\n\n## What it emits\n\nFor each query sqlc processes, three symbols (at the default `cols` level):\n\n| Symbol | Purpose |\n| --- | --- |\n| `MetaListAuthors metaquery.Query` | Runtime-readable metadata: the SQL text, columns (Name, GoType, DBType, NotNull, Table, …), args, source file, etc. JSON-serializable. |\n| `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. |\n| `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. |\n\nSix column kinds ship by default (Text/Int/Float/Bool/Time/Bytes), with\n`AnyCol` as the escape hatch for arrays, enums, pgtype.Numeric, UUIDs, etc.\n\n## Emission levels\n\nYou pay only for what you use. Set globally via `emit_metaquery` or per-query\nwith `-- metaquery: \u003clevel\u003e`:\n\n| Level | Emits | Typical use |\n| --- | --- | --- |\n| `off` | nothing | Query is only called via the regular sqlc method; no dynamic wrapping needed |\n| `meta` | `Meta\u003cName\u003e` only | You want runtime introspection (schema export, generic API handler) without the builder surface |\n| `wrap` | `+ Wrap\u003cName\u003e(args...)` | Typed wrappers but filter against column names as strings |\n| `cols` *(default)* | `+ \u003cName\u003eCols` | Full Tier 2 — typed wrappers + typed column refs |\n\nPer-query override example:\n\n```sql\n-- name: TruncateAll :exec\n-- metaquery: off\n-- (Only called from seed/migration code; no builder needed.)\nTRUNCATE authors RESTART IDENTITY CASCADE;\n```\n\n## Safety surface\n\n| Failure mode | Caught | How |\n| --- | --- | --- |\n| Wrong wrapper arg type | compile time | `WrapGetAuthor(\"not an int\")` won't compile |\n| 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 |\n| 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)` |\n| 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 |\n| Scan-struct shape drift | pre-query | `Validate[T]` reflects on T and diffs against `b.OutputColumns()` |\n| Malformed raw SQL in `WhereExpr`/`Agg` | query time | Passed through to Postgres verbatim; caller owns safety |\n\nThe validator is also callable as a library function (`metaquery.ValidateFilter(q, f)`)\nso JSON-driven HTTP handlers can fail fast on bad client input, using the\nsame rules the builder applies internally.\n\n## Relationship to upstream\n\nThis is a clean fork of\n[`github.com/sqlc-dev/sqlc-gen-go`](https://github.com/sqlc-dev/sqlc-gen-go),\nnot a registered GitHub fork. Upstream is tracked as a git remote:\n\n```sh\ngit remote -v\n# origin    git@github.com:IodeSystems/sqlc-go-codegen-metaquery.git\n# upstream  https://github.com/sqlc-dev/sqlc-gen-go.git\n```\n\nTo sync upstream updates:\n\n```sh\ngit fetch upstream\ngit merge upstream/main   # resolve conflicts in the three touched files\n                          #   (internal/gen.go, internal/result.go, go.mod + Makefile)\n                          # import-path conflicts resolve mechanically with sed.\n```\n\n## Caveats / non-goals\n\n- **Postgres + pgx/v5 only.** MySQL and SQLite aren't blocked by the runtime\n  design but aren't implemented; the `mqpgx` adapter is pgx-specific.\n- **The builder wraps, never rewrites.** A filter references the *output*\n  columns of the original query. If you need to filter on a column the\n  query doesn't project, either widen the query or use `WhereExpr`.\n- **`Sum`/`Avg`/`Min`/`Max` aggregates project the source column's type\n  without null-safety** — aggregates over empty groups return NULL. Use\n  `Agg(\"x\", \"coalesce(sum(y), 0)\", \"int64\")` as the escape hatch.\n\n## License\n\nMIT — same as upstream. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiodesystems%2Fsqlc-go-codegen-metaquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiodesystems%2Fsqlc-go-codegen-metaquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiodesystems%2Fsqlc-go-codegen-metaquery/lists"}