Add returning() to inserts on Postgres

[Makisuo]

Phase 2 of design/writes.md. Stacked on #9; review that first.

const created = CH.insertInto(ApiKeys)
	.values({ id: CH.param.string("id"), org_id: CH.param.string("orgId"), name: "default" })
	.returning(($) => ({ id: $.id, createdAt: $.created_at }))

const [row] = yield* Db.run(created, { id, orgId }) // { id: string; createdAt: DateTime.Utc }

What changes

• returning takes column names or a callback, the same two forms as select. Calling it again replaces the list.
• Decoding. The row schema is derived from the RETURNING list, so run returns decoded rows. An untypedExpr (such as Maple's pg_current_xact_id()::xid::text) leaves the insert undecoded, with rowSchemaSource: "none" and the alias in untypedColumns.
• CompiledQuery.returning lists the aliases. run reads it to choose between the row path and the command path, so a precompiled insert also runs correctly.
• Dialects. New optional DialectClauses.returning (absent means no). Postgres sets it. On ClickHouse, returning is a QueryBuilderDefect at compile, the same as .format() on Postgres.

Testing

• bun run typecheck and bun run test: 497 unit tests and the doc checks pass.
• New unit tests cover the exact SQL, the derived schema, untyped expressions and the ClickHouse defect; type tests cover both forms and RowOf.
• The PGlite round trip now inserts with returning and checks the decoded defaults (uses, revoked, created_at).

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 12 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 62291b09-3476-492c-839e-eda4ced7c7c5

📥 Commits

Reviewing files that changed from the base of the PR and between ecace6a and ee97ecb.

📒 Files selected for processing (13)

• CHANGELOG.md
• design/writes.md
• docs/database.md
• docs/inserts.md
• docs/reference.md
• src/ch/compile.ts
• src/ch/dialect.ts
• src/ch/insert.test-d.ts
• src/ch/insert.test.ts
• src/ch/insert.ts
• src/database/database.test.ts
• src/database/database.ts
• src/pg/dialect.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}