Skip to content

Classify Postgres errors by SQLSTATE - #160

Closed
mmkal wants to merge 3 commits into
pg-docsfrom
pg-error-kinds
Closed

mmkal wants to merge 3 commits into
pg-docsfrom
pg-error-kinds

Conversation

@mmkal

@mmkal mmkal commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #156 (pg-docs). Merge that first.

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

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

commit: f1e7027

mmkal and others added 2 commits October 29, 2026 13:22
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>
@mmkal
mmkal deleted the branch pg-docs October 29, 2026 13:25
@mmkal mmkal closed this Oct 29, 2026
@mmkal

mmkal commented Oct 29, 2026

Copy link
Copy Markdown
Collaborator Author

🤖 Closed automatically when pg-docs was deleted after #156 merged. Continued in #163 (same branch, now based on main).

mmkal added a commit that referenced this pull request Oct 29, 2026
#160 was closed when its base branch was deleted; #163 replaces it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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