Skip to content

Postgres typegen: same wrapper shapes as SQLite - #162

Closed
mmkal wants to merge 10 commits into
mainfrom
pg-typegen-parity
Closed

mmkal wants to merge 10 commits into
mainfrom
pg-typegen-parity

Conversation

@mmkal

@mmkal mmkal commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

sqlfu generate now emits the same wrappers for Postgres as for SQLite. Before, a project that switched to pgDialect got arrays for limit 1 queries, client.run for insert ... returning, and string | null for every where param.

Given this in sql/queries.sql:

/** @name findPostBySlug */
select id, slug, title from posts where slug = :slug limit 1;

/** @name insertPost */
insert into posts (slug, title, body) values (:slug, :title, :body) returning id, slug;

/** @name retitlePost */
update posts set title = :title where slug = :slug returning id, title;
// before, with pgDialect
await findPostBySlug(client, {slug});           // Promise<Result[]>, params: {slug: string | null}
await insertPost(client, {slug, title, body});  // client.run(...): no row type
await retitlePost(client, {title, slug});       // client.run(...)

// after: same as SQLite
await findPostBySlug(client, {slug});           // Promise<Result | null>, params: {slug: string}
await insertPost(client, {slug, title, body});  // Promise<insertPost.Result>
await retitlePost(client, {title}, {slug});     // SET values go in `data`, returns Promise<retitlePost.Result>

The new spec, packages/pg/test/generate-parity.test.ts, runs generate on one project with each dialect and asserts the wrapper signatures and namespace types are identical.

Change Purpose
New packages/pg/src/impl/query-shape.ts Reads the pgsql-ast-parser AST and a few catalog facts (unique indexes, column nullability, aggregate and set-returning functions from pg_proc). It decides one row vs many, which params are nullable, and which update params are SET values. The rules copy typesql's SQLite analyzer, so the shared wrapper generator gets the same descriptor fields from both dialects.
packages/pg/src/impl/typegen.ts Loads the catalog once per analyzeQueries, then uses the query shape for multipleRowsResult, param notNull and data. Sets returning: true for DML that has result columns, which is what turns client.run into client.all + row. If the AST parse fails, keeps today's loose shape (array, nullable params).
New packages/pg/test/generate-parity.test.ts End-to-end spec: six cases (limit 1, no from, aggregate, insert/delete RETURNING, update RETURNING, where params). Each pins SQLite's output in an inline snapshot and requires pg to equal it.
New packages/pg/test/fixtures/typegen/result-shape.md Pg-only details: unique/composite/partial indexes, joins, or, window functions, set-returning functions, is null params, nullable insert/on conflict targets, the data split, and the parse-failure fallback.
packages/pg/test/typegen-fixture-runner.ts + every fixtures/typegen/*.md Fixture output now includes multipleRowsResult, plus returning/data when set. Where-params flip to notNull: true.
packages/sqlfu/docs/guides/postgres.md Runtime example no longer destructures findPostBySlug. The "Generated wrappers" known gaps now list what's still different (see below) instead of the four fixed items.
tasks/pg.md, tasks/complete/2026-10-29-pg-typegen-parity.md Step three item two ticked; task file holds the decisions and follow-ups.

Before/after: analyzer fixtures

limitations.md › update-without-returning (update test_table set n = $1 where id = $2):

# before
parameters:
  - {name: $1, tsType: number, notNull: false}
  - {name: $2, tsType: number, notNull: false}

# after
multipleRowsResult: false
parameters:
  - {name: $2, tsType: number, notNull: true}
data:
  - {name: $1, tsType: number, notNull: false}   # n is nullable

dml-returning.md cases gain returning: true and multipleRowsResult: false. Every other case gains a multipleRowsResult line, and its where-params go from notNull: false to true.

Decisions to check

  • Copying SQLite's rules, warts included. DML+RETURNING is always one row, even insert ... select ... returning. That's what typesql does. Fixing it is a change for both dialects, not a pg-only one.
  • One deliberate difference: pg checks every unique index, so where slug = :slug returns Result | null even when the table also has a primary key. typesql only notices this when a table has exactly one unique column. SQLite is the buggy side here.
  • Set-returning functions (select generate_series(1, 3)) stay multi-row even with no from. SQLite doesn't have them.
  • The original report said FROM-less selects get no columns. That was a stale note in tasks/complete/2026-05-07-pg-package.md; the columns already worked. The real gap was the row count, which is fixed here.

Still different (now in the guide's Known gaps)

  • int8 (count(*)) is typed bigint and numeric is typed number, but pg returns both as strings by default.
  • DDL in a query file gets no wrapper on pg; SQLite emits a client.run one.
  • cast(...) drops not-null in the vendored pgkit nullability pass.
  • Queries pgsql-ast-parser can't parse (is not distinct from, similar to) fall back to arrays and nullable params.

Claude Code session: local_ca9de0dd-5a56-41ce-8314-da6da8e927c1 ("Match Postgres typegen output to SQLite")

🤖 Generated with Claude Code

mmkal and others added 8 commits October 29, 2026 08:45
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Postgres guide walks a pg project through draft, migrate, generate and
runtime use, verified end to end against the docker-compose Postgres in
packages/pg/test. It lists the gaps found while verifying: the simplified
schema reader in packages/pg/src/impl/schema.ts drops serial/identity,
enums, domains, functions, triggers, matviews, extensions, non-public
schemas and generated columns, and pg typegen differs from SQLite for
limit 1, returning, and nullable params.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The docs called Postgres a runtime adapter with toolchain docs 'still in
progress'. Postgres has a working dialect (draft, migrate, check, generate,
format, UI), so: README documents the dialect config key and points
limitations at the guide's known gaps; adapters, errors, formatter, lint
plugin and schema-diff pages say what's true for pg today (including that pg
errors are always kind 'unknown'); the intro blog post links the guide;
@sqlfu/pg gets a README so its npm page isn't empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tasks/pg.md was stale (step one 'in review', step two unticked though
PRs #87-#89 merged). It now has a current status summary and a step
three checklist of the bugs found while verifying the Postgres guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main added a celld guide alongside the Postgres guides here. Both sides
appended to the Guides description in sync-docs.mjs; kept both and
regenerated llms.txt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Task file for step three item two of tasks/pg.md: limit 1 / FROM-less /
aggregate selects, DML RETURNING, update data split and where-param
nullability should generate the same wrappers on pg as on SQLite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pkg-pr-new

pkg-pr-new Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/sqlfu@162

commit: 149a2c5

mmkal and others added 2 commits October 29, 2026 13:28
Generates one project with SQLite and with pgDialect and asserts the
wrapper signatures and namespace types match. All six cases fail today:
limit 1 / FROM-less / aggregate selects return arrays, RETURNING wrappers
call client.run, update SET params aren't split into data, and where
params are typed nullable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New packages/pg/src/impl/query-shape.ts reads the pgsql-ast-parser AST
plus catalog facts (unique indexes, column nullability, aggregate and
set-returning functions) and fills the descriptor fields the shared
wrapper generator keys off:

- multipleRowsResult: false for limit 1, FROM-less selects, aggregates
  without group by, and lookups covering a unique index. DML is always
  single-row, as in typesql. Set-returning functions stay multi-row.
- params: not-null unless tested with is [not] null or inserted/set into
  a nullable column.
- data: update SET params, when they come before every other param.

returning is set for DML that has result columns, so RETURNING wrappers
call client.all and return the row instead of client.run.

Analyzer fixtures now record multipleRowsResult (plus returning/data when
set); new result-shape.md covers the pg-only rules. The Postgres guide's
Known gaps list the differences that remain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mmkal

mmkal commented Oct 29, 2026

Copy link
Copy Markdown
Collaborator Author

🤖 Folded into the shared Postgres PR #159 (branch pg-real-schemas), which now carries these commits. Spec moved to the "Typegen parity" section of tasks/pg-real-schemas.md.

@mmkal mmkal closed this Oct 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant