pgdevkit 0.7.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

pgdevkit/migrate.py

@@ -303,6 +303,14 @@ def record_applied(conninfo: str, tracking_table: str, filename: str) -> bool:
             return False
 
 
+def created_table_names(sql: str) -> list[str]:
+    """Table names any CREATE TABLE statement in this raw SQL script targets. Public
+    wrapper around the same detection `apply_migration` uses internally, for callers that
+    run a script directly (e.g. via `execute_sql_script`) instead of through a tracked
+    migration file, and still want to know what tables -- if any -- it created."""
+    return _created_table_names(_split_sql(sql))
+
+
 def verify_created_tables(conninfo: str, stmts: list[str]) -> list[str]:
     """Table names from this migration's CREATE TABLE statements that do NOT exist in the
     database. Empty means everything landed."""
@@ -318,6 +326,39 @@ def verify_created_tables(conninfo: str, stmts: list[str]) -> list[str]:
     return missing
 
 
+def missing_privileges(conninfo: str, role: str, tables: list[str], privilege: str = "select") -> list[str]:
+    """Table names from `tables` that `role` cannot currently exercise `privilege` on
+    (checked via Postgres's own `has_table_privilege`). Empty means the role can access
+    all of them. For guarding against the classic "migration creates a table, nobody
+    grants it to the app's runtime role" gap: check the tables a migration just created
+    against the role that will actually query them at runtime."""
+    if not tables:
+        return []
+    missing = []
+    with psycopg.connect(conninfo) as con:
+        for tbl in tables:
+            row = con.execute("select has_table_privilege(%s, %s, %s)", (role, tbl, privilege)).fetchone()
+            if not (row and row[0]):
+                missing.append(tbl)
+    return missing
+
+
+def _execute_stmts(conninfo: str, stmts: list[str]) -> None:
+    with psycopg.connect(conninfo) as con:
+        for stmt in stmts:
+            con.execute(cast(LiteralString, stmt))
+        con.commit()
+
+
+def execute_sql_script(conninfo: str, sql: str) -> None:
+    """Run a raw SQL script as one committed transaction, split into statements the same
+    statement-boundary-safe way apply_migration is (dollar-quoted blocks, string literals,
+    and line comments never get split mid-statement). Unlike apply_migration, this does
+    no tracking-table bookkeeping and isn't forward-only -- for scripts meant to re-run
+    every time, like an idempotent `GRANT ... ON ALL TABLES IN SCHEMA` privilege sync."""
+    _execute_stmts(conninfo, _split_sql(sql))
+
+
 @dataclass
 class ApplyResult:
     filename: str
@@ -337,11 +378,7 @@ def apply_migration(
     stmts = _split_sql(sql)
 
     if not already_done:
-        # DDL in its own committed transaction.
-        with psycopg.connect(conninfo) as con:
-            for stmt in stmts:
-                con.execute(cast(LiteralString, stmt))
-            con.commit()
+        _execute_stmts(conninfo, stmts)
 
     # Tracking insert is a separate connection/transaction so a missing tracking table
     # never rolls back the DDL that was just applied.

pgdevkit/testdb/_docker.py

@@ -39,3 +39,36 @@ def client() -> docker.DockerClient:
         "Could not reach a Docker-compatible API. Set DOCKER_HOST, or make sure "
         "Docker or Podman's API socket is running."
     )
+
+
+def _parse_tmpfs(spec: str) -> dict[str, str]:
+    """Parse a docker-CLI-style --tmpfs spec into the dict shape docker-py's
+    `containers.run(tmpfs=...)` expects. Multiple mounts are semicolon-separated
+    (commas are already used by docker's own comma-separated mount options),
+    e.g. "/path:rw,size=64m;/other/path:ro,size=32m", matching `docker run
+    --tmpfs /path:rw,size=64m --tmpfs /other/path:ro,size=32m`."""
+    mounts: dict[str, str] = {}
+    for entry in spec.split(";"):
+        entry = entry.strip()
+        if not entry:
+            continue
+        path, _, options = entry.partition(":")
+        mounts[path] = options
+    return mounts
+
+
+def resource_kwargs(*, tmpfs: str, shm_size: str, mem_limit: str, cpus: str) -> dict:
+    """Build the `containers.run()` kwargs for the tmpfs/shm_size/mem_limit/cpus
+    overrides, omitting any that aren't set so Docker's own defaults apply.
+    Shared by the Postgres and MSSQL container modules -- these are Docker-level
+    resource knobs, not anything specific to either engine."""
+    kwargs: dict = {}
+    if tmpfs:
+        kwargs["tmpfs"] = _parse_tmpfs(tmpfs)
+    if shm_size:
+        kwargs["shm_size"] = shm_size
+    if mem_limit:
+        kwargs["mem_limit"] = mem_limit
+    if cpus:
+        kwargs["nano_cpus"] = int(float(cpus) * 1_000_000_000)
+    return kwargs

pgdevkit/testdb/constants.py

@@ -5,11 +5,18 @@ import os
 from psycopg.conninfo import make_conninfo
 
 CONTAINER_NAME = "pgdevkit-postgres"
-IMAGE = "pgvector/pgvector:pg18-trixie"
+IMAGE = os.environ.get("PGDEVKIT_TESTDB_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")
+# Docker-level resource overrides, passed through to `containers.run()` --
+# unset (the default) means "let Docker/Podman use their own defaults".
+# TMPFS uses docker-CLI --tmpfs syntax; see _docker._parse_tmpfs().
+TMPFS = os.environ.get("PGDEVKIT_TESTDB_TMPFS", "")
+SHM_SIZE = os.environ.get("PGDEVKIT_TESTDB_SHM_SIZE", "")
+MEM_LIMIT = os.environ.get("PGDEVKIT_TESTDB_MEM_LIMIT", "")
+CPUS = os.environ.get("PGDEVKIT_TESTDB_CPUS", "")
 PG_SPEED_FLAGS = ["-c", "fsync=off", "-c", "synchronous_commit=off", "-c", "full_page_writes=off"]
 # Production connects with session timezone=UTC; the container image's own default
 # (baked into its base OS, not something pgdevkit ever set) can differ, silently

pgdevkit/testdb/container.py

@@ -7,7 +7,7 @@ import docker
 import docker.errors
 import psycopg
 
-from . import constants
+from . import _docker, constants
 from ._docker import client as _client
 
 
@@ -43,6 +43,12 @@ def _create_container(client: docker.DockerClient) -> None:
                 "PGTZ": "UTC",
             },
             command=["postgres", *constants.PG_STARTUP_FLAGS],
+            **_docker.resource_kwargs(
+                tmpfs=constants.TMPFS,
+                shm_size=constants.SHM_SIZE,
+                mem_limit=constants.MEM_LIMIT,
+                cpus=constants.CPUS,
+            ),
         )
     except docker.errors.APIError as e:
         if getattr(e, "status_code", None) == 409 or "already in use" in str(e):
@@ -79,6 +85,10 @@ def ensure_container() -> None:
     except docker.errors.NotFound:
         container = None
     if container is not None:
+        # An existing container (even stopped) is just restarted as-is --
+        # constants like TMPFS/SHM_SIZE/IMAGE/etc. only take effect via
+        # _create_container(), so changing them has no effect here until
+        # the stale container is removed. Documented in the README.
         if container.status != "running":
             container.start()
     else:

pgdevkit/testdb/mssql/constants.py

@@ -22,6 +22,15 @@ USER = os.environ.get("PGDEVKIT_TESTDB_MSSQL_USER", "sa")
 # default -- see validate_sa_password().
 PASSWORD = os.environ.get("PGDEVKIT_TESTDB_MSSQL_PASSWORD", "TestPwd!2026")
 MEMORY_LIMIT_MB = int(os.environ.get("PGDEVKIT_TESTDB_MSSQL_MEMORY_LIMIT_MB", "2048"))
+# Docker-level resource overrides, passed through to `containers.run()` --
+# unset (the default) means "let Docker/Podman use their own defaults". Distinct
+# from MEMORY_LIMIT_MB above, which only controls SQL Server's own internal memory
+# management, not the container's actual cgroup limit. TMPFS uses docker-CLI
+# --tmpfs syntax; see _docker._parse_tmpfs().
+TMPFS = os.environ.get("PGDEVKIT_TESTDB_MSSQL_TMPFS", "")
+SHM_SIZE = os.environ.get("PGDEVKIT_TESTDB_MSSQL_SHM_SIZE", "")
+MEM_LIMIT = os.environ.get("PGDEVKIT_TESTDB_MSSQL_MEM_LIMIT", "")
+CPUS = os.environ.get("PGDEVKIT_TESTDB_MSSQL_CPUS", "")
 
 
 def validate_sa_password(password: str) -> None:

pgdevkit/testdb/mssql/container.py

@@ -40,6 +40,12 @@ def _create_container(client: docker.DockerClient) -> None:
                 "MSSQL_PID": "Developer",
                 "MSSQL_MEMORY_LIMIT_MB": str(constants.MEMORY_LIMIT_MB),
             },
+            **_docker.resource_kwargs(
+                tmpfs=constants.TMPFS,
+                shm_size=constants.SHM_SIZE,
+                mem_limit=constants.MEM_LIMIT,
+                cpus=constants.CPUS,
+            ),
         )
     except docker.errors.APIError as e:
         if getattr(e, "status_code", None) == 409 or "already in use" in str(e):
@@ -83,6 +89,9 @@ def ensure_mssql_container() -> None:
     except docker.errors.NotFound:
         container = None
     if container is not None:
+        # See the Postgres container's ensure_container() -- an existing
+        # (even stopped) container is just restarted as-is, so config
+        # constants only take effect via _create_container().
         if container.status != "running":
             container.start()
     else:

{pgdevkit-0.7.2.dist-info → pgdevkit-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.7.2
+Version: 0.9.0
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -261,11 +261,25 @@ worktree and wants to know exactly which DB(s) go with it.
 
 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 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.
+`PGDEVKIT_TESTDB_USER`, `PGDEVKIT_TESTDB_PASSWORD`, and the image with
+`PGDEVKIT_TESTDB_IMAGE`. 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.
+
+Docker-level resource knobs are unset by default (Docker/Podman's own
+defaults apply) and can be overridden with `PGDEVKIT_TESTDB_SHM_SIZE` (e.g.
+`256m`, useful when Docker's 64MB default shared-memory size is too small
+for parallel query workers), `PGDEVKIT_TESTDB_MEM_LIMIT` (e.g. `1g`),
+`PGDEVKIT_TESTDB_CPUS` (e.g. `2` or `0.5`), and `PGDEVKIT_TESTDB_TMPFS` —
+docker-CLI `--tmpfs` syntax (`/path:options`), semicolon-separated for
+multiple mounts, e.g. `/var/lib/postgresql/data:size=512m`.
+
+All of the above (including `_HOST`/`_PORT`/`_USER`/`_PASSWORD`/`_IMAGE`)
+only take effect when pgdevkit actually creates the container, not when it
+finds and restarts an existing stopped one with the same name — remove the
+existing container (`docker rm -f pgdevkit-postgres`) first if you've
+changed any of these on a machine that already has one.
 
 Container management goes through the Docker API (the `docker` package,
 `docker.from_env()`, falling back to Podman's rootful/rootless socket) — it
@@ -291,6 +305,17 @@ Container defaults (`localhost:14330`, `sa`/a generated complexity-valid
 password) can be overridden with `PGDEVKIT_TESTDB_MSSQL_HOST`, `_PORT`,
 `_USER`, `_PASSWORD`, `_IMAGE`, `_MEMORY_LIMIT_MB`. The container only
 bootstraps the `sa` login — additional logins are a known limitation.
+
+The same Docker-level resource knobs as the Postgres container are
+available here too: `PGDEVKIT_TESTDB_MSSQL_SHM_SIZE`,
+`PGDEVKIT_TESTDB_MSSQL_MEM_LIMIT` (a container-level cgroup limit, distinct
+from `_MEMORY_LIMIT_MB` above which only tunes SQL Server's own internal
+memory management), `PGDEVKIT_TESTDB_MSSQL_CPUS`, and
+`PGDEVKIT_TESTDB_MSSQL_TMPFS`. As with the Postgres container, these only
+take effect when pgdevkit creates the container, not when restarting an
+existing stopped one (`docker rm -f pgdevkit-mssql` first if you've changed
+any of them).
+
 `pgdb testdb shell` execs into
 [`sqlcmd`](https://github.com/microsoft/go-sqlcmd) (an external prerequisite,
 the same category as `psql` for the Postgres path) rather than a Python

{pgdevkit-0.7.2.dist-info → pgdevkit-0.9.0.dist-info}/RECORD

@@ -8,7 +8,7 @@ pgdevkit/envtag.py,sha256=FdRqjLRdS9O9LSvoEzrRsFNeqiyZTLLzFgEkIirJyZI,2006
 pgdevkit/fetch_missing.py,sha256=vb8hXWBKMWgqkxHso5SuhX9l6rxNXfaybAEsajPLYow,8495
 pgdevkit/introspect.py,sha256=QYIlRuZk4lBHGxaW7zb_kFRIuNfi3AxH0Q2F_GKzlVI,7870
 pgdevkit/lakebase.py,sha256=0PABOk4p-2klLTY8QAUibQf9QeyNHKywUWEWGdkUY8k,3165
-pgdevkit/migrate.py,sha256=AnlxOy6Sk0iQlGq5lHYIaIBDwljO9EhCVwDkyRZmvQQ,13499
+pgdevkit/migrate.py,sha256=gyZLsioM-Kr8Qped2dqJykNUB3iGHp943vNN6tFZdeo,15380
 pgdevkit/models.py,sha256=dAZ8f7pgDsxoLVrDWsM4h0qwJ0pOzXDdWMGsnjrW80E,2103
 pgdevkit/mssql_introspect.py,sha256=Fhv1N4zHYEDZ0PEy0OIpawUmoIFeoi-Lm97pmEyDmYY,12031
 pgdevkit/parser.py,sha256=FmXL6-eCFzP_0FNyTrg4wF3aPzPeq7re2i0xvrSJIcs,16885
@@ -27,23 +27,23 @@ pgdevkit/db/model.py,sha256=ntuXonq-SCGkbNw-lvdMS5VuzLjxYRT8O6xaVqiw56I,980
 pgdevkit/db/mssql_crud.py,sha256=yN4izZ0fsFwAs14008JECHH4dqjNbdHUHGEG8kidyNs,11374
 pgdevkit/db/mssql_sql.py,sha256=DO3UMsTFN9pg0tNdaPGb0wf6lWlHGcqwqzkrGVhJF2g,2292
 pgdevkit/testdb/__init__.py,sha256=tphuORo4t0QHQp_gFi6ZHXXgd32w6qUoKlaQCab6izA,366
-pgdevkit/testdb/_docker.py,sha256=kj_0xrGO_mxHlK83ilsB-yE0ELX1kpH22ruYrS-N3iU,1467
+pgdevkit/testdb/_docker.py,sha256=-W59YBbcSIl9H_YmySRtVbOV4ImZPHOq9hxmlO-p56s,2807
 pgdevkit/testdb/api.py,sha256=13YgTz6hPcYWfsUlQJhJ7k20-W_4hzepedVaT8gWhxI,9709
 pgdevkit/testdb/config.py,sha256=NyeskDeThUgwOuxiMgHVnUOiHW-xVO9s2lJQoJcQwW4,2839
-pgdevkit/testdb/constants.py,sha256=oykc7xoX2R0ykhjXpqIdwkZoeHcScme8S2UPYvi_d_w,1718
-pgdevkit/testdb/container.py,sha256=PD2xUksIlAWXXus2VtAil_8UnwlG5DUcyUvbZx0eZTg,3123
+pgdevkit/testdb/constants.py,sha256=cvdj800WnkzpXC1FZP4tmDDwwoIgZpXo36XIJngjHR0,2194
+pgdevkit/testdb/container.py,sha256=_BYqs5IZmf_c5CsxLCzB1yLSSM6F0NWb1K6CujkfJ44,3641
 pgdevkit/testdb/naming.py,sha256=iHZVYdBQjHOD5sihgmZFe2qOC1djgBb6iP6R8wLUfL0,4377
 pgdevkit/testdb/query.py,sha256=iYpy_EoYIq5USfwr6pNktmDjcGi_yQx0vHvjHZNGRr0,3854
 pgdevkit/testdb/schema.py,sha256=XYBK3xyay98a5gzFW6SAQ336Jge-NhOQhildSQDOaf4,15101
 pgdevkit/testdb/mssql/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 pgdevkit/testdb/mssql/api.py,sha256=Ah95QTsOLvtubyHxRWDywjX9NCvTVgurmANLP5RY2Ck,8959
-pgdevkit/testdb/mssql/constants.py,sha256=7n_NcYuhabbtb18CqG_H_rRbI7Wb_qu_l4nKk3281vI,2847
-pgdevkit/testdb/mssql/container.py,sha256=_rG0AMDXrNwok_E60Xai0DZdRiZ6Ba1j3GaLUnSAueg,3364
+pgdevkit/testdb/mssql/constants.py,sha256=qyA1FCv-2LAQ_C8OydePEXhyG_ZBPPB7vg1686xVpVU,3453
+pgdevkit/testdb/mssql/container.py,sha256=sqJPAuhN1by3kZZ96gLet4pRt3uJmUMO6Kkmvjydg1w,3791
 pgdevkit/docs/database-layout.md,sha256=j9N8GuT63D2oVf9rIOEv8GTWs4yTtjZTGH-zM5Wrg5o,8163
 pgdevkit/skills/pgdevkit/SKILL.md,sha256=ADqEaQtMJPUUAiieqokzUUmIf27bWWJNB1ZvsfgiKAE,12205
 pgdevkit/skills/pgdevkit/references/dynamic-sql.md,sha256=aTR1sx81moiTwaMaiOecaqk-9rT8y5Zxz7W1BoC3vK0,2774
 pgdevkit/skills/pgdevkit/references/temporal-tables.md,sha256=LwZnItvQWI7bB0oRHxIfUc0ynnq7N0V5Mnv-QHvFN3Q,1364
-pgdevkit-0.7.2.dist-info/METADATA,sha256=6LQs_7tl-vQ-I8WnTSpl7uRIesuDropRBTL8fcE22GE,20367
-pgdevkit-0.7.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-pgdevkit-0.7.2.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
-pgdevkit-0.7.2.dist-info/RECORD,,
+pgdevkit-0.9.0.dist-info/METADATA,sha256=wmx2V7kjwyFEgTNZZhngSM8JnigCShnKc65XQIdhaa0,21824
+pgdevkit-0.9.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pgdevkit-0.9.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
+pgdevkit-0.9.0.dist-info/RECORD,,