From 8064e1184cfd1da9003b8e4bbe4fb76c8f5c36b0 Mon Sep 17 00:00:00 2001
From: fox0430 <shuu.n@protonmail.com>
Date: Wed, 22 Apr 2026 17:56:36 +0900
Subject: [PATCH] Add pg_error module

---
 async_postgres/pg_connection.nim | 21 ++-----------------
 async_postgres/pg_errors.nim     | 35 ++++++++++++++++++++++++++++++++
 async_postgres/pg_protocol.nim   |  6 ++----
 async_postgres/pg_types/core.nim |  9 +++-----
 4 files changed, 42 insertions(+), 29 deletions(-)
 create mode 100644 async_postgres/pg_errors.nim

diff --git a/async_postgres/pg_connection.nim b/async_postgres/pg_connection.nim
index 1b55b8a..c8856fa 100644
--- a/async_postgres/pg_connection.nim
+++ b/async_postgres/pg_connection.nim
@@ -2,7 +2,7 @@ import std/[tables, sets, strutils, uri, deques, options, lists]
 when defined(posix):
   import std/posix
 
-import async_backend, pg_protocol, pg_auth, pg_types
+import async_backend, pg_errors, pg_protocol, pg_auth, pg_types
 
 when hasChronos:
   import chronos/streams/tlsstream
@@ -13,7 +13,7 @@ elif hasAsyncDispatch:
   when defined(ssl):
     import std/[net, openssl, tempfiles, os]
 
-export PgError
+export pg_errors
 
 # TCP keepalive socket options (not exported by posix module)
 when defined(linux):
@@ -33,23 +33,6 @@ else:
   .}
 
 type
-  PgConnectionError* = object of PgError
-    ## Connection failures, disconnections, SSL/auth errors.
-
-  PgQueryError* = object of PgError
-    ## SQL execution errors from the server (ErrorResponse).
-    sqlState*: string ## 5-char SQLSTATE code (e.g. "42P01"), empty if unavailable.
-    severity*: string ## e.g. "ERROR", "FATAL"
-    detail*: string ## DETAIL field, empty if not present.
-    hint*: string ## HINT field, empty if not present.
-
-  PgTimeoutError* = object of PgError ## Operation timed out.
-
-  PgPoolError* = object of PgError ## Pool exhaustion, pool closed, or acquire timeout.
-
-  PgNotifyOverflowError* = object of PgError
-    dropped*: int ## Number of notifications dropped due to queue overflow
-
   PgConnState* = enum
     ## Connection lifecycle state.
     csConnecting
diff --git a/async_postgres/pg_errors.nim b/async_postgres/pg_errors.nim
new file mode 100644
index 0000000..0cd55a8
--- /dev/null
+++ b/async_postgres/pg_errors.nim
@@ -0,0 +1,35 @@
+## Exception hierarchy.
+##
+## All library-raised exceptions derive from ``PgError`` so callers can catch
+## every pg-specific failure with a single ``except PgError`` clause. ``ProtocolError``
+## is a subtype of ``PgConnectionError`` because a protocol-level violation
+## desynchronises the wire stream — the only viable recovery is to tear down
+## and re-establish the connection.
+
+type
+  PgError* = object of CatchableError
+    ## General PostgreSQL error. Base type for all pg-specific errors.
+
+  PgTypeError* = object of PgError
+    ## Raised when a PostgreSQL value cannot be converted to the requested Nim type.
+
+  PgConnectionError* = object of PgError
+    ## Connection failures, disconnections, SSL/auth errors.
+
+  ProtocolError* = object of PgConnectionError
+    ## Raised on PostgreSQL wire protocol violations. The connection stream is
+    ## desynchronised after this error and must be torn down.
+
+  PgQueryError* = object of PgError
+    ## SQL execution errors from the server (ErrorResponse).
+    sqlState*: string ## 5-char SQLSTATE code (e.g. "42P01"), empty if unavailable.
+    severity*: string ## e.g. "ERROR", "FATAL"
+    detail*: string ## DETAIL field, empty if not present.
+    hint*: string ## HINT field, empty if not present.
+
+  PgTimeoutError* = object of PgError ## Operation timed out.
+
+  PgPoolError* = object of PgError ## Pool exhaustion, pool closed, or acquire timeout.
+
+  PgNotifyOverflowError* = object of PgError
+    dropped*: int ## Number of notifications dropped due to queue overflow
diff --git a/async_postgres/pg_protocol.nim b/async_postgres/pg_protocol.nim
index 762f907..f3b0bb9 100644
--- a/async_postgres/pg_protocol.nim
+++ b/async_postgres/pg_protocol.nim
@@ -1,11 +1,9 @@
 import std/[options, tables]
 
-import pg_bytes
+import pg_bytes, pg_errors
+export pg_errors
 
 type
-  ProtocolError* = object of CatchableError
-    ## Raised on PostgreSQL wire protocol violations.
-
   FrontendMessageKind* = enum
     ## Message types sent from client to server.
     fmkStartup
diff --git a/async_postgres/pg_types/core.nim b/async_postgres/pg_types/core.nim
index 2aeebbb..14055c0 100644
--- a/async_postgres/pg_types/core.nim
+++ b/async_postgres/pg_types/core.nim
@@ -1,12 +1,9 @@
 import std/[hashes, options, sequtils, strutils, tables, net]
 
-type
-  PgError* = object of CatchableError
-    ## General PostgreSQL error. Base type for all pg-specific errors.
-
-  PgTypeError* = object of PgError
-    ## Raised when a PostgreSQL value cannot be converted to the requested Nim type.
+import ../pg_errors
+export pg_errors
 
+type
   PgUuid* = distinct string
     ## UUID value stored as its string representation (e.g. "550e8400-e29b-41d4-a716-446655440000").