code-coordinator 0.5.272__tar.gz → 0.5.273__tar.gz

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/.github/workflows/test.yml

@@ -320,3 +320,61 @@ jobs:
   # the half of that check this repo can still make (the generator runs and
   # covers every schema; the coord-web byte-comparison itself is that repo's
   # own CI, per the paragraph above).
+
+  # #2886: a real Postgres 16 service, so `coord/sql.py`'s Postgres branches
+  # (paramstyle translation, upsert idioms, `information_schema`
+  # introspection, `RETURNING`, `dict_row`) — spoken since #2719 but never
+  # once executed against a real server — actually run against one, and so
+  # `COORD_TEST_BACKEND=postgres` (#2884's test-suite backend switch) means
+  # something in CI for the first time.
+  #
+  # SEPARATE JOB, not a `services:` block bolted onto `test` above, for two
+  # reasons: (1) the SQLite lane must stay exactly as fast and exactly as
+  # reliable as it is today — a Postgres service, even an unused one, is
+  # more CI surface for that job to depend on for zero benefit to the
+  # SQLite path; (2) `continue-on-error: true` below softens THIS job's
+  # conclusion without touching `test`'s at all. Running the whole suite
+  # (`coord_db` is autouse — see tests/conftest.py — so every one of ~400
+  # test files follows `COORD_TEST_BACKEND` for free) against a backend
+  # nothing has ever run it against is expected to be red for real,
+  # unrelated-to-this-PR reasons at first (coord/db.py's `_ensure_schema`
+  # and friends were written and only ever exercised against SQLite) — the
+  # harness-portability issue's deliverable is exactly that failure list.
+  # `continue-on-error: true` keeps this job's signal visible (its own
+  # conclusion is still pass/fail on the Checks tab) without blocking merges
+  # on it. Flip it off once that failure list is closed out.
+  #
+  # `psycopg` is an optional extra (`postgres`, this issue) — never a base
+  # or `[dev]` dependency (see `pyproject.toml`) — so installing it is this
+  # job's own opt-in `pip install -e ".[dev,postgres]"`, not a change to
+  # what every other job's `pip install -e ".[dev]"` pulls in.
+  postgres:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready --health-interval 10s
+          --health-timeout 5s --health-retries 5
+        ports:
+          - 5432:5432
+    env:
+      COORD_TEST_BACKEND: postgres
+      # The default image's bootstrap database is named after POSTGRES_USER
+      # (postgres) since no POSTGRES_DB was set above — matches
+      # tests/backends.py's schema-per-test isolation, which needs CREATE on
+      # an existing database, not a database of its own.
+      COORD_TEST_POSTGRES_DSN: postgresql://postgres:postgres@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,postgres]"
+      # #2180: same split as the `test` job above — the sealed acceptance
+      # suite is gated separately through the #2164 CI wrapper, not swept
+      # into this job's ordinary pytest run.
+      - run: pytest --ignore=tests/acceptance

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.272
+Version: 0.5.273
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -26,6 +26,8 @@ Requires-Dist: starlette>=0.37; extra == "server"
 Requires-Dist: uvicorn>=0.30; extra == "server"
 Requires-Dist: websockets>=12.0; extra == "server"
 Requires-Dist: psutil>=5.9; extra == "server"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Provides-Extra: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Provides-Extra: dev

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.272
+Version: 0.5.273
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT
@@ -26,6 +26,8 @@ Requires-Dist: starlette>=0.37; extra == "server"
 Requires-Dist: uvicorn>=0.30; extra == "server"
 Requires-Dist: websockets>=12.0; extra == "server"
 Requires-Dist: psutil>=5.9; extra == "server"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Provides-Extra: all
 Requires-Dist: code-coordinator[server]; extra == "all"
 Provides-Extra: dev

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/code_coordinator.egg-info/requires.txt

@@ -18,6 +18,9 @@ setuptools>=68
 setuptools-scm>=8
 wheel
 
+[postgres]
+psycopg[binary]>=3.1
+
 [server]
 starlette>=0.37
 uvicorn>=0.30

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.272",
+  "tag": "0.5.273",
   "distance": 0,
-  "node": "g86d2609016c406aeea4b99ed80b0eae4e2963c25",
+  "node": "gd5980777425030eea6f688b62a154d8312a34199",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-28"

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/coord/sql.py

@@ -71,6 +71,43 @@ class UnsupportedDialectError(ValueError):
     """Raised when a connection's driver module maps to no known dialect."""
 
 
+#: What to tell a caller who hit a Postgres codepath without the extra
+#: installed -- mirrors ``coord.commands._common.SERVER_EXTRA_INSTALL_HINT``'s
+#: shape for the ``[server]`` extra.
+POSTGRES_EXTRA_INSTALL_HINT = "pip install 'code-coordinator[postgres]'"
+
+
+def _import_psycopg() -> Any:
+    """Import ``psycopg``, translating its absence into an actionable message
+    (#2886).
+
+    ``psycopg`` is an optional dependency -- the ``postgres`` extra -- never a
+    base or ``[dev]`` one (see ``pyproject.toml``'s ``[project.optional-
+    dependencies]``): every existing SQLite deployment must keep working
+    without ever pulling it in. Hitting this on an install that never asked
+    for Postgres is therefore the expected, common case, not a bug -- so
+    every Postgres call site in this module that needs the driver
+    (:func:`connect`, :func:`row_factory_for`, :func:`driver_error`) routes
+    its import through here rather than a bare ``import psycopg``, so the
+    failure names the extra to install instead of surfacing a raw
+    ``ModuleNotFoundError: No module named 'psycopg'`` traceback.
+
+    :func:`driver_errors` deliberately does NOT route through here -- it
+    degrades silently to ``(sqlite3.Error,)`` when psycopg is absent (that is
+    its whole contract), so it keeps its own bare ``import psycopg`` inside a
+    caught ``try/except ImportError`` rather than raising through this
+    helper's message just to swallow it unread.
+    """
+    try:
+        import psycopg  # noqa: PLC0415 -- optional dep, see docstring
+    except ImportError as exc:  # ModuleNotFoundError is a subclass
+        raise ModuleNotFoundError(
+            "the Postgres backend needs the `psycopg` driver, which is not "
+            f"installed. Install it with: {POSTGRES_EXTRA_INSTALL_HINT}"
+        ) from exc
+    return psycopg
+
+
 def detect_dialect(conn: Any) -> str:
     """Identify *conn*'s SQL dialect from its concrete connection type.
 
@@ -136,7 +173,7 @@ def connect(
     superseded #2766 decision note.
 
     **Postgres** (``dsn`` required): ``psycopg.connect(dsn)``. ``psycopg`` is
-    an optional dependency (see :func:`row_factory_for`) imported
+    an optional dependency (see :func:`_import_psycopg`) imported
     function-locally, so calling this with ``backend=DIALECT_POSTGRES`` before
     psycopg is installed raises ``ImportError``/``ModuleNotFoundError`` rather
     than breaking import of this module for everyone else. *read_only* has no
@@ -157,7 +194,7 @@ def connect(
     if backend == DIALECT_POSTGRES:
         if not dsn:
             raise ValueError("sql.connect(backend='postgres') requires dsn")
-        import psycopg  # noqa: PLC0415 -- optional dep, see row_factory_for
+        psycopg = _import_psycopg()
 
         return psycopg.connect(dsn)
     raise UnsupportedDialectError(backend)
@@ -348,19 +385,20 @@ def row_factory_for(dialect: str) -> Any:
 
     ``sqlite3.Row`` is returned directly (it's a base-dependency import,
     already used throughout this tree).  ``psycopg.rows.dict_row`` is
-    imported function-locally -- ``psycopg`` is not a base or even a
-    ``server``-extra dependency yet (see ``pyproject.toml``'s ``[project]
-    dependencies`` comment on why third-party imports the base client
-    doesn't need stay function-local) -- so calling this with
-    :data:`DIALECT_POSTGRES` before a Postgres backend is actually installed
-    raises ``ImportError``/``ModuleNotFoundError`` rather than breaking
-    import of this module for everyone else.
+    imported function-locally -- ``psycopg`` is an optional dependency (the
+    ``postgres`` extra, #2886), never a base or ``[dev]`` one (see
+    ``pyproject.toml``'s ``[project.optional-dependencies]``) -- so calling
+    this with :data:`DIALECT_POSTGRES` before the extra is installed raises
+    ``ImportError``/``ModuleNotFoundError``, naming the extra to install
+    (see :func:`_import_psycopg`), rather than breaking import of this
+    module for everyone else.
     """
     if dialect == DIALECT_SQLITE:
         import sqlite3
 
         return sqlite3.Row
     if dialect == DIALECT_POSTGRES:
+        _import_psycopg()  # translate a missing psycopg into an actionable message
         from psycopg.rows import dict_row  # noqa: PLC0415 -- optional dep, see docstring
 
         return dict_row
@@ -615,7 +653,7 @@ def driver_error(conn: Any) -> type[BaseException]:
 
         return sqlite3.Error
     if dialect == DIALECT_POSTGRES:
-        import psycopg  # noqa: PLC0415 -- optional dep, see row_factory_for
+        psycopg = _import_psycopg()
 
         return psycopg.Error
     raise UnsupportedDialectError(dialect)
@@ -637,13 +675,15 @@ def driver_errors() -> tuple[type[BaseException], ...]:
     instead of a retried write.
 
     ``sqlite3`` is a stdlib module -- always present, always included.
-    ``psycopg`` is not a declared dependency (see :func:`row_factory_for`),
-    so its absence is the normal case today, not an error: this degrades to
-    ``(sqlite3.Error,)`` rather than raising ``ImportError``, the same
-    "absence is normal" posture :func:`row_factory_for` takes for a
-    *known* dialect with no live connection to detect it from -- except
-    here there is no dialect to detect at all, so degrading silently (not
-    even function-local, deferred-import-style) is correct: a caller doing
+    ``psycopg`` is an optional dependency, not a base or ``[dev]`` one (see
+    :func:`_import_psycopg`), so its absence is the normal case today, not an
+    error: this degrades to ``(sqlite3.Error,)`` rather than raising
+    ``ImportError`` -- unlike every other Postgres call site in this module,
+    this one does NOT route through :func:`_import_psycopg` and its
+    actionable message, precisely because the message would just be
+    swallowed unread by the ``except ImportError`` below; there is no dialect
+    to detect at all here, so degrading silently (not even
+    function-local, deferred-import-style) is correct: a caller doing
     ``except sql.driver_errors():`` on a SQLite-only install must keep
     behaving exactly as ``except sqlite3.OperationalError:`` always did.
 
@@ -656,7 +696,7 @@ def driver_errors() -> tuple[type[BaseException], ...]:
 
     errors: list[type[BaseException]] = [sqlite3.Error]
     try:
-        import psycopg  # noqa: PLC0415 -- optional dep, see row_factory_for
+        import psycopg  # noqa: PLC0415 -- optional dep, absence degrades silently, see docstring
     except ImportError:
         pass
     else:

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/pyproject.toml

@@ -96,6 +96,17 @@ server = [
     # Agent-side process/host metrics behind GET /metrics (coord/agent_app.py).
     "psutil>=5.9",
 ]
+# #2886: the Postgres driver for `coord/sql.py`'s dialect seam (#2719+).
+# Optional and NEVER folded into `server`/`all`/`dev` below — every existing
+# deployment runs SQLite and must keep working without ever pulling this in;
+# adding it to a shared extra would make it a fleet-wide install change for
+# zero benefit to anyone still on SQLite. `pip install 'code-coordinator[postgres]'`
+# is the only way to get it. `coord/sql.py`'s Postgres call sites
+# (`connect`/`row_factory_for`/`driver_error`) guard the import through
+# `_import_psycopg()`, which names this extra in its error message rather
+# than surfacing a bare `ModuleNotFoundError`; `tests/backends.py` does the
+# same for the test suite's own `COORD_TEST_BACKEND=postgres` opt-in.
+postgres = ["psycopg[binary]>=3.1"]
 # Convenience alias: "give me everything a full node runs".
 all = ["code-coordinator[server]"]
 dev = [

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/tests/backends.py

@@ -151,22 +151,20 @@ def _next_schema_name() -> str:
 def _import_psycopg() -> Any:
     """Import ``psycopg`` with an actionable message when it isn't installed.
 
-    ``psycopg`` is deliberately **not** a declared dependency of this project
-    yet — adding it (and a Postgres service to CI) is #2886, filed alongside
-    #2884 precisely so this harness could land first without touching the
-    dependency set.  Selecting the Postgres backend without it is therefore a
-    normal, expected state that deserves a real explanation rather than a
-    bare ``ModuleNotFoundError`` traceback out of a fixture.
+    ``psycopg`` is an optional dependency — the ``postgres`` extra (#2886) —
+    never a base or ``[dev]`` one, so a plain ``pip install -e ".[dev]"``
+    does not pull it in.  Selecting the Postgres backend without it is
+    therefore a normal, expected state that deserves a real explanation
+    rather than a bare ``ModuleNotFoundError`` traceback out of a fixture.
     """
     try:
         import psycopg  # noqa: PLC0415 -- optional dep, see docstring
     except ImportError as exc:  # ModuleNotFoundError is a subclass
         raise ModuleNotFoundError(
             f"{BACKEND_ENV_VAR}={BACKEND_POSTGRES} was requested but the "
-            "`psycopg` driver is not installed. It is not a declared "
-            "dependency of this project yet (#2886 adds it, along with a "
-            "Postgres service in CI). Install it into your venv with "
-            "`pip install 'psycopg[binary]'` and point "
+            "`psycopg` driver is not installed. It is an optional "
+            "dependency (the `postgres` extra, #2886) — install it with "
+            "`pip install 'code-coordinator[postgres]'` and point "
             f"{DSN_ENV_VAR} at a reachable server "
             f"(default: {DEFAULT_POSTGRES_DSN})."
         ) from exc

{code_coordinator-0.5.272 → code_coordinator-0.5.273}/tests/test_sql_dialect.py

@@ -4,25 +4,39 @@ This module is a pure addition: nothing in the tree calls ``coord.sql`` yet
 (that's Phase C slices 2-7 of #1948), so these tests exercise it directly
 rather than through any existing call site.
 
-Real ``psycopg``/``psycopg2`` are not installed (this repo has no Postgres
-dependency yet — see ``pyproject.toml``), so the Postgres path is exercised
-two ways: (1) dialect detection and SQL/param translation, which need only a
-*fake* connection class whose ``__module__`` claims to be ``psycopg``, spied
-to capture exactly what would have reached a real driver; and (2)
-``row_factory_for``, which asserts the honest failure mode (``ImportError``)
-when the optional dependency genuinely isn't there.
+``psycopg`` is an optional dependency (the ``postgres`` extra, #2886) — most
+runs of this suite still don't have it installed, so the Postgres path is
+exercised two ways: (1) dialect detection and SQL/param translation, which
+need only a *fake* connection class whose ``__module__`` claims to be
+``psycopg``, spied to capture exactly what would have reached a real driver
+(this needs no driver and no server — it is the bulk of this file, and it
+still runs on every machine, every time); and (2), in the
+"round trip against a real server" section near the bottom, actual
+``psycopg`` + an actual Postgres 16 connection — the CI ``postgres`` job in
+``.github/workflows/test.yml`` provides both. Those tests skip cleanly (not
+error) when ``psycopg`` isn't installed or no server is reachable, via the
+``pg_conn``/``real_postgres`` fixtures below, so a developer with neither
+sees skips, not failures — proving #2886's whole point: every Postgres
+branch coord.sql has ever emitted a fake-connection assertion for now also
+has at least one assertion that it is *accepted* by a real server, not just
+*shaped like* what one would accept.
 """
 
 from __future__ import annotations
 
 import ast
+import os
 import re
 import sqlite3
+import sys
+import uuid
 from pathlib import Path
+from typing import Any, Iterator
 
 import pytest
 
 from coord import sql
+from tests.backends import DSN_ENV_VAR, postgres_dsn
 
 
 # ── fake Postgres-shaped connection (no real psycopg needed) ────────────────
@@ -171,10 +185,19 @@ def test_connect_postgres_requires_dsn():
         sql.connect(backend=sql.DIALECT_POSTGRES)
 
 
-def test_connect_postgres_without_psycopg_raises_import_error():
-    """psycopg is not installed in this repo (see the module docstring) --
-    the honest failure mode for `backend="postgres"` with no driver present,
-    matching `row_factory_for`/`driver_error`'s posture for the same gap."""
+def test_connect_postgres_without_psycopg_raises_import_error(monkeypatch):
+    """``psycopg`` is an optional dependency (the ``postgres`` extra,
+    #2886) -- the honest failure mode for `backend="postgres"` with no
+    driver present, matching `row_factory_for`/`driver_error`'s posture for
+    the same gap.
+
+    ``sys.modules["psycopg"] = None`` forces ``import psycopg`` to raise
+    ``ImportError`` deterministically -- same technique
+    ``tests/test_backend_selection.py`` uses -- so this passes identically
+    whether or not the CI job running it happens to have the `[postgres]`
+    extra installed (the ``postgres`` job in .github/workflows/test.yml
+    does, everything else doesn't)."""
+    monkeypatch.setitem(sys.modules, "psycopg", None)
     with pytest.raises(ImportError):
         sql.connect(backend=sql.DIALECT_POSTGRES, dsn="postgresql://user@host/db")
 
@@ -483,7 +506,10 @@ def test_row_factory_for_sqlite_is_sqlite_row():
     assert sql.row_factory_for(sql.DIALECT_SQLITE) is sqlite3.Row
 
 
-def test_row_factory_for_postgres_without_psycopg_raises_import_error():
+def test_row_factory_for_postgres_without_psycopg_raises_import_error(monkeypatch):
+    """See ``test_connect_postgres_without_psycopg_raises_import_error`` for
+    why this forces the absence rather than assuming it (#2886)."""
+    monkeypatch.setitem(sys.modules, "psycopg", None)
     with pytest.raises(ImportError):
         sql.row_factory_for(sql.DIALECT_POSTGRES)
 
@@ -641,7 +667,10 @@ def test_driver_error_catches_a_real_sqlite_operational_error(memdb):
         memdb.execute("SELECT * FROM no_such_table")
 
 
-def test_driver_error_postgres_without_psycopg_raises_import_error():
+def test_driver_error_postgres_without_psycopg_raises_import_error(monkeypatch):
+    """See ``test_connect_postgres_without_psycopg_raises_import_error`` for
+    why this forces the absence rather than assuming it (#2886)."""
+    monkeypatch.setitem(sys.modules, "psycopg", None)
     conn = _FakePostgresConnection()
     with pytest.raises(ImportError):
         sql.driver_error(conn)
@@ -657,12 +686,16 @@ def test_driver_error_unknown_dialect_raises():
 # Unlike driver_error(conn), this needs no connection -- it's for the ~18
 # call sites wrapping a retry_on_locked(...) call (or another write with no
 # connection in scope) that used to hardcode `except sqlite3.OperationalError:`,
-# going silently inert under Postgres. psycopg is not installed in this repo
-# (see the module docstring), so degrading to (sqlite3.Error,) rather than
-# raising ImportError is the case actually under test here.
+# going silently inert under Postgres. psycopg is an optional dependency
+# (#2886) that most runs of this suite don't have installed, so degrading to
+# (sqlite3.Error,) rather than raising ImportError is the case actually
+# under test here -- forced deterministically below rather than assumed, so
+# this test still passes in the one CI job that DOES have the `[postgres]`
+# extra installed (`postgres` in .github/workflows/test.yml).
 
 
-def test_driver_errors_degrades_to_sqlite_only_when_psycopg_absent():
+def test_driver_errors_degrades_to_sqlite_only_when_psycopg_absent(monkeypatch):
+    monkeypatch.setitem(sys.modules, "psycopg", None)
     assert sql.driver_errors() == (sqlite3.Error,)
 
 
@@ -750,6 +783,187 @@ def test_is_lock_contention_error_false_for_unrelated_exception_with_no_sqlstate
     assert is_lock_contention_error(ValueError("not a DB error at all")) is False
 
 
+# ── round trip against a real server (#2886) ────────────────────────────────
+#
+# Everything above proves what SQL text/params coord.sql *would* send to a
+# real driver, using a fake connection whose __module__ merely claims to be
+# "psycopg" (see the module docstring). None of it proves Postgres *accepts*
+# that text -- coord/sql.py has spoken Postgres since #2719 and none of its
+# Postgres branches had ever executed against a real server before this
+# section existed. These tests fill that gap for the branches #2886 calls
+# out by name: execute/executemany translation, upsert, insert_ignore,
+# insert_returning_id's RETURNING path, table_columns against
+# information_schema, apply_row_factory's dict_row, and
+# autoincrement_pk_ddl's identity-column DDL actually creating a table.
+#
+# `psycopg` is an optional dependency (the `postgres` extra) and most runs of
+# this suite have neither it nor a reachable server -- both the driver import
+# and the connection attempt below skip cleanly (pytest.importorskip /
+# pytest.skip) rather than raising, so `pytest tests/test_sql_dialect.py`
+# with no Postgres anywhere behaves exactly as it did before this section
+# existed: skips, not errors, and NOT gated on `COORD_TEST_BACKEND` (these
+# tests must skip cleanly under the suite's default, unset backend too, not
+# just under an explicit non-`postgres` selection). CI's `postgres` job in
+# .github/workflows/test.yml provides both, and reuses tests/backends.py's
+# `COORD_TEST_POSTGRES_DSN` (#2884) so a developer or CI run only ever needs
+# to set the one env var to make both that harness and these targeted tests
+# exercise the same server.
+
+
+def _require_psycopg() -> Any:
+    return pytest.importorskip(
+        "psycopg",
+        reason="psycopg not installed -- pip install 'code-coordinator[postgres]'",
+    )
+
+
+@pytest.fixture
+def pg_conn() -> Iterator[Any]:
+    """A real ``psycopg`` connection, opened through :func:`sql.connect` (the
+    #827 connection factory, so that factory itself is exercised for real
+    too) -- in its own private schema, dropped on teardown.
+
+    Schema-per-test, the same isolation strategy ``tests/backends.py`` uses
+    for the whole suite's own Postgres opt-in (#2884) -- a small,
+    self-contained copy rather than reaching into that module's private
+    ``_open_postgres`` helper, because this fixture has a different
+    contract: it must skip cleanly under the suite's *default*
+    ``COORD_TEST_BACKEND`` (unset, i.e. SQLite), not just under an explicit
+    ``postgres`` selection -- see the section header above.
+
+    Row factory is left at psycopg's default (tuple rows) -- matching
+    ``sqlite3``'s own default, which the ``memdb`` fixture above relies on
+    -- so a test that cares about ``dict_row`` calls
+    :func:`sql.apply_row_factory` itself, the same way
+    ``test_apply_row_factory_makes_rows_dict_accessible`` does for SQLite.
+    """
+    _require_psycopg()
+    dsn = postgres_dsn()
+    try:
+        conn = sql.connect(backend=sql.DIALECT_POSTGRES, dsn=dsn)
+    except Exception as exc:  # noqa: BLE001 -- any connect failure is a skip, not a failure
+        pytest.skip(f"Postgres not reachable at {dsn!r} ({DSN_ENV_VAR}): {exc}")
+    schema = f"coord_sql_dialect_test_{os.getpid()}_{uuid.uuid4().hex[:8]}"
+    with conn.cursor() as cur:
+        cur.execute(f'CREATE SCHEMA "{schema}"')
+        # search_path is a session setting, so every later statement on this
+        # connection resolves unqualified table names into the private
+        # schema without any test needing to know it exists.
+        cur.execute(f'SET search_path TO "{schema}"')
+    conn.commit()
+    try:
+        yield conn
+    finally:
+        conn.rollback()
+        with conn.cursor() as cur:
+            cur.execute("SET search_path TO public")
+            cur.execute(f'DROP SCHEMA IF EXISTS "{schema}" CASCADE')
+        conn.commit()
+        conn.close()
+
+
+def test_detect_dialect_real_postgres_connection(pg_conn):
+    assert sql.detect_dialect(pg_conn) == sql.DIALECT_POSTGRES
+
+
+def test_connect_postgres_round_trip_opens_a_working_connection(pg_conn):
+    """:func:`sql.connect` itself (#827), not just its ``ImportError`` guard
+    (already covered above) -- ``pg_conn`` opened through it; this proves
+    the result is a live, usable connection."""
+    cur = sql.execute(pg_conn, "SELECT 1")
+    assert cur.fetchone() == (1,)
+
+
+def test_execute_and_executemany_round_trip_against_real_postgres(pg_conn):
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT, b TEXT)")
+    sql.execute(pg_conn, "INSERT INTO t (id, a, b) VALUES (?, ?, ?)", (1, "x", "y"))
+    sql.executemany(
+        pg_conn,
+        "INSERT INTO t (id, a, b) VALUES (?, ?, ?)",
+        [(2, "p", "q"), (3, "r", "s")],
+    )
+    pg_conn.commit()
+    cur = sql.execute(pg_conn, "SELECT id, a, b FROM t ORDER BY id")
+    assert cur.fetchall() == [(1, "x", "y"), (2, "p", "q"), (3, "r", "s")]
+
+
+def test_execute_preserves_literal_question_mark_against_real_postgres(pg_conn):
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT, b TEXT)")
+    sql.execute(pg_conn, "INSERT INTO t (id, a, b) VALUES (?, ?, ?)", (1, "why?", "z"))
+    pg_conn.commit()
+    cur = sql.execute(pg_conn, "SELECT a FROM t WHERE b = ? AND a = 'why?'", ("z",))
+    assert cur.fetchone() == ("why?",)
+
+
+def test_upsert_round_trips_against_real_postgres(pg_conn):
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT, b TEXT)")
+    pg_conn.commit()
+    sql.upsert(pg_conn, "t", ["id", "a", "b"], (1, "first", "y"), conflict_columns=["id"])
+    pg_conn.commit()
+    sql.upsert(pg_conn, "t", ["id", "a", "b"], (1, "second", "z"), conflict_columns=["id"])
+    pg_conn.commit()
+    cur = sql.execute(pg_conn, "SELECT a, b FROM t WHERE id = ?", (1,))
+    assert cur.fetchone() == ("second", "z")
+    assert sql.execute(pg_conn, "SELECT COUNT(*) FROM t").fetchone() == (1,)
+
+
+def test_insert_ignore_round_trips_against_real_postgres(pg_conn):
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT)")
+    pg_conn.commit()
+    sql.insert_ignore(pg_conn, "t", ["id", "a"], (1, "first"))
+    pg_conn.commit()
+    sql.insert_ignore(pg_conn, "t", ["id", "a"], (1, "second"))
+    pg_conn.commit()
+    cur = sql.execute(pg_conn, "SELECT a FROM t WHERE id = ?", (1,))
+    assert cur.fetchone() == ("first",)
+
+
+def test_insert_returning_id_round_trips_against_real_postgres(pg_conn):
+    ddl = sql.autoincrement_pk_ddl(sql.DIALECT_POSTGRES)
+    sql.execute(pg_conn, f"CREATE TABLE t (id {ddl}, a TEXT)")
+    pg_conn.commit()
+    new_id = sql.insert_returning_id(pg_conn, "INSERT INTO t (a) VALUES (?)", ("x",))
+    pg_conn.commit()
+    assert isinstance(new_id, int)
+    cur = sql.execute(pg_conn, "SELECT a FROM t WHERE id = ?", (new_id,))
+    assert cur.fetchone() == ("x",)
+
+
+def test_table_columns_round_trips_against_real_information_schema(pg_conn):
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT, b TEXT)")
+    pg_conn.commit()
+    columns = sql.table_columns(pg_conn, "t")
+    assert [name for name, _type in columns] == ["id", "a", "b"]
+
+
+def test_table_columns_round_trips_empty_for_missing_table_against_real_postgres(pg_conn):
+    assert sql.table_columns(pg_conn, "no_such_table") == []
+
+
+def test_apply_row_factory_dict_row_round_trips_against_real_postgres(pg_conn):
+    sql.apply_row_factory(pg_conn)
+    sql.execute(pg_conn, "CREATE TABLE t (id INTEGER PRIMARY KEY, a TEXT, b TEXT)")
+    sql.execute(pg_conn, "INSERT INTO t (id, a, b) VALUES (?, ?, ?)", (1, "x", "y"))
+    pg_conn.commit()
+    row = sql.execute(pg_conn, "SELECT a, b FROM t WHERE id = ?", (1,)).fetchone()
+    assert row["a"] == "x"
+    assert row["b"] == "y"
+
+
+def test_autoincrement_pk_ddl_round_trips_against_real_postgres(pg_conn):
+    """The identity-column DDL fragment actually creating a table and
+    actually generating monotonic ids -- this branch is pure DDL text with
+    no dedicated round trip other than using it exactly as coord/db.py
+    does: substituted into a CREATE TABLE and then inserted through."""
+    ddl = sql.autoincrement_pk_ddl(sql.DIALECT_POSTGRES)
+    sql.execute(pg_conn, f"CREATE TABLE t (id {ddl}, a TEXT)")
+    pg_conn.commit()
+    first = sql.insert_returning_id(pg_conn, "INSERT INTO t (a) VALUES (?)", ("x",))
+    second = sql.insert_returning_id(pg_conn, "INSERT INTO t (a) VALUES (?)", ("y",))
+    pg_conn.commit()
+    assert second == first + 1
+
+
 # ── the ratchet: no raw `?` reaches a driver outside the seam (#2768, #1948) ─
 #
 # #1948's first acceptance bullet: "No raw `?` placeholder reaches a driver: