Skip to content

Classify Postgres errors by SQLSTATE - #163

Closed
mmkal wants to merge 11 commits into
mainfrom
pg-error-kinds
Closed

mmkal wants to merge 11 commits into
mainfrom
pg-error-kinds

Conversation

@mmkal

@mmkal mmkal commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Replaces #160, which GitHub closed when its base branch (pg-docs) was deleted after #156 merged.

Postgres errors from createNodePostgresClient now get a real SqlfuError.kind, mapped from the SQLSTATE. Until now every Postgres error came back as kind: 'unknown'.

try {
  await insertUser(client, {email: 'ada@example.com'}); // already exists
} catch (error) {
  error.kind;       // before: 'unknown'   after: 'unique_violation'
  error.cause.code; // '23505' (unchanged)
}
kind SQLSTATE
syntax 42601
missing_table 42P01
missing_column 42703
unique_violation 23505 (primary keys too)
not_null_violation 23502
foreign_key_violation 23503
check_violation 23514
transient 40001 serialization failure, 40P01 deadlock, 55P03 lock not available

Everything else stays 'unknown', and the SQLSTATE is still on .cause.code.

Change Purpose
classifyPostgresError in packages/sqlfu/src/errors.ts SQLSTATE → kind lookup. Kind names already match SQLSTATE names, so it's a single switch.
mapSqliteDriverError → mapDriverError, picking the classifier by system wrapSyncClientErrors / wrapAsyncClientErrors already read client.system. 'postgresql' now gets the SQLSTATE classifier, so none of the 12 SQLite adapters change.
packages/pg/test/client-errors.test.ts One test per kind plus an unknown case, each produced by a real Postgres (the docker-compose one CI already runs for @sqlfu/pg). The transient tests make real lock contention: for update nowait against a held row lock, and a repeatable-read write conflict.
docs/errors.md, docs/guides/postgres.md, README.md Remove the "Postgres kind is always 'unknown'" notes (added in #156). Add a kind → SQLite / SQLSTATE table to the errors page.
tasks/pg.md, tasks/complete/2026-10-29-pg-error-kinds.md Tick the step-three error item and record the decisions.

Decisions worth a look:

  • transient means lock contention or a serialization conflict, where retrying the transaction usually works, like SQLite's BUSY/LOCKED. Connection-level failures (class 08, 57P01, 53300) stay unknown.
  • No new kinds. The original error-taxonomy task floated permission_denied (42501) for when pg landed. That's left for a follow-up.
  • Before this change the syntax test already passed, but only because the SQLite message fallback matched "syntax error at or near". Postgres errors no longer go through that fallback.

Session: cae4911f-3ee7-4867-864d-076bcf92f7ac

🤖 Generated with Claude Code

Package size — packed 281.2 kB (+492 B, +0.2%)

Package size

main this PR Δ
packed 280.7 kB 281.2 kB +0.2%
unpacked 1.12 MB 1.12 MB +0.1%
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).

mmkal and others added 11 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>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
createNodePostgresClient returns kind 'unknown' for every Postgres error
except syntax errors (which only match via the SQLite message fallback).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
createNodePostgresClient errors now get a real SqlfuError.kind. The
classifier reads the SQLSTATE from the pg error's .code and is picked by
client.system, so the SQLite adapters are unchanged.
mapSqliteDriverError is renamed mapDriverError since it now covers both.

Removes the Errors note from the Postgres guide's Known gaps, adds a
kind -> SQLite / SQLSTATE table to docs/errors.md, and ticks the
step-three item in tasks/pg.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	README.md
#	packages/sqlfu/README.md
#	packages/sqlfu/docs/errors.md
#	packages/sqlfu/docs/guides/postgres.md
#	tasks/pg.md
#160 was closed when its base branch was deleted; #163 replaces it.

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

commit: 6fdfd15

@mmkal

mmkal commented Oct 29, 2026

Copy link
Copy Markdown
Collaborator Author

🤖 Moved into the shared Postgres PR #159 (branch pg-real-schemas), alongside the schema-renderer and typegen fixes.

@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