release: 1.0.0

first stable release. pre-1.0.0 verification complete: all surviving MED regressions and
gaps resolved and independently re-fired, tree audited clean across the suite.

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

README.md

@@ -10,18 +10,18 @@ a sibling of the `mongo` lib. Class is **`PsqlDB`**.
 `requirements.txt`:
 
 ```
-psql @ git+ssh://git@git.rethinkstudios.io/rethink-public/psql.git@v0.1.2
+psql @ git+ssh://git@git.rethinkstudios.io/rethink-public/psql.git@v0.1.7
 ```
 
 Direct:
 
 ```bash
-pip install "psql @ git+ssh://git@git.rethinkstudios.io/rethink-public/psql.git@v0.1.2"
+pip install "psql @ git+ssh://git@git.rethinkstudios.io/rethink-public/psql.git@v0.1.7"
 ```
 
 Pulls `asyncpg`.
 
-Drop the `@v0.1.2` suffix from the line above to install the latest unpinned.
+Drop the `@v0.1.7` suffix from the line above to install the latest unpinned.
 
 ## The two-layer API
 
@@ -63,6 +63,12 @@ async with PsqlDB(database="app", user="postgres") as db:
     await db.insert("events", {"kind": "login"})
 ```
 
+`host`/`port` default to `None`, not `"localhost"`/`5432` — asyncpg only reads a `dsn`'s
+embedded host/port when the `host`/`port` kwargs are falsy, so passing `dsn=...` in
+`pool_kwargs` (with no `host`/`port` of your own) lets the dsn's server reach asyncpg
+instead of being silently overridden. The no-dsn path above still defaults to
+`localhost:5432` when you don't pass `host`.
+
 ### Layer 2 — raw SQL for the complex queries
 
 ```python

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "psql"
-version = "0.1.2"
+version = "1.0.0"
 description = "async postgres wrapper over asyncpg: two-layer API (friendly verbs + raw escape hatch), fail-loud, config-free"
 requires-python = ">=3.10"
 dependencies = [

src/psql/__init__.py

@@ -1,3 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
 from .psql import PsqlDB
 
 __all__ = ["PsqlDB"]
+
+try:
+    __version__ = version("psql")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

src/psql/psql.py

@@ -1,5 +1,5 @@
 """
-async postgres wrapper over asyncpg — two-layer API (friendly verbs + raw escape hatch)
+async postgres wrapper over asyncpg - two-layer API (friendly verbs + raw escape hatch)
 
 object pattern (one pool per process), attach to the app:
     from psql import PsqlDB
@@ -13,39 +13,33 @@ context manager:
     async with PsqlDB(database="app", user="postgres") as db:
         await db.execute("CREATE TABLE ...")
 
-lifecycle:
+dsn:
-    construction is sync and opens no socket. connect() builds the asyncpg pool and
+    host/port default to None, not "localhost"/5432 - asyncpg only reads a dsn's embedded
-    validates it with `SELECT 1` so a bad host/credentials fails loud immediately rather
+    host/port when the host/port kwargs are falsy, so a hardcoded default would silently
-    than on the first real op, and returns self. close() closes the pool.
+    shadow the dsn's server. pass dsn=... in pool_kwargs alone (no host/port) to let the
+    dsn's own host/port reach asyncpg; the no-dsn path still defaults to localhost:5432.
 
 two-layer API:
-    LAYER 1 — friendly, portable verbs for simple single-table CRUD. these hide the
+    LAYER 1 - friendly, portable verbs for simple single-table CRUD, byte-for-byte
-    dialect and are byte-for-byte identical to the `mysql` lib, so a dev swaps psql<->mysql
+    identical to the `mysql` lib (zero call-site changes swapping psql<->mysql):
-    with zero call-site changes: create_database, create_table, drop, insert, get,
+    create_database, create_table, drop, insert, get, get_one, delete, exists, upsert.
-    get_one, delete, exists, upsert.
+    LAYER 2 - raw escape hatch for the complex ~20% (joins, aggregates, CTEs, window
-    LAYER 2 — raw escape hatch for the complex ~20% (joins, aggregates, CTEs, window
+    functions): execute, fetch, fetchone, fetchval, transaction, using `$1, $2`
-    functions): execute, fetch, fetchone, fetchval, transaction. you write the SQL with
+    placeholders (asyncpg style). deliberately nothing in between - no query builder/ORM.
-    `$1, $2` placeholders (asyncpg style) + params; the wrapper still gives pooling,
-    parameterization, fail-loud errors, and row->dict conversion. raw SQL is psql-specific.
-    there is deliberately NOTHING in between — no query builder / ORM. a join goes through
-    raw fetch(), never a chainable .where()/.join().
-
-rows:
-    layer 1 and fetch/fetchone return plain dicts ({column: value}), not asyncpg Record
-    objects — identical shape to the mysql lib.
 
 placeholders / injection safety:
-    values are ALWAYS parameterized — layer 1 builds `$1, $2` internally; layer 2 takes
+    values are ALWAYS parameterized - layer 1 builds `$1, $2` internally; layer 2 takes
     your `$1` placeholders + *params. never f-string/format a value into SQL. only
     identifiers (table/column names) are interpolated, and they are quoted.
 
-errors (FAIL LOUD — unlike the mongo lib's swallow-and-default):
+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
-    only ever a real result (no row, empty table) — never a swallowed failure. for anything
+    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).
 """
 
+import asyncio
 import logging
 from typing import Any, Dict, List, Optional, Sequence
 
@@ -59,7 +53,7 @@ _DRIVER_ERRORS = (asyncpg.PostgresError, asyncpg.InterfaceError, OSError)
 def _quote_ident(identifier: str) -> str:
     """quote a sql identifier (table/column), escaping embedded double-quotes
 
-    identifiers can't be parameterized, so they are interpolated — quoting + doubling any
+    identifiers can't be parameterized, so they are interpolated - quoting + doubling any
     embedded quote is the postgres-safe way to do that for caller-supplied names.
     """
     return '"' + identifier.replace('"', '""') + '"'
@@ -75,8 +69,8 @@ class PsqlDB:
 
     def __init__(
         self,
-        host: str = "localhost",
+        host: Optional[str] = None,
-        port: int = 5432,
+        port: Optional[int] = None,
         database: Optional[str] = None,
         user: Optional[str] = None,
         password: Optional[str] = None,
@@ -91,7 +85,18 @@ class PsqlDB:
         host/port/database/user/password/min_size/max_size/command_timeout are injected by
         the caller. extra pool_kwargs pass through to asyncpg.create_pool (ssl, server_
         settings, dsn, etc). `host` may be a unix socket directory as well as a hostname.
+
+        host/port default to None here (not "localhost"/5432): asyncpg only reads a dsn's
+        embedded host/port when the host/port kwargs are falsy, so a hardcoded default
+        would silently shadow the dsn's server. no dsn -> host/port fall back to
+        localhost:5432; dsn passed -> host/port stay None (letting the dsn's own reach
+        asyncpg) unless the caller explicitly overrides them.
         """
+        if "dsn" not in pool_kwargs:
+            if host is None:
+                host = "localhost"
+            if port is None:
+                port = 5432
         self._config = dict(
             host=host,
             port=port,
@@ -104,6 +109,7 @@ class PsqlDB:
             **pool_kwargs,
         )
         self._pool: Optional[asyncpg.Pool] = None
+        self._connect_lock = asyncio.Lock()
 
     async def connect(self) -> "PsqlDB":
         """build the pool and validate it with SELECT 1; fail loud on bad config
@@ -111,25 +117,42 @@ class PsqlDB:
         returns self so callers can write `db = await PsqlDB(...).connect()`. if called
         again on an already-connected instance the previous pool is closed first (no
         orphaned pool); if the SELECT-1 validation fails the freshly-built pool is torn
-        down before re-raising, so a failed connect() never leaks a live pool.
+        down before re-raising, so a failed connect() never leaks a live pool. guarded by
+        an internal lock so concurrent connect() calls build exactly one pool instead of
+        each racing to create + orphan their own.
         """
+        async with self._connect_lock:
             if self._pool is not None:
-            await self.close()
+                await self._close_locked()
-        pool = await asyncpg.create_pool(**self._config)
+            pool = None
             try:
+                pool = await asyncpg.create_pool(**self._config)
                 await pool.fetchval("SELECT 1")
             except _DRIVER_ERRORS:
-            log.exception("psql.connect() validation failed")
+                log.exception("psql.connect() failed")
+                if pool is not None:
                     await pool.close()
                 raise
             except BaseException:
+                if pool is not None:
                     await pool.close()
                 raise
             self._pool = pool
             return self
 
     async def close(self) -> None:
-        """close the pool on shutdown"""
+        """close the pool on shutdown and null the reference (so pool/connected checks
+        report not-connected against a dead pool)
+
+        guarded by the same lock as connect() - a close() racing an in-flight connect()
+        waits for it rather than no-opping against a not-yet-installed pool and leaving
+        the just-built one live.
+        """
+        async with self._connect_lock:
+            await self._close_locked()
+
+    async def _close_locked(self) -> None:
+        """close the pool and null the reference; caller must hold `_connect_lock`"""
         if self._pool is None:
             return
         try:
@@ -137,31 +160,33 @@ class PsqlDB:
         except _DRIVER_ERRORS:
             log.exception("psql.close()")
             raise
+        finally:
+            self._pool = None
 
     async def __aenter__(self) -> "PsqlDB":
+        """enter: connect() and return self"""
         return await self.connect()
 
     async def __aexit__(self, exc_type, exc, tb) -> None:
+        """exit: close(), ignoring exc_type/exc/tb"""
         await self.close()
 
     @property
     def pool(self) -> asyncpg.Pool:
-        """raw asyncpg.Pool escape hatch; full driver surface, raises
+        """raw asyncpg.Pool escape hatch for copy/prepare/listen-notify/cursors and
-
+        anything not wrapped; full driver surface, raises"""
-        use for copy/prepare/listen-notify/cursors and anything not wrapped.
-        """
         if self._pool is None:
             raise RuntimeError("psql: not connected; call await db.connect() first")
         return self._pool
 
     # -------------------------------------------------------------------------
-    #   layer 2 — raw escape hatch (you write the SQL, $1 placeholders)
+    #   layer 2 - raw escape hatch (you write the SQL, $1 placeholders)
 
     async def execute(self, query: str, *params: Any) -> str:
         """run a statement (INSERT/UPDATE/DELETE/DDL); return asyncpg's status string
 
-        the status string is e.g. "INSERT 0 1" / "UPDATE 3" / "DELETE 2" — parse it or use
+        e.g. "INSERT 0 1" / "UPDATE 3" / "DELETE 2" - parse it, or use the layer-1 verbs
-        the layer-1 verbs (insert/delete) which return structured values instead.
+        (insert/delete) which return structured values instead.
         """
         try:
             return await self.pool.execute(query, *params)
@@ -181,8 +206,7 @@ class PsqlDB:
     async def fetchone(self, query: str, *params: Any) -> Optional[dict]:
         """run a query and return the first row as a dict, or None if no rows
 
-        named fetchone (not asyncpg's fetchrow) to match the mysql lib's layer-2 surface;
+        named fetchone (not asyncpg's fetchrow) to match the mysql lib's layer-2 surface.
-        maps to the driver's fetchrow internally.
         """
         try:
             row = await self.pool.fetchrow(query, *params)
@@ -207,15 +231,15 @@ class PsqlDB:
                 await conn.execute("INSERT ...", a)
                 await conn.execute("UPDATE ...", b)
         commits on clean exit, rolls back and re-raises on any error. `conn` is a raw
-        asyncpg connection (use its $1-placeholder execute/fetch/... directly).
+        asyncpg connection ($1-placeholder execute/fetch/... directly).
         """
         return _Transaction(self.pool)
 
     # -------------------------------------------------------------------------
-    #   layer 1 — friendly portable verbs (identical across psql/mysql)
+    #   layer 1 - friendly portable verbs (identical across psql/mysql)
 
     async def create_database(self, name: str) -> None:
-        """CREATE DATABASE name (raises if it already exists — postgres has no IF NOT
+        """CREATE DATABASE name (raises if it already exists - postgres has no IF NOT
         EXISTS for CREATE DATABASE; catch the duplicate error or check first)"""
         try:
             await self.pool.execute(f"CREATE DATABASE {_quote_ident(name)}")
@@ -251,7 +275,7 @@ class PsqlDB:
         """INSERT one row from {column: value}; return the inserted rowcount (1)
 
         values are parameterized ($1, $2, ...). returns the number of rows inserted (1 on
-        success) — the portable return shape shared with the mysql lib.
+        success) - the portable return shape shared with the mysql lib.
         """
         cols = list(values.keys())
         placeholders = ", ".join(f"${i + 1}" for i in range(len(cols)))
@@ -267,7 +291,7 @@ class PsqlDB:
     async def get(self, table: str, conditions: Optional[Dict[str, Any]] = None) -> List[dict]:
         """SELECT * rows matching equality `conditions` (col = val AND ...) as dicts
 
-        conditions=None/{} returns all rows. simple equality only — anything more complex
+        conditions=None/{} returns all rows. simple equality only - anything more complex
         goes through raw fetch().
         """
         where, params = _where(conditions)
@@ -315,7 +339,7 @@ class PsqlDB:
             raise
 
     async def upsert(self, table: str, values: Dict[str, Any], conflict: Sequence[str]) -> int:
-        """INSERT ... ON CONFLICT (conflict_cols) DO UPDATE — insert or update on key clash
+        """INSERT ... ON CONFLICT (conflict_cols) DO UPDATE - insert or update on key clash
 
         `conflict` is the list of columns forming the unique/pk constraint to upsert on.
         the wrapper emits ON CONFLICT here (the mysql lib emits ON DUPLICATE KEY UPDATE for
@@ -353,7 +377,7 @@ class _Transaction:
             await self._tx.start()
         except BaseException:
             # start() (or transaction()) failing after acquire would otherwise leak the
-            # pooled connection — __aexit__ is not called when __aenter__ raises. release
+            # pooled connection - __aexit__ is not called when __aenter__ raises. release
             # it and reset so a failed transaction start never burns a pool slot.
             await self._pool.release(self._conn)
             self._conn = None
@@ -373,13 +397,21 @@ class _Transaction:
 def _where(conditions: Optional[Dict[str, Any]]) -> tuple:
     """build a parameterized `WHERE col = $1 AND ...` clause + the params list
 
-    returns ("", []) when there are no conditions. equality only.
+    returns ("", []) when there are no conditions. equality only. a None value renders as
+    `col IS NULL` (not `col = $n` bound to NULL, which sql never matches) and does not
+    consume a placeholder.
     """
     if not conditions:
         return "", []
-    cols = list(conditions.keys())
+    parts = []
-    clause = " AND ".join(f"{_quote_ident(c)} = ${i + 1}" for i, c in enumerate(cols))
+    params = []
-    return f" WHERE {clause}", list(conditions.values())
+    for col, val in conditions.items():
+        if val is None:
+            parts.append(f"{_quote_ident(col)} IS NULL")
+        else:
+            params.append(val)
+            parts.append(f"{_quote_ident(col)} = ${len(params)}")
+    return f" WHERE {' AND '.join(parts)}", params
 
 
 def _status_count(status: str) -> int: