pgdevkit 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

pgdevkit/skills/pgdevkit/SKILL.md

@@ -73,7 +73,9 @@ def _testdb_env():
         os.environ[key] = value
 ```
 
-`ensure_testdb()` starts the shared `pgdevkit-postgres` container if needed (via `podman`), creates a database scoped to this project+branch (so different worktrees/branches never collide), and applies every `.sql` file under `database_dir` in dependency order, seeding any `.test_data.json` sidecar files.
+`ensure_testdb()` starts the shared `pgdevkit-postgres` container if needed (via the Docker API — works against a real Docker daemon or Podman's socket, no CLI binary required), creates a database scoped to this project+branch (so different worktrees/branches never collide), and applies every `.sql` file under `database_dir` in dependency order, seeding any `.test_data.json` sidecar files.
+
+**`migrations/` is never applied here, on purpose.** If the test schema is missing something, that's a sign the base `tables/`/`views`/... file has drifted behind a migration that was only ever run manually against a real database — fix the base file, don't add migration-replay to `apply_schema()` (tried once, reverted: a migration can't be judged "safe to re-run" from its SQL text alone — see `docs/database-layout.md`'s Migrations section).
 
 | What do you need? | Command |
 |---|---|
@@ -86,7 +88,7 @@ def _testdb_env():
 
 ### CI
 
-Podman needs to be available on the runner (`apt-get install -y podman` on `ubuntu-latest` if not preinstalled) — `ensure_testdb()`/`ensure_container()` shell out to it directly. There's no `PGDEVKIT_SKIP_CONTAINER` + service-container escape hatch wired through every fixture yet — if a project's CI can't run podman, it needs its own workaround for now.
+`ensure_testdb()`/`ensure_container()` talk to whatever Docker-compatible API is reachable (`DOCKER_HOST`, the default Docker socket, or Podman's socket as a fallback) — `ubuntu-latest`'s preinstalled Docker daemon just works, no setup step needed. There's no `PGDEVKIT_SKIP_CONTAINER` + service-container escape hatch wired through every fixture yet — if a project's CI has neither Docker nor Podman reachable, it needs its own workaround for now.
 
 ---
 

pgdevkit/testdb/container.py

@@ -1,23 +1,53 @@
 from __future__ import annotations
 
 import os
-import subprocess
 import time
 
+import docker
+import docker.errors
 import psycopg
 
 from . import constants
 
+# Candidate Docker-API-compatible socket URLs tried after plain
+# docker.from_env() (which only looks at DOCKER_HOST / the default Docker
+# socket) fails to connect -- covers rootful and rootless Podman, which
+# speaks the same API but doesn't always advertise itself via DOCKER_HOST.
+_FALLBACK_SOCKET_URLS = [
+    f"unix://{os.environ['XDG_RUNTIME_DIR']}/podman/podman.sock" if os.environ.get("XDG_RUNTIME_DIR") else None,
+    "unix:///run/podman/podman.sock",
+]
 
-def _podman(*args: str, check: bool = True) -> subprocess.CompletedProcess:
-    return subprocess.run(["podman", *args], capture_output=True, text=True, check=check)
+
+def _client() -> docker.DockerClient:
+    """A Docker-API client, working against a real Docker daemon or a
+    Podman one (Podman exposes the same API over its own socket) -- callers
+    never need to know or care which one is actually running."""
+    try:
+        client = docker.from_env()
+        client.ping()
+        return client
+    except Exception:  # noqa: BLE001
+        pass
+    for base_url in _FALLBACK_SOCKET_URLS:
+        if base_url is None:
+            continue
+        try:
+            client = docker.DockerClient(base_url=base_url)
+            client.ping()
+            return client
+        except Exception:  # noqa: BLE001
+            continue
+    raise RuntimeError(
+        "Could not reach a Docker-compatible API. Set DOCKER_HOST, or make sure "
+        "Docker or Podman's API socket is running."
+    )
 
 
 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."""
+    container from a previous run) doesn't trigger another Docker API 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))
@@ -29,32 +59,24 @@ def _available(timeout: float = 3.0) -> bool:
         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 _create_container(client: docker.DockerClient) -> None:
+    try:
+        client.containers.run(
+            constants.IMAGE,
+            name=constants.CONTAINER_NAME,
+            detach=True,
+            ports={"5432/tcp": constants.PORT},
+            environment={
+                "POSTGRES_USER": constants.USER,
+                "POSTGRES_PASSWORD": constants.PASSWORD,
+            },
+            command=["postgres", *constants.PG_SPEED_FLAGS],
+        )
+    except docker.errors.APIError as e:
+        if getattr(e, "status_code", None) == 409 or "already in use" in str(e):
+            client.containers.get(constants.CONTAINER_NAME).start()
+            return
+        raise RuntimeError(f"Starting the {constants.CONTAINER_NAME} container failed: {e}") from e
 
 
 def _wait_ready(timeout: float = 30.0) -> None:
@@ -73,17 +95,20 @@ def _wait_ready(timeout: float = 30.0) -> None:
 
 def ensure_container() -> None:
     """Idempotently ensure the shared pgdevkit-postgres container is running
-    and accepting connections. Never touches podman/docker if Postgres is
+    and accepting connections. Never touches the Docker API 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)
+    client = _client()
+    try:
+        container = client.containers.get(constants.CONTAINER_NAME)
+    except docker.errors.NotFound:
+        container = None
+    if container is not None:
+        if container.status != "running":
+            container.start()
     else:
-        _create_container()
+        _create_container(client)
     _wait_ready()

pgdevkit/testdb/schema.py

@@ -63,8 +63,31 @@ _SCHEMA_QUALIFIED_TYPES = {
 }
 
 
+_DECLARE_RE = re.compile(
+    r"CREATE\s+(?:OR\s+REPLACE\s+)?(?:TABLE|VIEW|FUNCTION|PROCEDURE|TYPE|SCHEMA)\s+(\w+\.\w+)", re.IGNORECASE
+)
+_DEPEND_RE = re.compile(r"(?:FROM|JOIN|INTO|UPDATE|TABLE|ON)\s+(\w+\.\w+)", re.IGNORECASE)
+
+
+def _get_sql_deps_regex_fallback(sql: str) -> set[str]:
+    """Crude regex scan used when sqlglot can't parse a statement even with
+    error_level=IGNORE. This only feeds dependency *ordering* (which file to
+    apply first), not execution, so an imprecise-but-safe approximation here
+    is fine."""
+    declares = set(_DECLARE_RE.findall(sql))
+    deps = set(_DEPEND_RE.findall(sql))
+    return deps - declares
+
+
 def _get_sql_deps(sql: str) -> set[str]:
-    exprs = sqlglot.parse(sql, dialect="postgres")
+    try:
+        # error_level=IGNORE lets sqlglot recover from statements it can't
+        # fully parse (e.g. a schema-qualified `DROP TRIGGER ... ON
+        # schema.table`) and keep going, instead of raising and losing every
+        # other statement's dependency info in the same file.
+        exprs = sqlglot.parse(sql, dialect="postgres", error_level=sqlglot.ErrorLevel.IGNORE)
+    except Exception:  # noqa: BLE001
+        return _get_sql_deps_regex_fallback(sql)
     deps: set[str] = set()
     for e in exprs:
         if e is None:
@@ -172,54 +195,19 @@ async def _insert_test_data(
         await cur.executemany(insert_sql, rows)
 
 
-_UNSAFE_MIGRATION_PATTERNS = (
-    "DROP COLUMN",
-    "DROP TABLE",
-    "TRUNCATE",
-    "RENAME COLUMN",
-    "RENAME TO",
-    "DELETE FROM",
-    "OWNER TO",
-)
-
-
-def _is_additive_migration(sql: str) -> bool:
-    """Only pure-additive migrations (ADD COLUMN/CREATE ... IF NOT EXISTS,
-    etc.) are safe to (re-)apply against a schema that already reflects
-    later migrations — skip anything that could drop, rename, truncate, or
-    delete existing structure/data, alter an existing column, or change
-    ownership. This is a substring heuristic, not a SQL parser, so it errs
-    towards skipping (a false negative here means real data loss replayed
-    on every apply_schema() call) rather than trying to be exhaustive."""
-    normalized = sql.upper()
-    has_alter_column = "ALTER COLUMN" in normalized and "ADD COLUMN" not in normalized
-    has_unsafe_pattern = any(pattern in normalized for pattern in _UNSAFE_MIGRATION_PATTERNS)
-    return not (has_alter_column or has_unsafe_pattern)
-
-
-def _iter_migration_files(database_dir: Path):
-    """Yield every `*.sql` file in any `migrations/` subdirectory, in
-    filename order (the project's naming convention — numeric or date
-    prefixes — sorts chronologically)."""
-    for root, _, files in os.walk(database_dir):
-        if Path(root).name != "migrations":
-            continue
-        for file in sorted(files):
-            if file.endswith(".sql"):
-                yield Path(root) / file
-
-
 async def apply_schema(
     con: psycopg.AsyncConnection,
     database_dir: Path,
     extensions: tuple[str, ...] = (),
     force_reset: bool = False,
 ) -> None:
-    """Apply every .sql file under database_dir (in dependency-safe order),
-    seed any matching .test_data.json files, then apply purely-additive
-    `migrations/*.sql` files (see `_is_additive_migration`) so a schema that
-    ships changes via migration files rather than editing the base object
-    files stays in sync. Safe to call repeatedly."""
+    """Apply every .sql file under database_dir (in dependency-safe order)
+    and seed any matching .test_data.json files. Safe to call repeatedly.
+
+    `migrations/` subdirectories are never applied here — they're for
+    one-time manual application against real (already-provisioned)
+    databases, not for building a fresh schema. The base object files under
+    `database_dir` must reflect the current, final schema on their own."""
     await con.set_autocommit(True)
     for extension in extensions:
         await con.execute(SQL("CREATE EXTENSION IF NOT EXISTS {e}").format(e=Identifier(extension)))
@@ -241,15 +229,21 @@ async def apply_schema(
             logger.warning("Error executing %s (will retry): %s", file, e)
             failures.append((file, sql))
 
-    for file, sql in failures:
-        await _apply(file, sql)
-
-    for migration_file in _iter_migration_files(database_dir):
-        content = migration_file.read_text(encoding="utf-8")
-        if not _is_additive_migration(content):
-            continue
-        try:
-            await con.execute(cast(Any, content))
-            logger.info("Applied migration %s", migration_file.name)
-        except Exception as e:  # noqa: BLE001
-            logger.debug("Migration %s skipped (likely already applied): %s", migration_file.name, e)
+    # Retry the whole failed set, not just once: a single extra pass in
+    # original order can still raise on an item whose dependency is later
+    # in the same list and hasn't had its own retry yet. Every CREATE here
+    # is idempotent, so looping until a full pass makes no progress
+    # converges on any resolvable ordering without re-doing finished work.
+    while failures:
+        still_failing: list[tuple[Path, str]] = []
+        last_error: Exception | None = None
+        for file, sql in failures:
+            try:
+                await _apply(file, sql)
+            except Exception as e:  # noqa: BLE001
+                still_failing.append((file, sql))
+                last_error = e
+        if len(still_failing) == len(failures):
+            assert last_error is not None
+            raise last_error
+        failures = still_failing

{pgdevkit-0.2.0.dist-info → pgdevkit-0.2.2.dist-info}/METADATA

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: pgdevkit
-Version: 0.2.0
+Version: 0.2.2
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
+Requires-Dist: docker>=7.1.0
 Requires-Dist: psycopg[binary]>=3.2.0
-Requires-Dist: sqlglot[c]>=30.11.0
+Requires-Dist: sqlglot>=30.11.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.19.0; extra == 'azure'
 Provides-Extra: cli
@@ -87,15 +88,20 @@ CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`.
 
 Container connection defaults (`localhost:54322`, `postgres`/`testpwd`) can
 be overridden with `PGDEVKIT_TESTDB_HOST`, `PGDEVKIT_TESTDB_PORT`,
-`PGDEVKIT_TESTDB_USER`, `PGDEVKIT_TESTDB_PASSWORD`. Before touching
-podman/docker, pgdevkit first checks (with a short timeout) whether Postgres
+`PGDEVKIT_TESTDB_USER`, `PGDEVKIT_TESTDB_PASSWORD`. Before touching the
+Docker API, pgdevkit first checks (with a short timeout) whether Postgres
 is already reachable at that address and skips container management if so.
 Set `PGDEVKIT_SKIP_CONTAINER=1` to always assume it's already there and skip
 that check too.
 
-To point at a local Postgres install instead of the podman container —
-useful when podman isn't available, or you'd rather use peer authentication
-as the current OS user — set `PGDEVKIT_TESTDB_HOST` to the unix socket
+Container management goes through the Docker API (the `docker` package,
+`docker.from_env()`, falling back to Podman's rootful/rootless socket) — it
+works against a real Docker daemon or Podman transparently, no CLI binary
+required either way.
+
+To point at a local Postgres install instead of the container — useful when
+neither is available, or you'd rather use peer authentication as the
+current OS user — set `PGDEVKIT_TESTDB_HOST` to the unix socket
 directory (e.g. `/var/run/postgresql`) and `PGDEVKIT_TESTDB_PASSWORD=""`.
 The role named by `PGDEVKIT_TESTDB_USER` must exist and match your OS user
 (`CREATE ROLE <user> SUPERUSER LOGIN;`) and `pg_hba.conf` must allow `peer`

{pgdevkit-0.2.0.dist-info → pgdevkit-0.2.2.dist-info}/RECORD

@@ -17,15 +17,15 @@ pgdevkit/testdb/__init__.py,sha256=-APwuluorU3iRCUsiJPK7Bc1AS5_IXxCdKB4zuaQ868,1
 pgdevkit/testdb/api.py,sha256=eNbkxDfWrIzsGs7YZGV9gJaX6hrrnIMqulkbRam0VXc,4796
 pgdevkit/testdb/config.py,sha256=v0KFSkWhhZ8vy9167nqHqPsuCjilVrIQ6iqo8m_9-Hk,1545
 pgdevkit/testdb/constants.py,sha256=xi8uIoEgN9LrRkr41j3mmWB9PqqU0r8aCUb2JJXBAs0,1165
-pgdevkit/testdb/container.py,sha256=24zl2_0mX24RTa2NCxps8RlJQAzdAif15TWgoVjNtMc,2974
+pgdevkit/testdb/container.py,sha256=R_IhazRw_c0HteDtESO6RY6XWHp995FP5RRA4LK7Fh0,4068
 pgdevkit/testdb/naming.py,sha256=Kyk5qEfxUkbggUG5bD7U7CJ_kAET332VPQNB-O5kvTY,1318
 pgdevkit/testdb/query.py,sha256=e4UbgdCKKIot3a8Qixg-OX-Af0rlQ4a8ODhJBD8mtVM,2318
-pgdevkit/testdb/schema.py,sha256=99Wnl2JAD_kd5226uCAAHEcd_fl23D-kNYmt16asRgM,9573
+pgdevkit/testdb/schema.py,sha256=-whDO8JTggFPNZtymzQ7dpsqMdQ-wUYAlRdWuyT4CAQ,9590
 pgdevkit/docs/database-layout.md,sha256=dNvDH956xSXuAnLqkOopyOfaIm_A-RtUd57VTaZ1GQU,6035
-pgdevkit/skills/pgdevkit/SKILL.md,sha256=anvsNNeC1-ixUk70L9owyQlQtN6_wUhykOGqU3mAboY,11524
+pgdevkit/skills/pgdevkit/SKILL.md,sha256=6uxe6BQwOLexGiBpf00VTFTHOiWJo5k2Qqzu172rb4I,12156
 pgdevkit/skills/pgdevkit/references/dynamic-sql.md,sha256=aTR1sx81moiTwaMaiOecaqk-9rT8y5Zxz7W1BoC3vK0,2774
 pgdevkit/skills/pgdevkit/references/temporal-tables.md,sha256=LwZnItvQWI7bB0oRHxIfUc0ynnq7N0V5Mnv-QHvFN3Q,1364
-pgdevkit-0.2.0.dist-info/METADATA,sha256=1KBvcghDMMHNmZ-IOBKawFnsdDiD2797b4dQZwX2mlg,5651
-pgdevkit-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-pgdevkit-0.2.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
-pgdevkit-0.2.0.dist-info/RECORD,,
+pgdevkit-0.2.2.dist-info/METADATA,sha256=56tCcCKLAnudYqguZtBn60RMnmGmKt-sk0yeFEG-y8c,5915
+pgdevkit-0.2.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pgdevkit-0.2.2.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
+pgdevkit-0.2.2.dist-info/RECORD,,