fix: log-XOR-raise — demote the pre-raise log to DEBUG, revise the contract (D1)

every wrapped method did log.exception (ERROR + traceback) immediately before re-raising
the driver error — the same failure reported at two layers (the log AND the raised
exception). that is the log-and-raise violation: a method that re-raises must not also
error-log, because the caller — which alone knows whether the failure is fatal or routine
— is the one that logs. demote all wrapped-method logs to log.debug(..., exc_info=True):
the traceback stays available at DEBUG, and the raised exception is the single loud
terminal signal. docstring updated from "logs via getLogger and re-raises" to the
corrected raise-XOR-log contract. no behavior change beyond log level — the fail-loud
re-raise is unchanged.

Signed-off-by: disqualifier <dev@disqualifier.me>

src/psql/psql.py

@@ -34,8 +34,11 @@ placeholders / injection safety:
 
 errors (FAIL LOUD - unlike the mongo lib's swallow-and-default):
     every method catches the driver error (asyncpg.PostgresError / InterfaceError, OSError
-    on connection loss), logs via getLogger(__name__), and re-raises. a None/[] return is
+    on connection loss) and re-raises it - the raised exception IS the signal, and the
-    only ever a real result (no row, empty table) - never a swallowed failure. for anything
+    caller (which alone knows fatal-vs-routine) decides and logs. the wrapped method itself
+    logs only at DEBUG (with the traceback) so a failure isn't reported twice (raise XOR
+    log). a None/[] return is only ever a real result (no row, empty table) - never a
+    swallowed failure. for anything
     not wrapped, use the raw `.pool` property (the asyncpg.Pool).
 """
 
@@ -129,7 +132,7 @@ class PsqlDB:
                 pool = await asyncpg.create_pool(**self._config)
                 await pool.fetchval("SELECT 1")
             except _DRIVER_ERRORS:
-                log.exception("psql.connect() failed")
+                log.debug("psql.connect() failed", exc_info=True)
                 if pool is not None:
                     await pool.close()
                 raise
@@ -158,7 +161,7 @@ class PsqlDB:
         try:
             await self._pool.close()
         except _DRIVER_ERRORS:
-            log.exception("psql.close()")
+            log.debug("psql.close()", exc_info=True)
             raise
         finally:
             self._pool = None
@@ -191,7 +194,7 @@ class PsqlDB:
         try:
             return await self.pool.execute(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.execute(): %s", query)
+            log.debug("psql.execute(): %s", query, exc_info=True)
             raise
 
     async def fetch(self, query: str, *params: Any) -> List[dict]:
@@ -199,7 +202,7 @@ class PsqlDB:
         try:
             rows = await self.pool.fetch(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.fetch(): %s", query)
+            log.debug("psql.fetch(): %s", query, exc_info=True)
             raise
         return [_row_to_dict(r) for r in rows]
 
@@ -211,7 +214,7 @@ class PsqlDB:
         try:
             row = await self.pool.fetchrow(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.fetchone(): %s", query)
+            log.debug("psql.fetchone(): %s", query, exc_info=True)
             raise
         return _row_to_dict(row) if row is not None else None
 
@@ -220,7 +223,7 @@ class PsqlDB:
         try:
             return await self.pool.fetchval(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.fetchval(): %s", query)
+            log.debug("psql.fetchval(): %s", query, exc_info=True)
             raise
 
     def transaction(self):
@@ -244,7 +247,7 @@ class PsqlDB:
         try:
             await self.pool.execute(f"CREATE DATABASE {_quote_ident(name)}")
         except _DRIVER_ERRORS:
-            log.exception("psql.create_database(%s)", name)
+            log.debug("psql.create_database(%s)", name, exc_info=True)
             raise
 
     async def create_table(self, name: str, schema: Dict[str, str]) -> None:
@@ -259,7 +262,7 @@ class PsqlDB:
         try:
             await self.pool.execute(f"CREATE TABLE IF NOT EXISTS {_quote_ident(name)} ({cols})")
         except _DRIVER_ERRORS:
-            log.exception("psql.create_table(%s)", name)
+            log.debug("psql.create_table(%s)", name, exc_info=True)
             raise
 
     async def drop(self, name: str, *, table: bool = True) -> None:
@@ -268,7 +271,7 @@ class PsqlDB:
         try:
             await self.pool.execute(f"DROP {kind} IF EXISTS {_quote_ident(name)}")
         except _DRIVER_ERRORS:
-            log.exception("psql.drop(%s)", name)
+            log.debug("psql.drop(%s)", name, exc_info=True)
             raise
 
     async def insert(self, table: str, values: Dict[str, Any]) -> int:
@@ -284,7 +287,7 @@ class PsqlDB:
         try:
             status = await self.pool.execute(query, *values.values())
         except _DRIVER_ERRORS:
-            log.exception("psql.insert(%s)", table)
+            log.debug("psql.insert(%s)", table, exc_info=True)
             raise
         return _status_count(status)
 
@@ -299,7 +302,7 @@ class PsqlDB:
         try:
             rows = await self.pool.fetch(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.get(%s)", table)
+            log.debug("psql.get(%s)", table, exc_info=True)
             raise
         return [_row_to_dict(r) for r in rows]
 
@@ -310,7 +313,7 @@ class PsqlDB:
         try:
             row = await self.pool.fetchrow(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.get_one(%s)", table)
+            log.debug("psql.get_one(%s)", table, exc_info=True)
             raise
         return _row_to_dict(row) if row is not None else None
 
@@ -324,7 +327,7 @@ class PsqlDB:
         try:
             status = await self.pool.execute(query, *params)
         except _DRIVER_ERRORS:
-            log.exception("psql.delete(%s)", table)
+            log.debug("psql.delete(%s)", table, exc_info=True)
             raise
         return _status_count(status)
 
@@ -335,7 +338,7 @@ class PsqlDB:
         try:
             return bool(await self.pool.fetchval(query, *params))
         except _DRIVER_ERRORS:
-            log.exception("psql.exists(%s)", table)
+            log.debug("psql.exists(%s)", table, exc_info=True)
             raise
 
     async def upsert(self, table: str, values: Dict[str, Any], conflict: Sequence[str]) -> int:
@@ -357,7 +360,7 @@ class PsqlDB:
         try:
             status = await self.pool.execute(query, *values.values())
         except _DRIVER_ERRORS:
-            log.exception("psql.upsert(%s)", table)
+            log.debug("psql.upsert(%s)", table, exc_info=True)
             raise
         return _status_count(status)