Skip to content

Document Postgres support - #156

Merged
mmkal merged 6 commits into
mainfrom
pg-docs
Oct 29, 2026
Merged

mmkal merged 6 commits into
mainfrom
pg-docs

Conversation

@mmkal

@mmkal mmkal commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Postgres works today via @sqlfu/pg, but the docs called it a runtime adapter with "toolchain docs still in progress", and the dialect config key wasn't documented anywhere. This adds two pages to Guides and fixes the Postgres wording elsewhere.

New docs pages:

  • Postgres: install, config, draft → migrate → generate, runtime use, how it differs from SQLite, and Known gaps.
  • Coming from pgkit: pgkit packages and migrator commands mapped to sqlfu, plus what doesn't carry over. It says plainly that sqlfu is not a drop-in replacement.
import {pgDialect} from '@sqlfu/pg';
import {createNodePostgresClient, defineConfig} from 'sqlfu';
import {Pool} from 'pg';

export default defineConfig({
  dialect: pgDialect({adminUrl: process.env.DATABASE_URL!}),
  db: () => {
    const pool = new Pool({connectionString: process.env.DATABASE_URL});
    return {client: createNodePostgresClient(pool), [Symbol.asyncDispose]: () => pool.end()};
  },
  definitions: './definitions.sql',
  migrations: './migrations',
  queries: './sql',
});

I ran the guide end to end against the docker-compose Postgres in packages/pg/test. That turned up real bugs. They're documented, not fixed, in the guide's Known gaps and in tasks/pg.md step three:

  • serial breaks generate (relation "posts_id_seq" does not exist). Identity columns get re-added by every later draft. Enums, domains, functions, triggers, matviews, extensions and non-public schemas either error or get redrafted every time. The cause is the simplified schema renderer in packages/pg/src/impl/schema.ts. The guide uses uuid default gen_random_uuid() ids because those work.
  • pg typegen differs from SQLite: limit 1 returns an array, insert ... returning wrappers return no rows, and = :param params are typed nullable.
  • pg errors are always kind: 'unknown'.

Fixes for these are in progress in #159.

Change Purpose
packages/sqlfu/docs/guides/postgres.md Main entry point for Postgres users. Snippets are copied from a project that ran end to end. Known gaps list what's broken today, so nobody adopts it blind.
packages/sqlfu/docs/guides/pgkit.md Answers "is this a pgkit replacement?" (no), and gives pgkit users a command-by-command map.
website/astro.config.mjs, website/scripts/sync-docs.mjs, website/scripts/sync-llms.mjs, website/public/llms.txt, docs/guides.md, docs/adapters.md guide table Puts both pages in the Guides sidebar, guide tables and llms.txt (as guides, not "Optional").
packages/sqlfu/README.md (+ regenerated root README.md) Intro mentions Postgres. dialect is documented under Configuration. Limitations point at Known gaps instead of "docs in progress". Errors and prior-art lines are corrected.
docs/adapters.md, docs/errors.md, docs/formatter.md, docs/lint-plugin.md, docs/schema-diff-model.md Each says what's true for pg now. sqlfu format follows the config, but the lint rule needs {dialect: 'postgresql'}. pg errors aren't classified. The SQLite diff engine isn't the pg one.
website/src/content/blog/introducing-sqlfu.md The "what it is not for" line said the pg story needed docs. It now links the guide (same line PR #121 last touched).
packages/pg/README.md, packages/pg/package.json description @sqlfu/pg's npm page was empty.
tasks/pg.md, tasks/complete/2026-10-29-pg-docs.md tasks/pg.md still said step one was in review with step two unticked. It now has a current status and a step-three bug list.

Verified: astro build, node --test website/test/, and the rendered dist/ links for the new pages.

Claude Code session: "Postgres support status" (local_d8095ac3-f355-44e4-a174-578140e5095e, CLI 403039a7-59d0-4757-851e-4d2a4e778da2)

🤖 Generated with Claude Code

Package size — packed 280.7 kB (+142 B, 0)

Package size

main this PR Δ
packed 280.6 kB 280.7 kB 0
unpacked 1.12 MB 1.12 MB 0
files 226 226 0

dist/vendor/*.js bundles

main this PR Δ
vendor/sha256.js 4.3 kB 4.3 kB 0
vendor/sql-formatter/*.js 94.5 kB 94.5 kB 0
vendor/sqlfu-sqlite-parser/*.js 17.2 kB 17.2 kB 0
vendor/standard-schema/*.js 2.8 kB 2.8 kB 0
vendor/typesql/*.js 134.9 kB 134.9 kB 0

Measured with npm pack --dry-run --json on sqlfu (0.0.0-dev on main vs 0.0.0-dev on this PR).

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@156

commit: 32e0905

mmkal and others added 5 commits October 29, 2026 08:52
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>
@mmkal
mmkal marked this pull request as ready for review October 29, 2026 13:25
@mmkal
mmkal merged commit 7666978 into main Oct 29, 2026
9 checks passed
@cursor

cursor Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Documentation and website navigation only; no runtime or toolchain code changes in this PR.

Overview
Adds Postgres and Coming from pgkit as first-class docs so @sqlfu/pg and dialect: pgDialect(...) are documented instead of “runtime adapter only / toolchain in progress.”

The Postgres guide walks through install, config (adminUrl, db factory with async dispose), draft → migrate → generate, runtime with createNodePostgresClient, SQLite differences, and a Known gaps section (schema renderer limits, typegen parity, unclassified errors). Coming from pgkit maps packages and migrator commands and states sqlfu is not a drop-in replacement.

READMEs (root and packages/sqlfu), Configuration (dialect), adapters/errors/formatter/lint-plugin/schema-diff pages, and the intro blog line are updated for current Postgres behavior (e.g. ESLint {dialect: 'postgresql'}, pg errors as kind: 'unknown'). packages/pg/README.md gives the npm package a short entry point. The site sidebar, doc sync scripts, and llms.txt include the new guides. tasks/pg.md reflects shipped step two and a step-three bug list; verification notes live in the completed task file.

Reviewed by Cursor Bugbot for commit 32e0905. Bugbot is set up for automated code reviews on this repo. Configure here.

mmkal added a commit that referenced this pull request Oct 29, 2026
pg-docs (#156) was squash-merged to main; this drops its commits from #159's diff.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mmkal
mmkal deleted the pg-docs branch October 29, 2026 13:25
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