pgdevkit 0.1.0__py3-none-any.whl

pgdevkit/skills/pgdevkit/references/complex_helper.py

@@ -0,0 +1,234 @@
+"""
+ComplexHelper — psycopg adapter for PostgreSQL composite types, enums, and JSONB.
+
+Use this when your project has custom PostgreSQL types (composite types, enums)
+that need to be registered with psycopg before inserting test data. Plain columns
+and JSONB are handled automatically by pgdevkit.testdb.schema's _insert_test_data;
+you only need this class for USER-DEFINED types, which that function does not
+yet support natively — wrap the connection it's given before the INSERT:
+
+    from pgdevkit.testdb import schema  # for reference, not a public extension point yet
+    from your_project.pg_complex_helper import ComplexHelper
+
+    async def insert_test_data_with_complex_types(json_file, table, force_reset, con):
+        helper = ComplexHelper(con)
+        schema_name, table_name = table.split(".")
+        complex_types = await helper.load_all_complex_types((schema_name, table_name))
+        rows = json.loads(json_file.read_text(encoding="utf-8"))
+        for row in rows:
+            for col, info in complex_types.items():
+                if col in row:
+                    row[col] = await helper.recursive_convert(row[col], info, con)
+        # then insert `rows` the same way schema.py's _insert_test_data does
+"""
+
+from psycopg import AsyncConnection
+from psycopg.rows import dict_row
+from typing import Any
+from psycopg.sql import Identifier
+from psycopg.types.composite import CompositeInfo, register_composite
+from psycopg.types.json import Jsonb
+from psycopg.types.enum import EnumInfo, register_enum
+
+
+class ComplexHelper:
+    complex_types: dict[tuple[str, str], CompositeInfo | EnumInfo] = {}
+
+    def __init__(self, con: AsyncConnection):
+        self.con = con
+        self.system_complex_type_dict = None
+
+        self.registered: set[CompositeInfo | EnumInfo] = set()
+
+    async def load_complex_type_dict(self):
+        async with self.con.cursor(row_factory=dict_row) as cur:
+            await cur.execute("""
+        SELECT t.oid,
+                pg_catalog.format_type ( t.oid, NULL ) AS obj_name,
+				t.typtype
+            FROM pg_catalog.pg_type t
+            JOIN pg_catalog.pg_namespace n
+                ON n.oid = t.typnamespace
+            WHERE ( t.typrelid = 0
+                    OR ( SELECT c.relkind = 'c'
+                            FROM pg_catalog.pg_class c
+                            WHERE c.oid = t.typrelid ) )
+                AND n.nspname <> 'pg_catalog'
+                AND n.nspname <> 'information_schema'
+                AND n.nspname !~ '^pg_toast'""")
+            system_complex_types = await cur.fetchall()
+            self.system_complex_type_dict = {
+                r["oid"]: (r["obj_name"], r["typtype"]) for r in system_complex_types
+            }
+
+    async def _load_complex_type_from_colinfos(
+        self, res: dict[str, Any] | None
+    ) -> CompositeInfo | EnumInfo | type[Jsonb] | None:
+        if not res:
+            return None
+        if res["data_type"].lower() == "jsonb":
+            return Jsonb
+        if res["data_type"].upper() == "ARRAY" and res["udt_name"] == "_jsonb":
+            return Jsonb
+        if (
+            not res["is_enum"]
+            and not res["is_user_defined"]
+            and not (res["data_type"] == "ARRAY" and res["udt_schema"] != "pg_catalog")
+        ):
+            return None
+        udt_schema: str = res["udt_schema"]
+        udt_name: str = res["udt_name"]
+        c = await self._get_complex_type(
+            f"{udt_schema}.{udt_name}", res["is_enum"], self.con
+        )
+        await self._recurse_register(c, self.con)
+        return c
+
+    async def load_all_complex_types(
+        self, table_name: tuple[str, str], include_generated: bool = False
+    ) -> dict[str, CompositeInfo | type[Jsonb] | EnumInfo | None]:
+        if self.system_complex_type_dict is None:
+            await self.load_complex_type_dict()
+        colquery = """
+        with enum_types as (
+                            select n.nspname  as enum_schema, t.typname as enum_name from pg_type t
+                                inner join pg_namespace n on n.oid=t.typnamespace
+                                where typtype='e'
+                        )
+        select column_name, data_type,
+            data_type='USER-DEFINED' as is_user_defined,
+            udt_schema, udt_name,
+            e.enum_name is not null as is_enum
+              from information_schema.columns c
+                 left join enum_types e on e.enum_schema=c.udt_schema and e.enum_name=c.udt_name
+              where table_schema=%(schema)s and table_name = %(tbl)s and (is_generated <> 'ALWAYS' or %(include_generated)s)"""
+        async with self.con.cursor(row_factory=dict_row) as cur:
+            await cur.execute(
+                colquery,
+                {
+                    "schema": table_name[0],
+                    "tbl": table_name[1],
+                    "include_generated": include_generated,
+                },
+            )
+            res = await cur.fetchall()
+            return {
+                r["column_name"]: await self._load_complex_type_from_colinfos(r)
+                for r in res
+            }
+
+    async def load_complex_type(
+        self, table_name: tuple[str, str], col_name: str
+    ) -> CompositeInfo | type[Jsonb] | EnumInfo | None:
+        if self.system_complex_type_dict is None:
+            await self.load_complex_type_dict()
+        colquery = """
+        with enum_types as (
+                            select n.nspname  as enum_schema, t.typname as enum_name from pg_type t
+                                inner join pg_namespace n on n.oid=t.typnamespace
+                                where typtype='e'
+                        )
+        select column_name, data_type,
+            data_type='USER-DEFINED' as is_user_defined,
+            udt_schema, udt_name,
+            e.enum_name is not null as is_enum
+              from information_schema.columns c
+            left join enum_types e on e.enum_schema=c.udt_schema and e.enum_name=c.udt_name
+              where table_schema=%(schema)s and table_name = %(tbl)s
+                and column_name = %(col)s"""
+        async with self.con.cursor(row_factory=dict_row) as cur:
+            await cur.execute(
+                colquery,
+                {"schema": table_name[0], "tbl": table_name[1], "col": col_name},
+            )
+            res = await cur.fetchone()
+
+            return await self._load_complex_type_from_colinfos(res)
+
+    async def _get_complex_type(
+        self, name: str, is_enum: bool, con: AsyncConnection
+    ) -> CompositeInfo | EnumInfo:
+        if name.endswith("[]"):
+            name = name[:-2]
+        schema, type_name = name.split(".")
+        if type_name.startswith(
+            "_"
+        ):  # the array type in PostgreSQL starts with an underscore
+            type_name = type_name[1:]
+        if is_enum:
+            ci = await EnumInfo.fetch(con, Identifier(schema, type_name))
+            assert ci is not None, f"Enum type {name} not found in database"
+            self.complex_types[(schema, type_name)] = ci
+        if (schema, type_name) not in self.complex_types:
+            ci = await CompositeInfo.fetch(con, Identifier(schema, type_name))
+            assert ci is not None, f"Complex type {name} not found in database"
+            self.complex_types[(schema, type_name)] = ci
+        return self.complex_types[(schema, type_name)]
+
+    async def _recurse_register(
+        self, info: CompositeInfo | EnumInfo, con: AsyncConnection
+    ):
+        assert self.system_complex_type_dict is not None, (
+            "System complex type dictionary not loaded"
+        )
+        if info not in self.registered:
+            if isinstance(info, EnumInfo):
+                register_enum(info, con)
+            else:
+                register_composite(info, con)
+            self.registered.add(info)
+        if isinstance(info, EnumInfo):
+            return
+        for t in info.field_types:
+            if t in self.system_complex_type_dict:
+                name, typtype = self.system_complex_type_dict[t]
+                ci = await self._get_complex_type(name, typtype == "e", con)
+                await self._recurse_register(ci, con)
+
+    async def recursive_convert(
+        self,
+        value: Any,
+        info: CompositeInfo | EnumInfo | type[Jsonb] | None,
+        con: AsyncConnection,
+    ) -> Any:
+        if info is None:
+            return value
+        if value is None:
+            return None
+        if self.system_complex_type_dict is None:
+            await self.load_complex_type_dict()
+        if isinstance(value, list):
+            return [await self.recursive_convert(item, info, con) for item in value]
+        prms = {}
+        if info == Jsonb:
+            return Jsonb(value)
+        if isinstance(value, str):
+            assert isinstance(info, EnumInfo), f"Expected EnumInfo, got {type(info)}"
+            return getattr(info.enum, value)  # Enum
+        assert isinstance(info, CompositeInfo), (
+            f"Expected CompositeInfo, got {type(info)}"
+        )
+        assert self.system_complex_type_dict is not None, (
+            "System complex type dictionary not loaded"
+        )
+        for k, v in value.items():
+            if v is None:
+                prms[k] = None
+                continue
+            fi = info.field_names.index(k)
+            type_oid = info.field_types[fi]
+            if type_oid in self.system_complex_type_dict:
+                name, typtype = self.system_complex_type_dict[type_oid]
+                ci = await self._get_complex_type(name, typtype == "e", con)
+                if name.endswith("[]"):
+                    prms[k] = [
+                        await self.recursive_convert(item, ci, con) for item in v
+                    ]
+                else:
+                    prms[k] = await self.recursive_convert(v, ci, con)
+            else:
+                prms[k] = v
+        assert info.python_type is not None, (
+            f"Python type for {info.name} is null, maybe an array?"
+        )
+        return info.python_type(**prms) if prms else None

pgdevkit/skills/pgdevkit/references/dynamic-sql.md

@@ -0,0 +1,92 @@
+# Dynamic SQL
+
+Avoid dynamic SQL whenever possible — a static `.sql` file is always clearer. When column or table names genuinely vary at runtime, check `pyproject.toml` (or `[project] requires-python`) to pick an approach at authoring time, not with a runtime `sys.version_info` check.
+
+---
+
+## Python 3.14+ — t-string templates
+
+T-strings look like f-strings but are evaluated by psycopg — values are always sent as bound parameters, never interpolated.
+
+**Format specifiers:**
+
+| Specifier | Meaning |
+|-----------|---------|
+| `{val}` / `{val:s}` | Bound parameter, automatic format (default) |
+| `{val:b}` | Bound parameter, binary format |
+| `{val:t}` | Bound parameter, text format |
+| `{name:i}` | SQL identifier (table/column name) — double-quoted |
+| `{val:l}` | Literal value merged client-side (use sparingly) |
+| `{snippet:q}` | SQL snippet — another t-string or `sql.SQL`/`Composed` instance |
+
+**Basic parameter:**
+
+```python
+await cur.execute(t"SELECT * FROM users WHERE id = {user_id}")
+```
+
+**Dynamic identifier (`:i`):**
+
+```python
+column = "email"
+await cur.execute(t"SELECT {column:i} FROM users WHERE active = {active}")
+```
+
+**NOTIFY — requires client-side composition (`:i` and `:l`):**
+
+```python
+def send_notify(conn: Connection, channel: str, payload: str) -> None:
+    conn.execute(t"NOTIFY {channel:i}, {payload:l}")
+```
+
+**Nested templates with `:q` (dynamic WHERE clause):**
+
+```python
+from psycopg import sql
+
+def search_users(
+    conn: Connection,
+    ids: Sequence[int] | None = None,
+    name_pattern: str | None = None,
+) -> list[UserRow]:
+    filters = []
+    if ids is not None:
+        filters.append(t"u.id = ANY({list(ids)})")
+    if name_pattern is not None:
+        filters.append(t"u.name ~* {name_pattern}")
+    if not filters:
+        raise TypeError("at least one filter required")
+    joined = sql.SQL(" AND ").join(filters)
+    cur = conn.cursor(row_factory=class_row(UserRow))
+    cur.execute(t"SELECT * FROM users AS u WHERE {joined:q}")
+    return cur.fetchall()
+```
+
+**Inspect composed SQL without executing:**
+
+```python
+from psycopg import sql
+
+name = "O'Reilly"
+dob = datetime.date(1970, 1, 1)
+print(sql.as_string(t"INSERT INTO tbl VALUES ({name}, {dob})"))
+# INSERT INTO tbl VALUES ('O''Reilly', '1970-01-01'::date)
+```
+
+---
+
+## Python < 3.14 — `psycopg.sql`
+
+```python
+from psycopg import sql
+
+column = "email"
+query = sql.SQL("SELECT {col} FROM users WHERE active = %(active)s").format(
+    col=sql.Identifier(column),
+)
+await cur.execute(query, {"active": True})
+```
+
+`sql.Identifier` quotes the identifier at the driver level — SQL injection via column/table names is impossible. Values always stay as bound parameters.
+
+**Never** use f-strings or string concatenation for identifiers or values.

pgdevkit/skills/pgdevkit/references/temporal-tables.md

@@ -0,0 +1,33 @@
+# Temporal Tables (row-level history)
+
+Use [nearform/temporal_tables](https://github.com/nearform/temporal_tables) — a pure PL/pgSQL trigger that archives every changed row to a parallel history table. Copy `versioning_function.sql` and `system_time_function.sql` from the repo into `db/migrations/` and apply them as a baseline migration.
+
+For each versioned table, add `sys_period`, create the history table with `LIKE`, and attach the trigger:
+
+```sql
+alter table users
+    add column sys_period tstzrange not null default tstzrange(current_timestamp, null);
+
+create table users_history (like users);
+
+create index on users_history using gist (id, sys_period);
+
+create trigger users_versioning
+before insert or update or delete on users
+for each row execute procedure versioning(
+    'sys_period',    -- system-period column
+    'users_history', -- history table name
+    true,            -- conflict mitigation
+    false             -- skip entry when no values changed
+);
+```
+
+`CREATE TABLE … LIKE` copies all columns and their types. Do not add a PK to the history table — the same `id` appears once per version.
+
+Query point-in-time with `@>`:
+
+```sql
+select * from users_history where id = %(id)s and sys_period @> %(as_of)s::timestamptz
+```
+
+`set_system_time('2023-01-01+00')` / `set_system_time(null)` backdates operations (useful for migrations).

pgdevkit/testdb/__init__.py

@@ -0,0 +1,3 @@
+from .api import clean_testdb, dsn_for, ensure_testdb, reset_testdb, run_sql, status
+
+__all__ = ["clean_testdb", "dsn_for", "ensure_testdb", "reset_testdb", "run_sql", "status"]

pgdevkit/testdb/api.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import psycopg
+from psycopg.sql import SQL, Identifier
+
+from . import constants, query
+from .config import ProjectConfig, load_config
+from .container import ensure_container
+from .naming import current_branch, slugify, workspace_db_name
+from .schema import apply_schema
+
+
+def _admin_dsn() -> str:
+    return f"postgresql://{constants.USER}:{constants.PASSWORD}@{constants.HOST}:{constants.PORT}/postgres?connect_timeout=10"
+
+
+def _db_dsn(db_name: str) -> str:
+    return f"postgresql://{constants.USER}:{constants.PASSWORD}@{constants.HOST}:{constants.PORT}/{db_name}?connect_timeout=10"
+
+
+def _resolve(project_root: Path | None) -> tuple[ProjectConfig, str]:
+    config = load_config(project_root)
+    branch = current_branch(config.root)
+    db_name = workspace_db_name(config.name, branch)
+    return config, db_name
+
+
+def _env_for(config: ProjectConfig, db_name: str) -> dict[str, str]:
+    prefix = config.env_prefix
+    return {
+        f"{prefix}POSTGRES_HOST": constants.HOST,
+        f"{prefix}POSTGRES_PORT": str(constants.PORT),
+        f"{prefix}POSTGRES_DB": db_name,
+        f"{prefix}POSTGRES_USER": constants.USER,
+        f"{prefix}POSTGRES_PASSWORD": constants.PASSWORD,
+    }
+
+
+async def _ensure_database(db_name: str) -> None:
+    async with await psycopg.AsyncConnection.connect(_admin_dsn(), autocommit=True) as con:
+        result = await con.execute("SELECT 1 FROM pg_database WHERE datname = %(db)s", {"db": db_name})
+        if await result.fetchone():
+            return
+        try:
+            await con.execute(SQL("CREATE DATABASE {}").format(Identifier(db_name)))
+        except psycopg.errors.DuplicateDatabase:
+            pass
+
+
+async def _drop_database(db_name: str) -> None:
+    async with await psycopg.AsyncConnection.connect(_admin_dsn(), autocommit=True) as con:
+        await con.execute(
+            "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = %(db)s",
+            {"db": db_name},
+        )
+        await con.execute(SQL("DROP DATABASE IF EXISTS {}").format(Identifier(db_name)))
+
+
+async def _apply(config: ProjectConfig, db_name: str, force_reset: bool) -> None:
+    async with await psycopg.AsyncConnection.connect(_db_dsn(db_name), autocommit=True) as con:
+        await apply_schema(
+            con,
+            config.root / config.database_dir,
+            extensions=config.extensions,
+            force_reset=force_reset,
+        )
+
+
+def ensure_testdb(project_root: Path | None = None, force_reset: bool = False) -> dict[str, str]:
+    """Ensure the shared container is running, this workspace's database
+    exists, and its schema is applied. Returns the {PREFIX}POSTGRES_* env
+    vars for this workspace."""
+    ensure_container()
+    config, db_name = _resolve(project_root)
+
+    async def _run() -> None:
+        if force_reset:
+            await _drop_database(db_name)
+        await _ensure_database(db_name)
+        await _apply(config, db_name, force_reset)
+
+    asyncio.run(_run())
+    return _env_for(config, db_name)
+
+
+def reset_testdb(project_root: Path | None = None) -> dict[str, str]:
+    """Drop and recreate only this workspace's database, then reapply
+    schema and seed data."""
+    return ensure_testdb(project_root, force_reset=True)
+
+
+def clean_testdb(project_root: Path | None = None, all: bool = False) -> None:
+    """Drop this workspace's database. With all=True, drop every database
+    belonging to this project (matched by its name-slug prefix), across
+    every worktree/branch."""
+    config, db_name = _resolve(project_root)
+
+    async def _run() -> None:
+        if not all:
+            await _drop_database(db_name)
+            return
+        prefix = f"{slugify(config.name)}_"
+        escaped_prefix = prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        async with await psycopg.AsyncConnection.connect(_admin_dsn(), autocommit=True) as con:
+            result = await con.execute(
+                "SELECT datname FROM pg_database WHERE datname LIKE %(pattern)s ESCAPE '\\'",
+                {"pattern": f"{escaped_prefix}%"},
+            )
+            names = [row[0] for row in await result.fetchall()]
+        for name in names:
+            await _drop_database(name)
+
+    asyncio.run(_run())
+
+
+def status(project_root: Path | None = None) -> dict[str, str]:
+    config, db_name = _resolve(project_root)
+    return {
+        "container": constants.CONTAINER_NAME,
+        "host": constants.HOST,
+        "port": str(constants.PORT),
+        "database": db_name,
+        "dsn": _db_dsn(db_name),
+    }
+
+
+def run_sql(sql: str, project_root: Path | None = None) -> list[dict] | None:
+    _, db_name = _resolve(project_root)
+    return asyncio.run(query.execute(_db_dsn(db_name), sql))
+
+
+def dsn_for(project_root: Path | None = None) -> str:
+    _, db_name = _resolve(project_root)
+    return _db_dsn(db_name)

pgdevkit/testdb/config.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    name: str
+    database_dir: str = "database"
+    env_prefix: str = ""
+    extensions: tuple[str, ...] = ()
+    root: Path = field(default_factory=Path)
+
+    def __post_init__(self) -> None:
+        if not self.env_prefix:
+            object.__setattr__(self, "env_prefix", f"{self.name.upper()}_")
+
+
+def _find_pyproject(start: Path) -> Path | None:
+    for directory in [start, *start.parents]:
+        candidate = directory / "pyproject.toml"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_config(start: Path | None = None) -> ProjectConfig:
+    start = (start or Path.cwd()).resolve()
+    pyproject = _find_pyproject(start)
+    root = pyproject.parent if pyproject else start
+
+    section: dict = {}
+    if pyproject is not None:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        section = data.get("tool", {}).get("pgdevkit", {})
+
+    extensions = section.get("extensions", [])
+    if not isinstance(extensions, list):
+        raise TypeError(
+            f"[tool.pgdevkit].extensions in {pyproject} must be a list, got {type(extensions).__name__}"
+        )
+
+    return ProjectConfig(
+        name=section.get("name") or root.name,
+        database_dir=section.get("database_dir", "database"),
+        env_prefix=section.get("env_prefix", ""),
+        extensions=tuple(extensions),
+        root=root,
+    )

pgdevkit/testdb/constants.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import os
+
+CONTAINER_NAME = "pgdevkit-postgres"
+IMAGE = "pgvector/pgvector:pg18-trixie"
+HOST = os.environ.get("PGDEVKIT_TESTDB_HOST", "localhost")
+PORT = int(os.environ.get("PGDEVKIT_TESTDB_PORT", "54322"))
+USER = os.environ.get("PGDEVKIT_TESTDB_USER", "postgres")
+PASSWORD = os.environ.get("PGDEVKIT_TESTDB_PASSWORD", "testpwd")
+PG_SPEED_FLAGS = ["-c", "fsync=off", "-c", "synchronous_commit=off", "-c", "full_page_writes=off"]

pgdevkit/testdb/container.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+
+import psycopg
+
+from . import constants
+
+
+def _podman(*args: str, check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(["podman", *args], capture_output=True, text=True, check=check)
+
+
+def _available(timeout: float = 3.0) -> bool:
+    """Quick check (short timeout) for whether Postgres is already reachable
+    at HOST:PORT, so a database started outside pgdevkit's control (or the
+    container from a previous run) doesn't trigger another podman/docker
+    lifecycle call."""
+    # libpq's connect_timeout is whole seconds; anything below 1 means "wait
+    # indefinitely" instead of a short timeout, so it's clamped up to 1.
+    connect_timeout = max(1, round(timeout))
+    dsn = (
+        f"postgresql://{constants.USER}:{constants.PASSWORD}"
+        f"@{constants.HOST}:{constants.PORT}/postgres?connect_timeout={connect_timeout}"
+    )
+    try:
+        with psycopg.connect(dsn):
+            return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _container_status() -> str | None:
+    """Return 'running', 'exited', etc., or None if the container doesn't exist."""
+    result = _podman(
+        "inspect", constants.CONTAINER_NAME, "--format", "{{.State.Status}}", check=False
+    )
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip()
+
+
+def _create_container() -> None:
+    result = _podman(
+        "run", "-d",
+        "--name", constants.CONTAINER_NAME,
+        "-p", f"{constants.PORT}:5432",
+        "-e", f"POSTGRES_USER={constants.USER}",
+        "-e", f"POSTGRES_PASSWORD={constants.PASSWORD}",
+        constants.IMAGE,
+        "postgres", *constants.PG_SPEED_FLAGS,
+        check=False,
+    )
+    if result.returncode != 0 and "already in use" in result.stderr:
+        _podman("start", constants.CONTAINER_NAME)
+        return
+    if result.returncode != 0:
+        raise RuntimeError(f"podman run failed: {result.stderr}")
+
+
+def _wait_ready(timeout: float = 30.0) -> None:
+    deadline = time.monotonic() + timeout
+    dsn = (
+        f"postgresql://{constants.USER}:{constants.PASSWORD}"
+        f"@{constants.HOST}:{constants.PORT}/postgres?connect_timeout=2"
+    )
+    last_error: Exception | None = None
+    while time.monotonic() < deadline:
+        try:
+            with psycopg.connect(dsn):
+                return
+        except Exception as e:  # noqa: BLE001
+            last_error = e
+            time.sleep(0.5)
+    raise RuntimeError(f"Postgres did not become ready within {timeout}s: {last_error}")
+
+
+def ensure_container() -> None:
+    """Idempotently ensure the shared pgdevkit-postgres container is running
+    and accepting connections. Never touches podman/docker if Postgres is
+    already reachable, or if PGDEVKIT_SKIP_CONTAINER says to assume it is."""
+    if os.environ.get("PGDEVKIT_SKIP_CONTAINER"):
+        return
+    if _available():
+        return
+    status = _container_status()
+    if status == "running":
+        return
+    if status is not None:
+        _podman("start", constants.CONTAINER_NAME)
+    else:
+        _create_container()
+    _wait_ready()