pgdevkit 0.6.0__tar.gz → 0.6.2__tar.gz

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.6.0
+Version: 0.6.2
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/docs/database-layout.md

@@ -63,6 +63,17 @@ both together.
 One object per file: `tables/user.sql`, `views/all_edits.sql`,
 `types/measurement_unit.sql`.
 
+**`permissions` files always apply last, genuinely.** A blanket `GRANT ...
+ON ALL TABLES IN SCHEMA x TO role;` only covers what exists at the moment it
+runs — so if a table with a cross-file dependency that isn't resolved on the
+first pass (e.g. an FK to a table in another layer directory whose filename
+happens to sort later) got created *after* a `permissions` file, that grant
+would silently never cover it. `pgdb testdb` holds every `permissions` file
+back unconditionally and applies it only once the whole rest of the tree
+(delayed-retry resolution included) has actually finished — so write
+`permissions` files as if every table/view they reference is guaranteed to
+already exist, because it is.
+
 ---
 
 ## File-naming conventions

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/pgdevkit/testdb/constants.py

@@ -11,6 +11,13 @@ 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"]
+# 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
+# making any ::date cast of a timestamptz column disagree between test and prod for
+# rows near local midnight. Forcing UTC here -- both as the server's own timezone GUC
+# and as PGTZ/TZ for any client library that consults the environment instead -- keeps
+# test parity with prod instead of depending on the host/image's locale.
+PG_STARTUP_FLAGS = [*PG_SPEED_FLAGS, "-c", "timezone=UTC"]
 
 
 def conninfo(dbname: str, *, connect_timeout: int | None = None) -> str:

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/pgdevkit/testdb/container.py

@@ -36,8 +36,13 @@ def _create_container(client: docker.DockerClient) -> None:
             environment={
                 "POSTGRES_USER": constants.USER,
                 "POSTGRES_PASSWORD": constants.PASSWORD,
+                # Belt-and-suspenders alongside the server's own -c timezone=UTC below:
+                # some client libraries/tools inside the container consult TZ/PGTZ
+                # directly instead of asking Postgres for its configured timezone.
+                "TZ": "UTC",
+                "PGTZ": "UTC",
             },
-            command=["postgres", *constants.PG_SPEED_FLAGS],
+            command=["postgres", *constants.PG_STARTUP_FLAGS],
         )
     except docker.errors.APIError as e:
         if getattr(e, "status_code", None) == 409 or "already in use" in str(e):

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/pgdevkit/testdb/schema.py

@@ -132,6 +132,19 @@ def _iter_sql_files(
 ):
     """Yield (Path, sql_content) pairs in dependency-safe execution order.
 
+    Every `permissions`-type file (see `_TYPE_ORDER`) is held back
+    unconditionally and yielded only after every other file -- including
+    anything resolved via the delayed-retry loop below -- has actually been
+    delivered. A blanket "grant ... on all tables in schema X" has no real
+    per-object dependency of its own to track, but it still must apply
+    *after* every table/view it's meant to cover; a table whose own creation
+    got deferred to the retry loop (e.g. an FK to a same-type file that
+    happens to sort later) would otherwise silently miss that grant, since
+    a schema-wide GRANT is a one-time snapshot of whatever exists when it
+    runs. Nothing ever legitimately depends on a permissions file (it
+    creates no table/view/schema of its own), so holding every one back is
+    always safe.
+
     A file tagged for another environment (see pgdevkit.envtag) is dropped
     during the initial file walk, before dependency ordering even sees it.
 
@@ -154,6 +167,7 @@ def _iter_sql_files(
     delivered: set[str] = set()
     delayed: list[tuple[str | None, Path, str]] = []
     all_declared: set[str] = set()
+    permissions_files: list[tuple[Path, str]] = []
 
     for file in sorted(files, key=lambda p: (_get_type_order(p), p.name)):
         content = file.read_text(encoding="utf-8")
@@ -163,6 +177,9 @@ def _iter_sql_files(
             sql_schemas(content, dialect), only=schemas, exclude=exclude_schemas
         ):
             continue
+        if _get_type_order(file) == _TYPE_ORDER["permissions"]:
+            permissions_files.append((file, content))
+            continue
         deps = _get_sql_deps(content, dialect)
         if file.parent.name in _SCHEMA_QUALIFIED_TYPES:
             schema = _strip_layer_prefix(file.parent.parent.name)
@@ -196,6 +213,8 @@ def _iter_sql_files(
         if not progressed:
             raise ValueError(f"Circular or missing SQL dependencies: {[f[1] for f in delayed]}")
 
+    yield from permissions_files
+
 
 async def _insert_test_data(
     json_file: Path,
@@ -276,6 +295,10 @@ async def apply_schema(
     """Apply every .sql file under database_dir (in dependency-safe order)
     and seed any matching .test_data.json files. Safe to call repeatedly.
 
+    Every `permissions`-type file (see `_TYPE_ORDER`) is guaranteed to apply
+    after every table/view it's meant to cover, including anything resolved
+    via delayed-retry -- see `_iter_sql_files()`'s docstring.
+
     A file tagged for another environment (e.g. `grants.prod.sql` when
     `env="local_test"`) is skipped — see pgdevkit.envtag.
 

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/pyproject.toml

@@ -11,7 +11,7 @@ packages = ["pgdevkit"]
 
 [project]
 name = "pgdevkit"
-version = "0.6.0"
+version = "0.6.2"
 description = "A helper for developing with Postgres"
 readme = "README.md"
 requires-python = ">=3.14"

pgdevkit-0.6.2/tests/testdb/fixtures/database/app/tables/event.sql

@@ -0,0 +1,10 @@
+-- Filename ("event.sql") deliberately sorts alphabetically before its own FK
+-- target's filename ("event_kind.sql") -- '.' (0x2E) sorts before '_' (0x5F) --
+-- so this file's first apply attempt always fails (app.event_kind doesn't
+-- exist yet) and it only actually gets created via _iter_sql_files()'s
+-- delayed-retry pass, which runs after every non-delayed file has already
+-- been attempted. See test_apply_schema_applies_permissions_after_a_delayed_table.
+CREATE TABLE IF NOT EXISTS app.event (
+    id serial PRIMARY KEY,
+    event_kind_id int NOT NULL REFERENCES app.event_kind(id)
+);

pgdevkit-0.6.2/tests/testdb/fixtures/database/app/tables/event_kind.sql

@@ -0,0 +1,4 @@
+CREATE TABLE IF NOT EXISTS app.event_kind (
+    id serial PRIMARY KEY,
+    name text NOT NULL
+);

pgdevkit-0.6.2/tests/testdb/fixtures/database/permissions/grants.sql

@@ -0,0 +1,18 @@
+-- Roles are cluster-wide, not per-database, so this can race against another
+-- pytest process (e.g. a second worktree) hitting the same shared testdb
+-- container concurrently -- both can pass the IF NOT EXISTS check before
+-- either commits. Catching duplicate_object (mirroring _ensure_database()'s
+-- own DuplicateDatabase guard in pgdevkit/testdb/api.py) is race-safe in a
+-- way "IF NOT EXISTS (SELECT ...) THEN CREATE" is not, since it lets
+-- Postgres's own uniqueness check -- not a separate lookup -- be the source
+-- of truth.
+DO $$
+BEGIN
+    CREATE ROLE pgdevkit_test_reader LOGIN PASSWORD 'testpwd';
+EXCEPTION WHEN duplicate_object THEN
+    NULL;
+END
+$$;
+
+GRANT USAGE ON SCHEMA app TO pgdevkit_test_reader;
+GRANT SELECT ON ALL TABLES IN SCHEMA app TO pgdevkit_test_reader;

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/tests/testdb/test_container.py

@@ -49,6 +49,36 @@ def test_ensure_container_skips_everything_when_skip_env_set(monkeypatch):
     ensure_container()  # must return without checking availability or calling the Docker API
 
 
+class _FakeContainers:
+    def __init__(self):
+        self.run_kwargs: dict | None = None
+
+    def run(self, image, **kwargs):
+        self.run_kwargs = kwargs
+
+
+class _FakeClient:
+    def __init__(self):
+        self.containers = _FakeContainers()
+
+
+def test_create_container_forces_utc_timezone():
+    """Test Postgres must run with timezone=UTC regardless of the container
+    image's/host's own locale default -- production connects with session
+    timezone=UTC, so any ::date cast of a timestamptz column would otherwise
+    silently disagree between test and prod for rows near local midnight."""
+    client = _FakeClient()
+
+    _create_container(client)
+
+    assert client.containers.run_kwargs is not None
+    assert "-c" in client.containers.run_kwargs["command"]
+    timezone_flag_index = client.containers.run_kwargs["command"].index("timezone=UTC")
+    assert client.containers.run_kwargs["command"][timezone_flag_index - 1] == "-c"
+    assert client.containers.run_kwargs["environment"]["TZ"] == "UTC"
+    assert client.containers.run_kwargs["environment"]["PGTZ"] == "UTC"
+
+
 def _admin_dsn() -> str:
     return constants.conninfo("postgres", connect_timeout=5)
 
@@ -84,3 +114,13 @@ def test_create_container_falls_back_to_start_when_name_in_use():
         with con.cursor() as cur:
             cur.execute("SELECT 1")
             assert cur.fetchone() == (1,)
+
+
+@requires_podman
+def test_ensure_container_runs_with_utc_timezone():
+    ensure_container()
+
+    with psycopg.connect(_admin_dsn()) as con:
+        with con.cursor() as cur:
+            cur.execute("SHOW timezone")
+            assert cur.fetchone() == ("UTC",)

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/tests/testdb/test_schema.py

@@ -4,6 +4,7 @@ from pathlib import Path
 
 import psycopg
 import pytest
+from psycopg.conninfo import make_conninfo
 
 from pgdevkit.testdb import constants
 from pgdevkit.testdb.container import ensure_container
@@ -97,6 +98,33 @@ async def test_apply_schema_resolves_view_to_view_dependency(schema_test_db):
     assert rows == [(1, "sprocket")]
 
 
+@requires_podman
+async def test_apply_schema_applies_permissions_after_a_delayed_table(schema_test_db):
+    # permissions/grants.sql (a blanket "grant select on all tables in schema app")
+    # has no SQL dependencies of its own -- app.event, whose own filename
+    # ("event.sql") sorts alphabetically before its FK target's filename
+    # ("event_kind.sql"), always falls to the delayed-retry pass instead of
+    # resolving on the first attempt. Without holding permissions files back
+    # unconditionally, a blanket GRANT (a one-time snapshot of whatever exists
+    # when it runs) would apply before app.event exists and never cover it.
+    # Confirms _iter_sql_files() always yields permissions-type files last,
+    # genuinely after the whole tree (delayed retries included) has converged.
+    async with await psycopg.AsyncConnection.connect(_db_dsn(), autocommit=True) as con:
+        await apply_schema(con, FIXTURES)  # must not raise
+
+    # permissions/grants.sql creates this login role itself -- a fixed,
+    # non-secret password, matching pgdevkit's own testdb container convention.
+    reader_dsn = make_conninfo(
+        host=constants.HOST, port=str(constants.PORT), dbname=TEST_DB,
+        user="pgdevkit_test_reader", password="testpwd",
+    )
+    async with await psycopg.AsyncConnection.connect(reader_dsn, autocommit=True) as con:
+        async with con.cursor() as cur:
+            await cur.execute("SELECT count(*) FROM app.event")  # must not raise InsufficientPrivilege
+            (count,) = await cur.fetchone()
+    assert count == 0
+
+
 @requires_podman
 async def test_apply_schema_seeds_composite_enum_and_jsonb_columns(schema_test_db):
     # gadget.mood is an enum, gadget.size a composite type, gadget.tags

{pgdevkit-0.6.0 → pgdevkit-0.6.2}/uv.lock

@@ -313,7 +313,7 @@ wheels = [
 
 [[package]]
 name = "pgdevkit"
-version = "0.6.0"
+version = "0.6.2"
 source = { editable = "." }
 dependencies = [
     { name = "docker" },