Postconditions: what we check

• query · neon-db-error

  error
  WhenPostgreSQL error (syntax error, constraint violation, undefined table, permission denied, etc.) OR network error (connection refused, timeout, scale-to-zero activation failure)
  ThrowsNeonDbError extends Error with fields: code (PostgreSQL SQLSTATE 5-char code), severity, detail, hint, constraint, table, column, sourceError. Common codes: 42601 (syntax), 23505 (unique), 23503 (foreign key), 42P01 (undefined table). Network errors include Neon scale-to-zero activation timeouts on first query after idle period.
  Required handlingCaller MUST wrap in try-catch. NeonDbError carries a PostgreSQL SQLSTATE code in error.code. Distinguish constraint violations (23505/23503) from network errors (sourceError set) from query errors. All uncaught errors crash the request handler.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• connect · connection-error

  error
  WhenCannot establish WebSocket connection to Neon — database suspended, network error, invalid connection string, or pool exhausted (connectionTimeoutMillis exceeded)
  ThrowsNeonDbError with sourceError set to the underlying network error. Pool exhaustion: Error with message containing "timeout" when all pool clients are checked out and connectionTimeoutMillis elapses.
  Required handlingCaller MUST wrap in try-catch. For Pool.connect(), use try/finally to ALWAYS release the client even if the query throws: const client = await pool.connect(); try { await client.query(...); } finally { client.release(); } Failure to release causes pool exhaustion and eventual application hang.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• end · close-error

  warning
  Whenin-flight queries are abandoned or WebSocket close handshake fails
  ThrowsError wrapping the underlying WebSocket error
  Required handlingCaller SHOULD wrap in try-catch, especially in shutdown handlers. Uncaught errors from pool.end() during SIGTERM handling will crash the process.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• neon · neon-db-error

  error
  WhenPostgreSQL error (syntax error, constraint violation, undefined table, permission denied, etc.) OR network error (connection refused, timeout, scale-to-zero activation failure)
  ThrowsNeonDbError extends Error with fields: code (PostgreSQL SQLSTATE 5-char code), severity, detail, hint, constraint, table, column, sourceError. Common codes: 42601 (syntax), 23505 (unique), 23503 (foreign key), 42P01 (undefined table). Network errors include Neon scale-to-zero activation timeouts on first query after idle period.
  Required handlingCaller MUST wrap in try-catch. Every sql`...` tagged template call is a live HTTP request that can fail. Uncaught errors crash the request handler (Next.js route, etc.).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• transaction · transaction-statement-error

  error
  WhenAny statement within the transaction fails — constraint violation (23505 unique, 23503 foreign key), syntax error (42601), serialization failure (40001), or deadlock (40P01). The entire transaction is rolled back; no partial commits occur.
  ThrowsNeonDbError carrying the PostgreSQL SQLSTATE code of the first failing statement.
  Required handlingCaller MUST wrap sql.transaction() in try-catch. Because all statements are batched into a single HTTP request, partial results are never returned — on any failure the entire array rejects. Uncaught NeonDbError crashes the request handler (Next.js route, Cloudflare Worker, etc.).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• transaction · transaction-isolation-conflict

  warning
  WhenTransaction isolation level is REPEATABLE READ or SERIALIZABLE and a concurrent write conflict is detected (SQLSTATE 40001 serialization_failure or 40P01 deadlock).
  ThrowsNeonDbError with SQLSTATE 40001 or 40P01. These errors require retry logic — they are expected under high concurrency and do not indicate a bug.
  Required handlingCallers using isolationLevel: 'RepeatableRead' or 'Serializable' MUST implement retry logic for SQLSTATE 40001/40P01 errors. Treating serialization failures as fatal errors causes unnecessary user-visible failures under load.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[3][4]
• transaction · transaction-network-error

  error
  WhenHTTP request to Neon's proxy fails mid-transaction (network timeout, Neon scale-to-zero activation delay, connection reset). Transaction state is unknown — may have committed or rolled back on the server side.
  ThrowsNeonDbError with sourceError set to the underlying network error.
  Required handlingCallers MUST handle NeonDbError where sourceError is set (network errors) separately from SQLSTATE errors. For idempotent transactions, implement retry with exponential backoff. For non-idempotent transactions (e.g. payment processing), do NOT blindly retry — implement idempotency keys to safely detect duplicate commits.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[3]
• sql_query · neon-db-error

  error
  WhenPostgreSQL error (syntax error, constraint violation, undefined table, permission denied, etc.) returned by Neon's HTTP proxy as HTTP 400 with SQLSTATE fields, OR network error (DNS failure, connection refused, fetch() rejection, scale-to-zero activation timeout) when the underlying fetch() call rejects.
  ThrowsNeonDbError extends Error. On PostgreSQL errors carries: code (SQLSTATE 5-char), severity, detail, hint, position, constraint, table, column. On network errors carries sourceError set to the underlying fetch() rejection reason. Common SQLSTATE codes: 42601 (syntax), 23505 (unique violation), 23503 (foreign key), 42P01 (undefined table), 42501 (insufficient privilege).
  Required handlingCaller MUST wrap sql.query() in try-catch. Every call is a live HTTP fetch — DNS errors, TLS handshake failures, and Neon scale-to-zero activation timeouts all surface as NeonDbError with sourceError set. Uncaught errors crash the request handler (Next.js route, Cloudflare Worker, Vercel Edge Function). Branch handling on `error.code` (constraint violations) vs `error.sourceError` (network errors).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][5]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.