Add a Postgres dialect

[Makisuo]

Stacked on #1. Finishes the dialect work: identifier quoting, clause differences, and a Postgres dialect that runs on real Postgres. The design notes, including where the plan changed, are in design/dialects.md; the user-facing guide is docs/postgres.md.

Identifiers through the dialect

Column refs, qualifiers, tables, aliases, CTE names and group/order keys render as Ident fragments that Dialect.quoteIdent quotes. A column ref carries its qualifier separately (ident("Name", "e")), so a ClickHouse Nested column like Events.Name is never split, while a db.table qualifier is quoted per segment. Untyped boolean and DateTime literals go through the dialect as well. ClickHouse writes names bare, so its output is byte-identical.

Clause differences as capability flags

Dialect.clauses holds what differs between the two databases:

• format: .format() fails to compile where FORMAT does not exist, rather than being dropped silently.
• derivedTableAlias: a wrapped union gets AS "__union".
• groupByAlias: Postgres resolves a bare name in GROUP BY to an input column before a select alias, so select({ Service: lower($.Service) }).groupBy("Service") would group by the raw column. Postgres keys are written by position (GROUP BY 1), which keeps ClickHouse's meaning. There is a test that fails without this.

The plan was to move compile.ts into a ClickHouse dialect class. Three flags read in three places did the job without relocating ~1100 lines.

The ./postgres entry point

• postgresDialect: double-quoted identifiers, standard string literals (an E'...' string only when a value spells the param marker, so the marker can be hex-escaped), $n binding. Dialect.paramCodecs makes param.bool bind a boolean and param.dateTime an ISO-8601 instant, which no session time zone can reinterpret.
• Column types on the shared descriptor, with codecs that accept what common drivers send: int8 and numeric as number, string or bigint; timestamptz as a Date or text; jsonb parsed.
• Functions Postgres spells differently: count(*), countIf/sumIf as FILTER (WHERE ...), percentile_cont, date_trunc(..., 'UTC'), date_bin, array_agg, ->>, coalesce.
• compile / compileUnsafe / compileUnion / compileUnionUnsafe that default to Postgres.

Testing

src/pg/postgres.test.ts runs every query on PGlite (Postgres 17 in WASM, new dev dependency), so a test passes only if Postgres accepts the SQL, binds the params, and the rows decode through the declared types. It covers aggregates with FILTER, dateBin/dateTrunc buckets with Date and DateTime.Utc params, a join to a schema-qualified table over a subquery, a CTE, an ordered union, a value containing a quote, a backslash and the param marker (as a bound param, a literal, and a LIKE pattern), boolean binding, jsonb comparison, and the GROUP BY alias case.

• tsc for the library and the tests
• vitest run src/ch src/sql src/pg src/docs-examples.test.ts: 324 passed
• bun run build, the doc-citation and export-catalog checks, and the doc-example check, which now runs the docs/postgres.md example on PGlite and asserts its rows
• Not run: the benchmark tests and test:clickhouse (live ClickHouse via Docker)

Not in this PR

• The root entry's ClickHouse functions (quantile, toStartOfInterval, map subscripts) still write ClickHouse SQL under any dialect; they could refuse to compile under another one instead.
• The package name and root exports are unchanged.

🤖 Generated with Claude Code

---

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

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 54428098-a414-44a2-aa7d-1c73a5b3a977

📥 Commits

Reviewing files that changed from the base of the PR and between ffa089d and 2abbdd4.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (24)

• CHANGELOG.md
• README.md
• design/dialects.md
• docs/README.md
• docs/params-and-compilation.md
• docs/postgres.md
• docs/reference.md
• package.json
• scripts/check-doc-examples.mjs
• src/ch/compile.ts
• src/ch/dialect.test.ts
• src/ch/dialect.ts
• src/ch/expr.ts
• src/ch/index.ts
• src/ch/literal.ts
• src/pg/dialect.ts
• src/pg/functions.ts
• src/pg/postgres.test.ts
• src/pg/types.ts
• src/postgres.ts
• src/sql/literal-syntax.ts
• src/sql/sql-fragment.ts
• src/sql/sql-syntax.ts
• tsdown.config.ts

 ________________________________________________________________________
< Brb...inventing the time machine to fix your code before you wrote it. >
 ------------------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• 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.}