pgcommon 0.1.0__tar.gz → 0.2.0__tar.gz

{pgcommon-0.1.0 → pgcommon-0.2.0}/.github/workflows/ci.yml

@@ -78,6 +78,19 @@ jobs:
           path: dist/
           if-no-files-found: error
 
+  interop:
+    name: Cross-language compatibility
+    needs: build
+    uses: BCBP-SOLUTIONS-FZC-LLC/platform-interop-tests/.github/workflows/interop.yml@main
+    with:
+      # This repo's own PR/branch ref; the other five default to their main branch (see
+      # platform-interop-tests/README.md for why).
+      platform_pgcommon_py_ref: ${{ github.head_ref || github.ref_name }}
+    secrets:
+      # Reuses the org's existing GO_PRIVATE_TOKEN (Contents:Read across the six sibling
+      # repos) rather than provisioning a separate GH_PRIVATE_TOKEN for this repo alone.
+      gh_private_token: ${{ secrets.GO_PRIVATE_TOKEN }}
+
   lint-dockerfile:
     name: Lint Dockerfile
     runs-on: ubuntu-latest

{pgcommon-0.1.0 → pgcommon-0.2.0}/ARCHITECTURE.md

@@ -277,7 +277,7 @@ sequenceDiagram
     run_in_tx ->> pool: pool._acquire() — shared acquire primitive (also used by with_conn)
 
     opt pgbouncer_mode AND guc_provider set and GUCSet non-zero
-        run_in_tx ->> run_in_tx: guc_provider() -> GUCSet; guc_set.validate() [before BEGIN]
+        run_in_tx ->> run_in_tx: guc_provider() -> GUCSet, guc_set.validate() [before BEGIN]
     end
 
     run_in_tx ->>+ DB: conn.transaction(isolation=..., readonly=...) — BEGIN
@@ -359,7 +359,7 @@ flowchart TD
     T -- "up/down/steps" --> B["_load_migrations(source)\nparse NNNN_description.{up,down}.sql\nraise NoMigrationsFoundError if none match"]
     B --> C1["connect() -> SET lock_timeout = '30s'"]
     C1 --> D1["SELECT pg_advisory_lock(key)"]
-    D1 --> E1["CREATE TABLE IF NOT EXISTS schema_migrations\n(only ever run while the lock is held —\nconcurrent CREATE TABLE IF NOT EXISTS is not race-safe in Postgres)"]
+    D1 --> E1["CREATE TABLE IF NOT EXISTS pgcommon_migrations\n(only ever run while the lock is held —\nconcurrent CREATE TABLE IF NOT EXISTS is not race-safe in Postgres)"]
     E1 --> F{"dirty flag set\nfrom a previous run?"}
     F -- yes --> G([raise MigrationDirtyError])
     F -- no --> H["apply/roll back the requested migrations,\none at a time, each in its own transaction"]
@@ -372,7 +372,7 @@ flowchart TD
 
     T -- "version" --> C2["connect() -> SET lock_timeout = '30s'\n(never calls _load_migrations — cannot raise NoMigrationsFoundError)"]
     C2 --> D2["SELECT pg_advisory_lock(key)"]
-    D2 --> E2["CREATE TABLE IF NOT EXISTS schema_migrations\n(same race-avoidance as the up/down/steps path)"]
+    D2 --> E2["CREATE TABLE IF NOT EXISTS pgcommon_migrations\n(same race-avoidance as the up/down/steps path)"]
     E2 --> M["read (version, dirty) — returned as-is,\nno dirty check, never raises MigrationDirtyError"]
     M --> K2["SELECT pg_advisory_unlock(key) [always, in a finally block]"]
     K2 --> L

pgcommon-0.2.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows [semantic versioning](VERSIONING.md).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-27
+
+### Added
+
+- `migrate.Runner` accepts an optional `table` constructor parameter (default
+  `"pgcommon_migrations"`) naming the version-tracking table, validated against
+  `^[A-Za-z_][A-Za-z0-9_]*$`. Lets a library that ships its own migrations (e.g.
+  `eventcommon`'s outbox schema) track its version state in an isolated table, independent of
+  a consuming service's own `schema_migrations`/dirty-state. New `InvalidMigrationsTableError`
+  sentinel raised for an invalid name.
+
+### Fixed — cross-language compatibility with the Go `platform-pgcommon` library
+
+- `migrate.Runner`'s default tracking table is `"pgcommon_migrations"`, not `"schema_migrations"`
+  — matching the Go library's own default, which is deliberately not `schema_migrations` so this
+  runner never collides with a consuming service's own `golang-migrate`-tracked table. Pass
+  `table="schema_migrations"` explicitly to adopt an existing `golang-migrate` deployment.
+- `config_from_env()` now warns (`key="PG_USER/PG_DBNAME"`) and leaves `Config.dsn` empty when
+  `PG_USER`/`PG_DBNAME` are missing and `DATABASE_URL` is unset, instead of silently building an
+  unusable DSN — matching Go's `internal/config.Load()`.
+- `PG_MAX_CONNS`/`PG_MIN_CONNS` now reject `0` (not just negative values), matching Go's
+  `parsePositiveInt32`.
+- The insecure-`sslmode` warning is now keyed `"DATABASE_URL"` (and sourced only from the DSN's
+  own `sslmode` query parameter) when `DATABASE_URL` is set, matching Go's mutually-exclusive
+  branching — previously it was always keyed `"PG_SSLMODE"` and could miss a warning Go would
+  have emitted, or emit one Go wouldn't.
+- `PG_BOUNCER_MODE` now matches only the exact string `"true"` (case-sensitive, no trimming),
+  matching Go's `os.Getenv("PG_BOUNCER_MODE") == "true"` — previously accepted a wider set of
+  truthy spellings (`"1"`, `"yes"`, `"on"`, ...) that Go's own config loader does not.
+- `RetryOptions.multiplier < 1` is now clamped up to `1` (constant wait) instead of producing a
+  shrinking backoff, matching Go's `backoffWait`.
+
+## [0.1.0] - 2026-07-26
+
+### Changed
+
+- Licensed under Apache-2.0 (was `Proprietary`) and published to public PyPI as `pgcommon`
+  via Trusted Publishing — the source repository itself stays private. See
+  [VERSIONING.md § Publishing to PyPI](VERSIONING.md#publishing-to-pypi).
+
+### Added
+
+- Initial Python port of `platform-pgcommon` (Go) for `asyncio`/FastAPI services, built on `asyncpg`.
+- `Config`, `config_from_env`, `ConfigWarning` (`pgcommon.config`).
+- Sentinel errors and SQLSTATE helpers (`pgcommon.errors`).
+- `GUCSet`, contextvars-based propagation, `inject_gucs` (`pgcommon.guc`).
+- `Pool` — fail-fast construction, `with_conn`, `health`, `stat`, `drain_and_close` (`pgcommon.pool`).
+- `run_in_tx`, `run_in_savepoint` (`pgcommon.tx`).
+- `RetryOptions`, `run_in_tx_with_retry`, `run_in_tx_with_retry_opts` (`pgcommon.retry`).
+- `SlowQueryTracer` (`pgcommon.tracer`).
+- Prometheus metrics + `OTelQueryRecorder` (`pgcommon.metrics`).
+- Dependency-light `.sql` migration `Runner` + `pgcommon-migrate` console script (`pgcommon.migrate`).
+- Optional FastAPI integration: lifespan pool wiring, `GUCAuthMiddleware`, `/healthz` helper (`pgcommon.integrations.fastapi`, `pgcommon[fastapi]` extra).
+- Optional `structlog` `Logger` adapter (`pgcommon[structlog]` extra).
+- Unit, integration (testcontainers Postgres), and e2e (testcontainers Postgres + PgBouncer) test suites.

{pgcommon-0.1.0 → pgcommon-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgcommon
-Version: 0.1.0
+Version: 0.2.0
 Summary: Opinionated async PostgreSQL access layer for platform services — RLS tenancy, retries, and observability by default.
 Project-URL: Homepage, https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
 Project-URL: Repository, https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
@@ -835,7 +835,7 @@ try:
     await runner.up()  # apply all pending migrations
 except MigrationDirtyError:
     # A previous migration failed mid-run. Fix the migration and manually
-    # clear the schema_migrations.dirty flag before retrying.
+    # clear the pgcommon_migrations.dirty flag before retrying.
     raise
 
 version, dirty = await runner.version()  # report current schema version
@@ -843,10 +843,12 @@ await runner.down(1)  # roll back one step
 await runner.steps(2)  # apply exactly two steps forward (or -2 to roll back two)
 ```
 
-Migration files follow the `NNNN_description.up.sql` / `NNNN_description.down.sql` naming convention (see [`migrations/`](migrations/) for the shipped example pair). Applied versions are tracked in a `schema_migrations(version bigint, dirty boolean)` table, created automatically if absent.
+Migration files follow the `NNNN_description.up.sql` / `NNNN_description.down.sql` naming convention (see [`migrations/`](migrations/) for the shipped example pair). Applied versions are tracked in a `pgcommon_migrations(version bigint, dirty boolean)` table, created automatically if absent. The default is deliberately *not* `schema_migrations` — matching the Go `pgcommon` library's own default — so this runner never collides with a consuming service's own `golang-migrate`-tracked `schema_migrations` table.
 
 > **Custom migration source:** pass any directory path as `Runner`'s second argument — it is read fresh on every `up`/`down`/`steps` call, so no code changes are needed to add migration files.
 
+> **Isolated tracking table:** pass `table="my_table"` to track versions in a table other than the default — e.g. a library that ships its own migrations (bundled with the package, applied via its own `Runner` instance) uses a dedicated table so its version/dirty state never collides with the consuming service's own domain migrations run against the same database. Pass `table="schema_migrations"` explicitly to adopt an existing `golang-migrate`-based deployment's tracking table instead.
+
 ---
 
 ## Observability — Prometheus and OTel

{pgcommon-0.1.0 → pgcommon-0.2.0}/README.md

@@ -809,7 +809,7 @@ try:
     await runner.up()  # apply all pending migrations
 except MigrationDirtyError:
     # A previous migration failed mid-run. Fix the migration and manually
-    # clear the schema_migrations.dirty flag before retrying.
+    # clear the pgcommon_migrations.dirty flag before retrying.
     raise
 
 version, dirty = await runner.version()  # report current schema version
@@ -817,10 +817,12 @@ await runner.down(1)  # roll back one step
 await runner.steps(2)  # apply exactly two steps forward (or -2 to roll back two)
 ```
 
-Migration files follow the `NNNN_description.up.sql` / `NNNN_description.down.sql` naming convention (see [`migrations/`](migrations/) for the shipped example pair). Applied versions are tracked in a `schema_migrations(version bigint, dirty boolean)` table, created automatically if absent.
+Migration files follow the `NNNN_description.up.sql` / `NNNN_description.down.sql` naming convention (see [`migrations/`](migrations/) for the shipped example pair). Applied versions are tracked in a `pgcommon_migrations(version bigint, dirty boolean)` table, created automatically if absent. The default is deliberately *not* `schema_migrations` — matching the Go `pgcommon` library's own default — so this runner never collides with a consuming service's own `golang-migrate`-tracked `schema_migrations` table.
 
 > **Custom migration source:** pass any directory path as `Runner`'s second argument — it is read fresh on every `up`/`down`/`steps` call, so no code changes are needed to add migration files.
 
+> **Isolated tracking table:** pass `table="my_table"` to track versions in a table other than the default — e.g. a library that ships its own migrations (bundled with the package, applied via its own `Runner` instance) uses a dedicated table so its version/dirty state never collides with the consuming service's own domain migrations run against the same database. Pass `table="schema_migrations"` explicitly to adopt an existing `golang-migrate`-based deployment's tracking table instead.
+
 ---
 
 ## Observability — Prometheus and OTel

{pgcommon-0.1.0 → pgcommon-0.2.0}/docs/architecture/mermaid/runintx-lifecycle.mmd

@@ -7,7 +7,7 @@ sequenceDiagram
     run_in_tx ->> pool: pool._acquire() — shared acquire primitive (also used by with_conn)
 
     opt pgbouncer_mode AND guc_provider set and GUCSet non-zero
-        run_in_tx ->> run_in_tx: guc_provider() -> GUCSet; guc_set.validate() [before BEGIN]
+        run_in_tx ->> run_in_tx: guc_provider() -> GUCSet, guc_set.validate() [before BEGIN]
     end
 
     run_in_tx ->>+ DB: conn.transaction(isolation=..., readonly=...) — BEGIN

{pgcommon-0.1.0 → pgcommon-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pgcommon"
-version = "0.1.0"
+version = "0.2.0"
 description = "Opinionated async PostgreSQL access layer for platform services — RLS tenancy, retries, and observability by default."
 readme = "README.md"
 requires-python = ">=3.12"

{pgcommon-0.1.0 → pgcommon-0.2.0}/src/pgcommon/config.py

@@ -98,9 +98,9 @@ def _parse_positive_int(env_var: str, default: int) -> tuple[int, ConfigWarning
         return default, ConfigWarning(
             key=env_var, reason=f"invalid integer {raw!r}, using default {default}"
         )
-    if parsed < 0:
+    if parsed <= 0:
         return default, ConfigWarning(
-            key=env_var, reason=f"value {parsed} must be >= 0, using default {default}"
+            key=env_var, reason=f"value {parsed} must be positive, using default {default}"
         )
     return parsed, None
 
@@ -119,17 +119,32 @@ def _parse_duration_with_warning(
         )
 
 
-def _parse_bool(env_var: str, default: bool) -> bool:
-    raw = os.environ.get(env_var)
-    if raw is None:
-        return default
-    return raw.strip().lower() in ("1", "true", "t", "yes", "y", "on")
+def _is_pgbouncer_mode() -> bool:
+    # Exact-string match, no trimming/case-folding — mirrors Go's `os.Getenv(...) == "true"`
+    # precisely, since a shared .env file/Helm value must behave identically for either language.
+    return os.environ.get("PG_BOUNCER_MODE") == "true"
+
 
+@dataclass(frozen=True, slots=True)
+class _DSNResult:
+    dsn: str
+    warning: ConfigWarning | None
+    # sslmode + the warning key to use if it's insecure — kept alongside the DSN because Go's
+    # two DSN-construction branches (DATABASE_URL vs PG_* parts) each have their own,
+    # mutually-exclusive sslmode source and warning key; there's no single global sslmode check.
+    sslmode: str | None
+    sslmode_warning_key: str
 
-def _build_dsn() -> tuple[str, ConfigWarning | None]:
+
+def _build_dsn() -> _DSNResult:
     database_url = os.environ.get("DATABASE_URL")
     if database_url:
-        return database_url, None
+        return _DSNResult(
+            dsn=database_url,
+            warning=None,
+            sslmode=_sslmode_of(database_url),
+            sslmode_warning_key="DATABASE_URL",
+        )
 
     host = os.environ.get("PG_HOST", "localhost")
     port = os.environ.get("PG_PORT", "5432")
@@ -138,9 +153,21 @@ def _build_dsn() -> tuple[str, ConfigWarning | None]:
     dbname = os.environ.get("PG_DBNAME", "")
     sslmode = os.environ.get("PG_SSLMODE", "require")
 
-    userinfo = f"{user}:{password}@" if user or password else ""
+    if not user or not dbname:
+        return _DSNResult(
+            dsn="",
+            warning=ConfigWarning(
+                key="PG_USER/PG_DBNAME",
+                reason="both PG_USER and PG_DBNAME are required to build a DSN; database "
+                "connections will fail",
+            ),
+            sslmode=sslmode,
+            sslmode_warning_key="PG_SSLMODE",
+        )
+
+    userinfo = f"{user}:{password}@"
     dsn = f"postgres://{userinfo}{host}:{port}/{dbname}?sslmode={sslmode}"
-    return dsn, None
+    return _DSNResult(dsn=dsn, warning=None, sslmode=sslmode, sslmode_warning_key="PG_SSLMODE")
 
 
 def _sslmode_of(dsn: str) -> str | None:
@@ -162,9 +189,10 @@ def config_from_env() -> tuple[Config, list[ConfigWarning]]:
     """
     warnings: list[ConfigWarning] = []
 
-    dsn, dsn_warning = _build_dsn()
-    if dsn_warning:
-        warnings.append(dsn_warning)
+    dsn_result = _build_dsn()
+    dsn = dsn_result.dsn
+    if dsn_result.warning:
+        warnings.append(dsn_result.warning)
 
     max_conns, w = _parse_positive_int("PG_MAX_CONNS", _DEFAULT_MAX_CONNS)
     if w:
@@ -197,14 +225,14 @@ def config_from_env() -> tuple[Config, list[ConfigWarning]]:
     )
     if w:
         warnings.append(w)
-    pgbouncer_mode = _parse_bool("PG_BOUNCER_MODE", False)
+    pgbouncer_mode = _is_pgbouncer_mode()
 
-    sslmode = os.environ.get("PG_SSLMODE") or _sslmode_of(dsn)
-    if sslmode and sslmode.lower() in _INSECURE_SSLMODES:
+    if dsn_result.sslmode and dsn_result.sslmode.lower() in _INSECURE_SSLMODES:
         warnings.append(
             ConfigWarning(
-                key="PG_SSLMODE",
-                reason=f"sslmode={sslmode!r} does not enforce TLS — use 'require' or stronger in production",
+                key=dsn_result.sslmode_warning_key,
+                reason=f"sslmode={dsn_result.sslmode!r} does not enforce TLS — use 'require' or "
+                "stronger in production",
             )
         )
 

{pgcommon-0.1.0 → pgcommon-0.2.0}/src/pgcommon/errors.py

@@ -22,6 +22,7 @@ __all__ = [
     "EmptyTenantRoleError",
     "InconsistentGUCSetError",
     "InvalidMaxConnsError",
+    "InvalidMigrationsTableError",
     "InvalidMinConnsError",
     "InvalidSavepointNameError",
     "InvalidTenantRoleError",
@@ -84,6 +85,14 @@ class MigrationDirtyError(PgCommonError):
     """Raised when the schema is left dirty by a previously failed migration run."""
 
 
+class InvalidMigrationsTableError(PgCommonError):
+    """Raised by `migrate.Runner` when `table` fails `^[A-Za-z_][A-Za-z0-9_]*$`.
+
+    The table name is interpolated directly into SQL (identifiers cannot be bound as query
+    parameters), so it is validated up front rather than escaped.
+    """
+
+
 class NoMigrationsFoundError(PgCommonError):
     """Raised when the migration source directory has no matching `*.sql` files."""
 

{pgcommon-0.1.0 → pgcommon-0.2.0}/src/pgcommon/migrate/runner.py

@@ -3,9 +3,9 @@
 Deliberately not built on Alembic — Alembic assumes SQLAlchemy models, which this library does
 not have. This is a from-scratch, `golang-migrate`-equivalent runner: it reads
 `NNNN_description.up.sql` / `NNNN_description.down.sql` pairs from a directory, tracks the
-applied version in a `schema_migrations` table, and takes a Postgres advisory lock for the
-duration of the run so two runners started concurrently (e.g. two replicas booting at once)
-don't race each other.
+applied version in a tracking table (default `pgcommon_migrations`, see `Runner.__init__`'s
+`table` param), and takes a Postgres advisory lock for the duration of the run so two runners
+started concurrently (e.g. two replicas booting at once) don't race each other.
 
 ⚠️ **Never run migrations from every replica's boot path simultaneously.** The advisory lock
 here only serializes the runs — it does not make it safe for the application to start against
@@ -26,7 +26,7 @@ from typing import TypeVar
 
 import asyncpg
 
-from pgcommon.errors import MigrationDirtyError, NoMigrationsFoundError
+from pgcommon.errors import InvalidMigrationsTableError, MigrationDirtyError, NoMigrationsFoundError
 from pgcommon.logger import Logger
 
 __all__ = ["Migration", "Runner"]
@@ -34,6 +34,7 @@ __all__ = ["Migration", "Runner"]
 T = TypeVar("T")
 
 _FILENAME_RE = re.compile(r"^(?P<version>\d+)_(?P<description>.+)\.(?P<direction>up|down)\.sql$")
+_TABLE_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 _ADVISORY_LOCK_KEY = zlib.crc32(b"pgcommon-migrate")
 _LOCK_TIMEOUT_SECONDS = 30
 
@@ -90,12 +91,33 @@ class Runner:
 
     `source` defaults are the caller's responsibility — pass an absolute or relative path to a
     directory containing `NNNN_description.up.sql` / `NNNN_description.down.sql` pairs.
+
+    `table` names the version-tracking table (default `"pgcommon_migrations"` — deliberately not
+    `"schema_migrations"`, so this runner never collides with a consuming service's own
+    `golang-migrate`/`schema_migrations`-based migrations, matching the Go `pgcommon` library's
+    default). Pass a distinct name to run an isolated set of migrations against the same database
+    without colliding with another `Runner`'s tracking table or dirty-state — e.g. a library that
+    ships its own migrations (like `eventcommon`'s outbox schema) alongside a consuming service's
+    own domain migrations, or to explicitly opt into reading/writing an existing
+    `"schema_migrations"` table from a prior `golang-migrate` deployment. Must match
+    `^[A-Za-z_][A-Za-z0-9_]*$`; it is interpolated directly into SQL since identifiers cannot be
+    bound as query parameters.
     """
 
-    def __init__(self, dsn: str, source: str | Path, *, logger: Logger | None = None) -> None:
+    def __init__(
+        self,
+        dsn: str,
+        source: str | Path,
+        *,
+        logger: Logger | None = None,
+        table: str = "pgcommon_migrations",
+    ) -> None:
+        if not _TABLE_NAME_RE.match(table):
+            raise InvalidMigrationsTableError(f"invalid migrations table name: {table!r}")
         self._dsn = dsn
         self._source = Path(source)
         self._logger = logger
+        self._table = table
 
     async def up(self) -> None:
         """Apply all pending migrations, in ascending version order."""
@@ -131,21 +153,21 @@ class Runner:
 
     async def _ensure_schema_migrations_table(self, conn: asyncpg.Connection) -> None:
         await conn.execute(
-            "CREATE TABLE IF NOT EXISTS schema_migrations ("
+            f"CREATE TABLE IF NOT EXISTS {self._table} ("
             "version bigint PRIMARY KEY, dirty boolean NOT NULL DEFAULT false)"
         )
 
     async def _current_version(self, conn: asyncpg.Connection) -> tuple[int, bool]:
-        row = await conn.fetchrow("SELECT version, dirty FROM schema_migrations LIMIT 1")
+        row = await conn.fetchrow(f"SELECT version, dirty FROM {self._table} LIMIT 1")
         if row is None:
             return 0, False
         return row["version"], row["dirty"]
 
     async def _set_version(self, conn: asyncpg.Connection, version: int, *, dirty: bool) -> None:
         async with conn.transaction():
-            await conn.execute("DELETE FROM schema_migrations")
+            await conn.execute(f"DELETE FROM {self._table}")
             await conn.execute(
-                "INSERT INTO schema_migrations (version, dirty) VALUES ($1, $2)", version, dirty
+                f"INSERT INTO {self._table} (version, dirty) VALUES ($1, $2)", version, dirty
             )
 
     async def _with_advisory_lock(

{pgcommon-0.1.0 → pgcommon-0.2.0}/src/pgcommon/retry.py

@@ -53,7 +53,10 @@ def _retry_reason(exc: BaseException) -> str | None:
 
 
 def _compute_delay_seconds(opts: RetryOptions, attempt: int) -> float:
-    delay = opts.initial_wait.total_seconds() * (opts.multiplier ** (attempt - 1))
+    # A multiplier < 1 would shrink the delay on every retry instead of growing it — Go's
+    # backoffWait clamps this up to 1 (constant wait) rather than allowing it.
+    multiplier = max(opts.multiplier, 1.0)
+    delay = opts.initial_wait.total_seconds() * (multiplier ** (attempt - 1))
     max_wait_seconds = opts.max_wait.total_seconds()
     if max_wait_seconds > 0:
         delay = min(delay, max_wait_seconds)

{pgcommon-0.1.0 → pgcommon-0.2.0}/tests/fixtures/fake_migrate_conn.py

@@ -8,8 +8,15 @@ letting a specific migration's SQL fail on demand) without a database.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field
 
+_DEFAULT_TABLE = "pgcommon_migrations"
+_CREATE_TABLE_RE = re.compile(r"CREATE TABLE IF NOT EXISTS (\w+)")
+_SELECT_VERSION_RE = re.compile(r"SELECT version, dirty FROM (\w+)")
+_DELETE_RE = re.compile(r"DELETE FROM (\w+)")
+_INSERT_RE = re.compile(r"INSERT INTO (\w+)")
+
 
 class _NoOpTransaction:
     async def __aenter__(self) -> _NoOpTransaction:
@@ -21,7 +28,15 @@ class _NoOpTransaction:
 
 @dataclass
 class FakeMigrationConnection:
+    """Tracks per-table schema state so tests can drive two `Runner`s (different `table=`)
+    against the same fake connection and assert their version bookkeeping stays independent.
+
+    `schema_migrations` is kept as a plain attribute (not nested under `tables`) for backward
+    compatibility with existing tests that only ever use the default table name.
+    """
+
     schema_migrations: dict[str, object] | None = None
+    tables: dict[str, dict[str, object] | None] = field(default_factory=dict)
     executed_migration_sql: list[str] = field(default_factory=list)
     lock_calls: list[int] = field(default_factory=list)
     unlock_calls: list[int] = field(default_factory=list)
@@ -29,12 +44,24 @@ class FakeMigrationConnection:
     closed: bool = False
     call_order: list[str] = field(default_factory=list)
 
+    def _get_table_state(self, table: str) -> dict[str, object] | None:
+        if table == _DEFAULT_TABLE:
+            return self.schema_migrations
+        return self.tables.get(table)
+
+    def _set_table_state(self, table: str, state: dict[str, object] | None) -> None:
+        if table == _DEFAULT_TABLE:
+            self.schema_migrations = state
+        else:
+            self.tables[table] = state
+
     async def execute(self, sql: str, *args: object) -> str:
         stripped = sql.strip()
         if stripped.startswith("SET lock_timeout"):
             return "SET"
-        if stripped.startswith("CREATE TABLE IF NOT EXISTS schema_migrations"):
+        if m := _CREATE_TABLE_RE.match(stripped):
             self.call_order.append("create_table")
+            self.tables.setdefault(m.group(1), self.tables.get(m.group(1)))
             return "CREATE TABLE"
         if stripped.startswith("SELECT pg_advisory_lock"):
             self.call_order.append("lock")
@@ -43,12 +70,12 @@ class FakeMigrationConnection:
         if stripped.startswith("SELECT pg_advisory_unlock"):
             self.unlock_calls.append(args[0])  # type: ignore[arg-type]
             return "SELECT"
-        if stripped.startswith("DELETE FROM schema_migrations"):
-            self.schema_migrations = None
+        if m := _DELETE_RE.match(stripped):
+            self._set_table_state(m.group(1), None)
             return "DELETE"
-        if stripped.startswith("INSERT INTO schema_migrations"):
+        if m := _INSERT_RE.match(stripped):
             version, dirty = args
-            self.schema_migrations = {"version": version, "dirty": dirty}
+            self._set_table_state(m.group(1), {"version": version, "dirty": dirty})
             return "INSERT"
 
         self.executed_migration_sql.append(stripped)
@@ -57,6 +84,9 @@ class FakeMigrationConnection:
         return "SELECT"
 
     async def fetchrow(self, sql: str, *args: object) -> dict[str, object] | None:
+        stripped = sql.strip()
+        if m := _SELECT_VERSION_RE.match(stripped):
+            return self._get_table_state(m.group(1))
         return self.schema_migrations
 
     def transaction(self, **_kwargs: object) -> _NoOpTransaction:

{pgcommon-0.1.0 → pgcommon-0.2.0}/tests/integration/test_migrate_runner_integration.py

@@ -35,9 +35,11 @@ def migrations_dir(tmp_path: Path, table: str) -> Path:
 
 @pytest.fixture(autouse=True)
 async def _drop_schema_migrations(postgres_dsn: str, pg_conn):
-    # Each integration test file shares one Postgres container; keep schema_migrations state
-    # isolated per test by resetting it before every test in this module.
-    await pg_conn.execute("DROP TABLE IF EXISTS schema_migrations")
+    # Each integration test file shares one Postgres container; keep the tracking table's state
+    # isolated per test by resetting it before every test in this module. "pgcommon_migrations"
+    # is the Runner's default (see runner.py) — deliberately not "schema_migrations", so this
+    # library never collides with a consuming service's own golang-migrate-tracked table.
+    await pg_conn.execute("DROP TABLE IF EXISTS pgcommon_migrations")
     yield
 
 

{pgcommon-0.1.0 → pgcommon-0.2.0}/tests/unit/test_config.py

@@ -97,20 +97,46 @@ def test_config_from_env_builds_dsn_from_pg_vars(monkeypatch: pytest.MonkeyPatch
 
 
 def test_config_from_env_defaults_host_and_sslmode(monkeypatch: pytest.MonkeyPatch) -> None:
-    cfg, _ = config_from_env()
-    assert cfg.dsn == "postgres://localhost:5432/?sslmode=require"
+    # PG_USER/PG_DBNAME are required to build a DSN from parts (see the dedicated warning test
+    # below) — set them here so this test isolates the host/port/sslmode defaults.
+    monkeypatch.setenv("PG_USER", "svc")
+    monkeypatch.setenv("PG_DBNAME", "orders")
+    cfg, warnings = config_from_env()
+    assert cfg.dsn == "postgres://svc:@localhost:5432/orders?sslmode=require"
+    assert warnings == []
+
+
+def test_config_from_env_warns_when_user_or_dbname_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Matches Go's buildDSN: DSN is left empty (not a syntactically-valid-but-unusable string)
+    # when either PG_USER or PG_DBNAME is missing, so Pool.create fails fast with a clear error.
+    cfg, warnings = config_from_env()
+    assert cfg.dsn == ""
+    assert any(w.key == "PG_USER/PG_DBNAME" for w in warnings)
+
+
+def test_config_from_env_warns_when_only_dbname_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PG_USER", "svc")
+    cfg, warnings = config_from_env()
+    assert cfg.dsn == ""
+    assert any(w.key == "PG_USER/PG_DBNAME" for w in warnings)
 
 
 @pytest.mark.parametrize("sslmode", ["disable", "allow", "prefer"])
 def test_config_from_env_warns_on_insecure_sslmode(
     monkeypatch: pytest.MonkeyPatch, sslmode: str
 ) -> None:
+    monkeypatch.setenv("PG_USER", "svc")
+    monkeypatch.setenv("PG_DBNAME", "orders")
     monkeypatch.setenv("PG_SSLMODE", sslmode)
     _, warnings = config_from_env()
     assert any(w.key == "PG_SSLMODE" for w in warnings)
 
 
 def test_config_from_env_no_warning_for_require(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PG_USER", "svc")
+    monkeypatch.setenv("PG_DBNAME", "orders")
     monkeypatch.setenv("PG_SSLMODE", "require")
     _, warnings = config_from_env()
     assert warnings == []
@@ -121,10 +147,26 @@ def test_config_from_env_warns_on_insecure_sslmode_in_database_url(
 ) -> None:
     monkeypatch.setenv("DATABASE_URL", "postgres://user:pass@host:5432/db?sslmode=disable")
     _, warnings = config_from_env()
-    assert any(w.key == "PG_SSLMODE" for w in warnings)
+    # Once DATABASE_URL is set, Go inspects only the DSN's own sslmode query param (never
+    # PG_SSLMODE) and keys the warning "DATABASE_URL", not "PG_SSLMODE".
+    assert any(w.key == "DATABASE_URL" for w in warnings)
+
+
+def test_config_from_env_ignores_pg_sslmode_env_var_once_database_url_is_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A secure PG_SSLMODE env var must not mask an insecure sslmode inside DATABASE_URL itself —
+    # and, symmetrically, a "secure-looking" DATABASE_URL must not be second-guessed by a
+    # leftover insecure PG_SSLMODE env var either. DATABASE_URL's own query param always wins.
+    monkeypatch.setenv("PG_SSLMODE", "require")
+    monkeypatch.setenv("DATABASE_URL", "postgres://user:pass@host:5432/db?sslmode=disable")
+    _, warnings = config_from_env()
+    assert any(w.key == "DATABASE_URL" for w in warnings)
 
 
 def test_config_from_env_parses_durations(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PG_USER", "svc")
+    monkeypatch.setenv("PG_DBNAME", "orders")
     monkeypatch.setenv("PG_MAX_CONN_LIFETIME", "2h")
     monkeypatch.setenv("PG_SLOW_QUERY_THRESHOLD", "500ms")
     cfg, warnings = config_from_env()
@@ -160,12 +202,34 @@ def test_config_from_env_warns_and_defaults_on_negative_int(
     assert any(w.key == "PG_MIN_CONNS" for w in warnings)
 
 
+def test_config_from_env_warns_and_defaults_on_zero_int(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Zero must be rejected too, not just negative values — matches Go's parsePositiveInt32,
+    # which checks `v <= 0`, not `v < 0`.
+    monkeypatch.setenv("PG_MAX_CONNS", "0")
+    cfg, warnings = config_from_env()
+    assert cfg.max_conns == 10
+    assert any(w.key == "PG_MAX_CONNS" for w in warnings)
+
+
 def test_config_from_env_parses_bouncer_mode(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("PG_BOUNCER_MODE", "true")
     cfg, _ = config_from_env()
     assert cfg.pgbouncer_mode is True
 
 
+@pytest.mark.parametrize("value", ["1", "yes", "True", "TRUE", "on", " true", "true "])
+def test_config_from_env_bouncer_mode_requires_exact_lowercase_true(
+    monkeypatch: pytest.MonkeyPatch, value: str
+) -> None:
+    # Go matches only the exact string "true" (os.Getenv(...) == "true") — no case-folding, no
+    # trimming, no other truthy spellings. A shared .env file must behave identically either way.
+    monkeypatch.setenv("PG_BOUNCER_MODE", value)
+    cfg, _ = config_from_env()
+    assert cfg.pgbouncer_mode is False
+
+
 @pytest.mark.parametrize(
     "env_var",
     [
@@ -191,6 +255,8 @@ def test_config_from_env_no_warning_when_database_url_has_no_sslmode(
 
 
 def test_config_from_env_min_conns_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("PG_USER", "svc")
+    monkeypatch.setenv("PG_DBNAME", "orders")
     monkeypatch.setenv("PG_MIN_CONNS", "5")
     cfg, warnings = config_from_env()
     assert cfg.min_conns == 5

{pgcommon-0.1.0 → pgcommon-0.2.0}/tests/unit/test_migrate_runner.py

@@ -5,7 +5,7 @@ from pathlib import Path
 import pytest
 
 import pgcommon.migrate.runner as runner_module
-from pgcommon.errors import MigrationDirtyError, NoMigrationsFoundError
+from pgcommon.errors import InvalidMigrationsTableError, MigrationDirtyError, NoMigrationsFoundError
 from pgcommon.migrate.runner import Runner, _load_migrations
 from tests.fixtures.fake_migrate_conn import FakeMigrationConnection
 from tests.fixtures.fakes import FakeLogger
@@ -363,3 +363,62 @@ def test_load_migrations_skips_subdirectories(tmp_path: Path) -> None:
     (d / "0002_not_a_file.up.sql").mkdir()  # a directory that happens to match the pattern
     migrations = _load_migrations(d)
     assert set(migrations) == {1}
+
+
+# --- table= (isolated tracking table name) ---
+
+
+def test_default_table_name_is_pgcommon_migrations(migrations_dir: Path) -> None:
+    runner = Runner("postgres://localhost/db", migrations_dir)
+    assert runner._table == "pgcommon_migrations"
+
+
+async def test_can_override_to_schema_migrations_for_golang_migrate_compat(
+    migrations_dir: Path, patch_connect: FakeMigrationConnection
+) -> None:
+    # golang-migrate (and any pre-existing golang-migrate-based deployment) tracks versions in
+    # "schema_migrations" — a caller adopting that table explicitly opts in via table=.
+    runner = Runner("postgres://localhost/db", migrations_dir, table="schema_migrations")
+    await runner.up()
+    assert patch_connect.tables["schema_migrations"] == {"version": 3, "dirty": False}
+
+
+async def test_custom_table_name_is_used_for_tracking(
+    migrations_dir: Path, patch_connect: FakeMigrationConnection
+) -> None:
+    runner = Runner("postgres://localhost/db", migrations_dir, table="outbox_migrations")
+    await runner.up()
+    assert patch_connect.schema_migrations is None
+    assert patch_connect.tables["outbox_migrations"] == {"version": 3, "dirty": False}
+
+
+async def test_two_runners_with_different_tables_track_versions_independently(
+    migrations_dir: Path, patch_connect: FakeMigrationConnection
+) -> None:
+    domain_runner = Runner("postgres://localhost/db", migrations_dir)
+    outbox_runner = Runner("postgres://localhost/db", migrations_dir, table="outbox_migrations")
+
+    await domain_runner.up()
+    assert patch_connect.schema_migrations == {"version": 3, "dirty": False}
+    assert patch_connect.tables.get("outbox_migrations") is None
+
+    patch_connect.executed_migration_sql.clear()
+    await outbox_runner.up()
+    assert patch_connect.tables["outbox_migrations"] == {"version": 3, "dirty": False}
+    # Domain runner's version is untouched by the outbox runner's run.
+    assert patch_connect.schema_migrations == {"version": 3, "dirty": False}
+
+    domain_version, domain_dirty = await domain_runner.version()
+    outbox_version, outbox_dirty = await outbox_runner.version()
+    assert (domain_version, domain_dirty) == (3, False)
+    assert (outbox_version, outbox_dirty) == (3, False)
+
+
+@pytest.mark.parametrize("bad_table", ["", "1abc", "has space", "has-dash", "drop table;--"])
+def test_invalid_table_name_raises(bad_table: str, tmp_path: Path) -> None:
+    with pytest.raises(InvalidMigrationsTableError):
+        Runner("postgres://localhost/db", tmp_path, table=bad_table)
+
+
+def test_valid_table_name_with_underscore_and_digits_is_accepted(tmp_path: Path) -> None:
+    Runner("postgres://localhost/db", tmp_path, table="outbox_migrations_v2")

{pgcommon-0.1.0 → pgcommon-0.2.0}/tests/unit/test_retry.py

@@ -204,3 +204,14 @@ async def test_jitter_produces_varying_delays_within_bounds(patch_create_pool) -
     assert len(delays) > 1
     for d in delays:
         assert 0.05 <= d <= 0.15 + 1e-9
+
+
+def test_multiplier_below_one_is_clamped_to_constant_wait() -> None:
+    # A multiplier < 1 would shrink the delay on every retry — Go's backoffWait clamps this up
+    # to 1 (a constant wait) rather than allowing a shrinking backoff.
+    from pgcommon.retry import _compute_delay_seconds
+
+    opts = RetryOptions(initial_wait=timedelta(milliseconds=50), multiplier=0.5)
+    assert _compute_delay_seconds(opts, 1) == pytest.approx(0.05)
+    assert _compute_delay_seconds(opts, 2) == pytest.approx(0.05)
+    assert _compute_delay_seconds(opts, 3) == pytest.approx(0.05)

{pgcommon-0.1.0 → pgcommon-0.2.0}/uv.lock

@@ -681,7 +681,7 @@ wheels = [
 
 [[package]]
 name = "pgcommon"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },

pgcommon-0.1.0/CHANGELOG.md

@@ -1,29 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows [semantic versioning](VERSIONING.md).
-
-## [Unreleased]
-
-## [0.1.0] - 2026-07-26
-
-### Changed
-
-- Licensed under Apache-2.0 (was `Proprietary`) and published to public PyPI as `pgcommon`
-  via Trusted Publishing — the source repository itself stays private. See
-  [VERSIONING.md § Publishing to PyPI](VERSIONING.md#publishing-to-pypi).
-
-### Added
-
-- Initial Python port of `platform-pgcommon` (Go) for `asyncio`/FastAPI services, built on `asyncpg`.
-- `Config`, `config_from_env`, `ConfigWarning` (`pgcommon.config`).
-- Sentinel errors and SQLSTATE helpers (`pgcommon.errors`).
-- `GUCSet`, contextvars-based propagation, `inject_gucs` (`pgcommon.guc`).
-- `Pool` — fail-fast construction, `with_conn`, `health`, `stat`, `drain_and_close` (`pgcommon.pool`).
-- `run_in_tx`, `run_in_savepoint` (`pgcommon.tx`).
-- `RetryOptions`, `run_in_tx_with_retry`, `run_in_tx_with_retry_opts` (`pgcommon.retry`).
-- `SlowQueryTracer` (`pgcommon.tracer`).
-- Prometheus metrics + `OTelQueryRecorder` (`pgcommon.metrics`).
-- Dependency-light `.sql` migration `Runner` + `pgcommon-migrate` console script (`pgcommon.migrate`).
-- Optional FastAPI integration: lifespan pool wiring, `GUCAuthMiddleware`, `/healthz` helper (`pgcommon.integrations.fastapi`, `pgcommon[fastapi]` extra).
-- Optional `structlog` `Logger` adapter (`pgcommon[structlog]` extra).
-- Unit, integration (testcontainers Postgres), and e2e (testcontainers Postgres + PgBouncer) test suites.