pgdevkit 0.5.0__tar.gz → 0.6.1__tar.gz

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.5.0
+Version: 0.6.1
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -167,6 +167,32 @@ semantics. `pgdevkit.migrate.list_migration_files`/`pending_migrations` and
 `pgdevkit.fetch_missing.find_missing_objects` takes neither, for the reason
 above.
 
+## Environment-tagged files (`<name>.<env>.sql`)
+
+A file whose name ends `.<env>.sql` (e.g. `grants.prod.sql`,
+`seed.staging.sql`) is only in scope when targeting that environment; a
+plain `<name>.sql` file is untagged and always in scope, regardless of
+environment. `.init.sql` (see `docs/database-layout.md`) is reserved and is
+never treated as an environment tag.
+
+- `pgdb testdb up`/`pgdb testdb reset` accept `--env` (default
+  `local_test`) — so an untagged `grants.sql` always applies, but
+  `grants.prod.sql` is skipped unless run with `--env prod`.
+- `pgdb migrate check`/`pgdb migrate apply` accept `--env` too, but it's
+  optional with **no** default: omit it and every file is a candidate
+  regardless of its tag (unchanged, today's behavior); pass it to restrict
+  to files tagged for that environment plus untagged ones.
+
+```bash
+pgdb testdb up --env prod   # apply prod-tagged files too, against the local test container
+pgdb migrate apply path/to/database/_migration_scripts --url ... --env prod
+```
+
+`pgdevkit.envtag` exposes the same logic for scripting: `file_env` reads a
+file's tag, `env_allowed` applies the filtering semantics above, and
+`strip_env_suffix` returns a tagged file's logical name (e.g.
+`grants.prod.sql` -> `"grants"`).
+
 ## `pgdb testdb`
 
 Manages a single shared, Podman-backed Postgres container for local tests
@@ -195,7 +221,8 @@ def ensure_test_postgres():
         os.environ[k] = v
 ```
 
-CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`.
+CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`. `up`/`reset` accept
+`--env` (default `local_test`) — see "Environment-tagged files" above.
 
 `up`/`reset` accept `--area`/`--exclude-area` and `--schema`/`--exclude-schema`
 (see "Area and schema filtering" above) to scope which `database/` files get

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/README.md

@@ -146,6 +146,32 @@ semantics. `pgdevkit.migrate.list_migration_files`/`pending_migrations` and
 `pgdevkit.fetch_missing.find_missing_objects` takes neither, for the reason
 above.
 
+## Environment-tagged files (`<name>.<env>.sql`)
+
+A file whose name ends `.<env>.sql` (e.g. `grants.prod.sql`,
+`seed.staging.sql`) is only in scope when targeting that environment; a
+plain `<name>.sql` file is untagged and always in scope, regardless of
+environment. `.init.sql` (see `docs/database-layout.md`) is reserved and is
+never treated as an environment tag.
+
+- `pgdb testdb up`/`pgdb testdb reset` accept `--env` (default
+  `local_test`) — so an untagged `grants.sql` always applies, but
+  `grants.prod.sql` is skipped unless run with `--env prod`.
+- `pgdb migrate check`/`pgdb migrate apply` accept `--env` too, but it's
+  optional with **no** default: omit it and every file is a candidate
+  regardless of its tag (unchanged, today's behavior); pass it to restrict
+  to files tagged for that environment plus untagged ones.
+
+```bash
+pgdb testdb up --env prod   # apply prod-tagged files too, against the local test container
+pgdb migrate apply path/to/database/_migration_scripts --url ... --env prod
+```
+
+`pgdevkit.envtag` exposes the same logic for scripting: `file_env` reads a
+file's tag, `env_allowed` applies the filtering semantics above, and
+`strip_env_suffix` returns a tagged file's logical name (e.g.
+`grants.prod.sql` -> `"grants"`).
+
 ## `pgdb testdb`
 
 Manages a single shared, Podman-backed Postgres container for local tests
@@ -174,7 +200,8 @@ def ensure_test_postgres():
         os.environ[k] = v
 ```
 
-CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`.
+CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`. `up`/`reset` accept
+`--env` (default `local_test`) — see "Environment-tagged files" above.
 
 `up`/`reset` accept `--area`/`--exclude-area` and `--schema`/`--exclude-schema`
 (see "Area and schema filtering" above) to scope which `database/` files get

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/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
@@ -71,10 +82,18 @@ One object per file: `tables/user.sql`, `views/all_edits.sql`,
 |---|---|
 | `<name>.sql` | The object's live definition (`CREATE TABLE`, `CREATE OR REPLACE VIEW`, ...) |
 | `<name>.test_data.json` | Seed rows for a table — a JSON array of row objects, loaded after the table is created |
-| `<name>.init.sql` | One-time setup for an object (e.g. a backfill), run once, kept separate from the reusable definition |
-| `<name>.prod.sql` / `.prod` anywhere in the name | Production-only (real permission grants, real user accounts) — skipped by `pgdb testdb` |
+| `<name>.init.sql` | One-time setup for an object (e.g. a backfill), run once, kept separate from the reusable definition — `init` is reserved and is never treated as an environment tag |
+| `<name>.<env>.sql` | Only applied when targeting environment `<env>` (any name you like — `prod`, `staging`, ...); a file with no such suffix is untagged and always applies, regardless of environment |
 | `all.sql` | Generated concatenation of the whole tree — not hand-edited, not committed |
 
+`pgdb testdb up`/`pgdb testdb reset` apply the `--env` they're given (default
+`local_test`) — so an untagged `grants.sql` always applies, but
+`grants.prod.sql` is skipped unless you pass `--env prod`. `pgdb migrate
+check`/`pgdb migrate apply` accept the same `--env`, but it's optional with no
+default: omit it and every file is a candidate regardless of its tag (today's
+behavior); pass it to restrict to files tagged for that environment plus
+untagged ones.
+
 ---
 
 ## Migrations
@@ -156,5 +175,5 @@ leading sort number.
 - [ ] Object-type folder (`tables`, `views`, ...) matches the apply-order table above — that's what governs ordering, not the layer's leading number
 - [ ] One-off changes go in `migrations/`, dated, never edited after applying
 - [ ] The live `.sql` file is updated in the same change as any migration touching that object
-- [ ] `.prod` files are production-only and skipped by `pgdb testdb`
+- [ ] `.<env>.sql` files (e.g. `.prod.sql`) are skipped by `pgdb testdb` unless it's run with a matching `--env`
 - [ ] Every table (and non-obvious column) has a `COMMENT ON`, placed in the object's own `.sql` file

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pgdevkit/cli.py

@@ -41,6 +41,17 @@ _EXCLUDE_SCHEMA_OPTION = typer.Option(
     help="Skip files referencing this DB schema (repeatable); "
     "files with no detectable schema reference are never excluded",
 )
+_TESTDB_ENV_OPTION = typer.Option(
+    "local_test",
+    "--env",
+    help="Environment to apply: skips any <name>.<other-env>.sql file (e.g. grants.prod.sql); untagged files always apply",
+)
+_MIGRATE_ENV_OPTION = typer.Option(
+    None,
+    "--env",
+    help="Restrict to files tagged for this environment (e.g. <name>.prod.sql); untagged files always apply; "
+    "omit to apply every file regardless of its env tag",
+)
 
 
 def _as_set(values: list[str]) -> frozenset[str] | None:
@@ -209,6 +220,7 @@ def fetch_missing(
 
 @testdb_app.command("up")
 def testdb_up(
+    env: str = _TESTDB_ENV_OPTION,
     area: list[str] = _AREA_OPTION,
     exclude_area: list[str] = _EXCLUDE_AREA_OPTION,
     schema: list[str] = _SCHEMA_OPTION,
@@ -216,7 +228,7 @@ def testdb_up(
 ) -> None:
     """Ensure the container is running, the workspace DB exists, and schema is applied."""
     testdb.ensure_testdb(
-        areas=_as_set(area), exclude_areas=_as_set(exclude_area), schemas=_as_set(schema),
+        env=env, areas=_as_set(area), exclude_areas=_as_set(exclude_area), schemas=_as_set(schema),
         exclude_schemas=_as_set(exclude_schema),
     )
     info = testdb.status()
@@ -225,6 +237,7 @@ def testdb_up(
 
 @testdb_app.command("reset")
 def testdb_reset(
+    env: str = _TESTDB_ENV_OPTION,
     area: list[str] = _AREA_OPTION,
     exclude_area: list[str] = _EXCLUDE_AREA_OPTION,
     schema: list[str] = _SCHEMA_OPTION,
@@ -232,7 +245,7 @@ def testdb_reset(
 ) -> None:
     """Drop and recreate only this workspace's database, then reapply schema + seed data."""
     testdb.reset_testdb(
-        areas=_as_set(area), exclude_areas=_as_set(exclude_area), schemas=_as_set(schema),
+        env=env, areas=_as_set(area), exclude_areas=_as_set(exclude_area), schemas=_as_set(schema),
         exclude_schemas=_as_set(exclude_schema),
     )
     info = testdb.status()
@@ -310,6 +323,7 @@ def migrate_check(
     exclude_area: list[str] = _EXCLUDE_AREA_OPTION,
     schema: list[str] = _SCHEMA_OPTION,
     exclude_schema: list[str] = _EXCLUDE_SCHEMA_OPTION,
+    env: str | None = _MIGRATE_ENV_OPTION,
 ) -> None:
     """List which migration files under migrations_dir are applied vs. pending."""
     if not migrations_dir.is_dir():
@@ -324,6 +338,7 @@ def migrate_check(
         exclude_areas=_as_set(exclude_area),
         schemas=_as_set(schema),
         exclude_schemas=_as_set(exclude_schema),
+        env=env,
     )
     try:
         applied = migrate.applied_migrations(conninfo, tracking_table)
@@ -367,6 +382,7 @@ def migrate_apply(
     exclude_area: list[str] = _EXCLUDE_AREA_OPTION,
     schema: list[str] = _SCHEMA_OPTION,
     exclude_schema: list[str] = _EXCLUDE_SCHEMA_OPTION,
+    env: str | None = _MIGRATE_ENV_OPTION,
 ) -> None:
     """Apply pending migration files, in filename order, tracking each in tracking_table."""
     if not migrations_dir.is_dir():
@@ -393,6 +409,7 @@ def migrate_apply(
                 exclude_areas=exclude_areas,
                 schemas=schemas,
                 exclude_schemas=exclude_schemas,
+                env=env,
             )
         except migrate.TrackingTableMissing:
             err_console.print(
@@ -400,7 +417,7 @@ def migrate_apply(
             )
             targets = migrate.list_migration_files(
                 migrations_dir, areas=areas, exclude_areas=exclude_areas, schemas=schemas,
-                exclude_schemas=exclude_schemas,
+                exclude_schemas=exclude_schemas, env=env,
             )
 
     if not targets:

pgdevkit-0.6.1/pgdevkit/envtag.py

@@ -0,0 +1,54 @@
+"""Optional `<name>.<env>.sql` filename convention: a file whose dot-segment
+immediately before `.sql` names a deployment environment (e.g.
+`grants.prod.sql`, `seed.staging.sql`) is only in scope when the caller is
+targeting that same environment. A plain `<name>.sql` file (no such segment)
+is untagged/common and is always in scope, regardless of which environment is
+requested — mirroring the untagged-file rule for `-- area:` tags in
+areas.py.
+
+This generalizes the older, hardcoded `.prod.sql` convention (still the usual
+name for a production-only file — grants, real user accounts — that
+`pgdb testdb` should never touch); any string can now be used as an
+environment name.
+
+`.init.sql` (one-time setup, see docs/database-layout.md) is reserved and is
+never interpreted as an environment tag.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_RESERVED_SQL_SUFFIXES = {"init"}
+
+
+def file_env(path: Path) -> str | None:
+    """The environment tag from `path`'s name, or None if it's untagged (or
+    the suffix is a reserved, non-env one like `.init.sql`). Only `.sql`
+    files can carry a tag."""
+    if path.suffix != ".sql":
+        return None
+    stem = path.stem
+    base, dot, suffix = stem.rpartition(".")
+    if not dot or suffix in _RESERVED_SQL_SUFFIXES:
+        return None
+    return suffix
+
+
+def env_allowed(path: Path, env: str | None) -> bool:
+    """Whether `path` is in scope for `env`. `env=None` means no environment
+    filtering was requested, so every file (tagged or not) is in scope."""
+    if env is None:
+        return True
+    tag = file_env(path)
+    return tag is None or tag == env
+
+
+def strip_env_suffix(path: Path) -> str:
+    """`path.stem` with a trailing `.<tag>` removed, so a tagged file
+    resolves to the same logical name as its untagged counterpart would
+    (e.g. `grants.prod.sql` -> "grants", same as `grants.sql`)."""
+    tag = file_env(path)
+    if tag is None:
+        return path.stem
+    return path.stem[: -(len(tag) + 1)]

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pgdevkit/migrate.py

@@ -19,6 +19,7 @@ from psycopg import errors as pg_errors
 from psycopg import sql as pg_sql
 
 from .areas import filter_by_area
+from .envtag import env_allowed
 from .schemas import filter_by_schema
 from .sql_text import strip_line_comments
 
@@ -236,10 +237,17 @@ def list_migration_files(
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
     exclude_schemas: frozenset[str] | None = None,
+    env: str | None = None,
 ) -> list[Path]:
+    """Migration files under migrations_dir, restricted by area (see
+    `.areas`), by schema (see `.schemas`), and by environment tag (see
+    `.envtag`) — e.g. a `2026-07-10_backfill.prod.sql` is only included when
+    `env="prod"`. `env=None` (the default) applies no environment filtering
+    at all, so every file is a candidate regardless of its tag."""
     files = sorted(migrations_dir.glob("*.sql"))
     files = filter_by_area(files, only=areas, exclude=exclude_areas)
-    return filter_by_schema(files, only=schemas, exclude=exclude_schemas)
+    files = filter_by_schema(files, only=schemas, exclude=exclude_schemas)
+    return [f for f in files if env_allowed(f, env)]
 
 
 def applied_migrations(conninfo: str, tracking_table: str) -> dict[str, tuple[datetime, str]]:
@@ -264,10 +272,16 @@ def pending_migrations(
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
     exclude_schemas: frozenset[str] | None = None,
+    env: str | None = None,
 ) -> list[Path]:
     applied = applied_migrations(conninfo, tracking_table)
     files = list_migration_files(
-        migrations_dir, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas
+        migrations_dir,
+        areas=areas,
+        exclude_areas=exclude_areas,
+        schemas=schemas,
+        exclude_schemas=exclude_schemas,
+        env=env,
     )
     return [p for p in files if p.name not in applied]
 

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pgdevkit/testdb/api.py

@@ -73,6 +73,7 @@ async def _apply(
     db_name: str,
     force_reset: bool,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -84,6 +85,7 @@ async def _apply(
             config.root / config.database_dir,
             extensions=config.extensions,
             force_reset=force_reset,
+            env=env,
             areas=areas,
             exclude_areas=exclude_areas,
             schemas=schemas,
@@ -95,6 +97,7 @@ def ensure_testdb(
     project_root: Path | None = None,
     force_reset: bool = False,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -105,6 +108,9 @@ def ensure_testdb(
     vars for this workspace (or the mssql equivalent's env vars, per
     `config.engine`).
 
+    `env` selects which environment-tagged files apply (see pgdevkit.envtag,
+    e.g. a `grants.prod.sql` is skipped unless env="prod").
+
     `areas`/`exclude_areas` and `schemas`/`exclude_schemas` restrict which
     database/ files get applied -- e.g. for a test DB scoped to one area or
     schema. Neither filters what gets *dropped* by force_reset/clean, only
@@ -113,7 +119,7 @@ def ensure_testdb(
     if config.engine == "mssql":
         return _mssql_api().ensure_testdb(
             config, db_name, force_reset,
-            areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
         )
 
     ensure_container()
@@ -124,7 +130,7 @@ def ensure_testdb(
         await _ensure_database(db_name)
         await _apply(
             config, db_name, force_reset,
-            areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
         )
 
     asyncio.run(_run())
@@ -134,6 +140,7 @@ def ensure_testdb(
 def reset_testdb(
     project_root: Path | None = None,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -143,7 +150,7 @@ def reset_testdb(
     schema and seed data."""
     return ensure_testdb(
         project_root, force_reset=True,
-        areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+        env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
     )
 
 

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pgdevkit/testdb/mssql/api.py

@@ -9,6 +9,7 @@ import mssql_python
 
 from ...db.mssql_sql import ident, json_encode_value
 from ...dialect import MSSQL
+from ...envtag import strip_env_suffix
 from .. import query
 from ..config import ProjectConfig
 from ..schema import _iter_sql_files, _strip_layer_prefix
@@ -106,6 +107,7 @@ async def _apply(
     db_name: str,
     force_reset: bool,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -121,7 +123,7 @@ async def _apply(
             return
         for file, sql in _iter_sql_files(
             database_dir, MSSQL,
-            areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
         ):
             for batch in query.split_tsql_batches(sql):
 
@@ -129,11 +131,13 @@ async def _apply(
                     conn.cursor().execute(batch)
 
                 await asyncio.to_thread(_exec)
-            json_file = file.with_suffix(".test_data.json")
+            table_stem = strip_env_suffix(file)
+            json_file = file.parent / f"{table_stem}.test_data.json"
             if json_file.exists():
                 schema_name = _strip_layer_prefix(file.parent.parent.name)
-                table_stem = _strip_layer_prefix(file.stem)
-                await _insert_test_data(json_file, f"{schema_name}.{table_stem}", force_reset, conn)
+                await _insert_test_data(
+                    json_file, f"{schema_name}.{_strip_layer_prefix(table_stem)}", force_reset, conn
+                )
     finally:
         await asyncio.to_thread(conn.close)
 
@@ -143,6 +147,7 @@ def ensure_testdb(
     db_name: str,
     force_reset: bool,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -156,7 +161,7 @@ def ensure_testdb(
         await _ensure_database(db_name)
         await _apply(
             config, db_name, force_reset,
-            areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
         )
 
     asyncio.run(_run())

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pgdevkit/testdb/schema.py

@@ -16,6 +16,7 @@ from psycopg.sql import SQL, Identifier, Placeholder
 from ..areas import area_allowed, parse_areas
 from ..db.complex_types import ComplexHelper
 from ..dialect import Dialect, POSTGRES, SYSTEM_SCHEMAS
+from ..envtag import env_allowed, strip_env_suffix
 from ..parser import IGNORED_DIR_NAMES
 from ..schemas import schema_allowed, sql_schemas
 
@@ -40,7 +41,7 @@ _TYPE_ORDER = {
 
 
 def _get_type_order(path: Path) -> int:
-    filename = re.sub(r"^\d+(\.\d+)?", "", path.name).removeprefix("_").removesuffix(".sql")
+    filename = re.sub(r"^\d+(\.\d+)?", "", strip_env_suffix(path)).removeprefix("_")
     if filename in _TYPE_ORDER:
         return _TYPE_ORDER[filename]
     if path.parent.name in _TYPE_ORDER:
@@ -123,6 +124,7 @@ def _iter_sql_files(
     database_dir: Path,
     dialect: Dialect = POSTGRES,
     *,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -130,6 +132,22 @@ 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.
+
     A file dropped by the area/schema filter is skipped entirely -- as if it
     didn't exist -- so it never delivers a dependency another (in-scope)
     file waits on; that's the same tradeoff `list_migration_files`/
@@ -142,12 +160,14 @@ def _iter_sql_files(
         for file in dbfiles:
             if file in ("all.sql", "100_permissions.sql"):
                 continue
-            if file.endswith(".sql") and ".prod" not in file:
-                files.append(Path(root) / file)
+            path = Path(root) / file
+            if file.endswith(".sql") and env_allowed(path, env):
+                files.append(path)
 
     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")
@@ -157,10 +177,13 @@ 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)
-            full_name = f"{schema}.{_strip_layer_prefix(file.stem)}"
+            full_name = f"{schema}.{_strip_layer_prefix(strip_env_suffix(file))}"
             deps.discard(full_name)  # the file's own CREATE target is not a real dependency
             all_declared.add(full_name)
             if not deps or all(d in delivered for d in deps):
@@ -190,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,
@@ -261,6 +286,7 @@ async def apply_schema(
     force_reset: bool = False,
     *,
     dialect: Dialect = POSTGRES,
+    env: str = "local_test",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
     schemas: frozenset[str] | None = None,
@@ -269,6 +295,13 @@ 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.
+
     `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
@@ -286,16 +319,19 @@ async def apply_schema(
 
     async def _apply(file: Path, sql: str) -> None:
         await con.execute(cast(Any, sql))
-        json_file = file.with_suffix(".test_data.json")
+        table_stem = strip_env_suffix(file)
+        json_file = file.parent / f"{table_stem}.test_data.json"
         if json_file.exists():
             schema_name = _strip_layer_prefix(file.parent.parent.name)
-            table_stem = _strip_layer_prefix(file.stem)
-            await _insert_test_data(json_file, f"{schema_name}.{table_stem}", force_reset, con, complex_helper)
+            await _insert_test_data(
+                json_file, f"{schema_name}.{_strip_layer_prefix(table_stem)}", force_reset, con, complex_helper
+            )
 
     failures: list[tuple[Path, str]] = []
     for file, sql in _iter_sql_files(
         database_dir,
         dialect,
+        env=env,
         areas=areas,
         exclude_areas=exclude_areas,
         schemas=schemas,

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/pyproject.toml

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

{pgdevkit-0.5.0 → pgdevkit-0.6.1}/skills/pgdevkit/SKILL.md

@@ -253,7 +253,7 @@ sqlfmt --check db/queries/  # CI check
 
 ## The `database/` folder & backfilling untracked objects
 
-See [docs/database-layout.md](../../docs/database-layout.md) for the full convention: layer directories, object-type subfolders and their apply order, file-naming rules (`.test_data.json`, `.init.sql`, `.prod`), and how migrations are organised.
+See [docs/database-layout.md](../../docs/database-layout.md) for the full convention: layer directories, object-type subfolders and their apply order, file-naming rules (`.test_data.json`, `.init.sql`, `.<env>.sql`), and how migrations are organised.
 
 If a table, view, or function was created directly on the database and never got a `.sql` file:
 
@@ -285,6 +285,6 @@ Reports drift between the `database/` `.sql` files and the actual schema — tab
 - [ ] All parameters use `%(name)s` style with a dict argument
 - [ ] Results mapped to a Pydantic model; table-mapped models extend `PostgresTableModel`
 - [ ] No `LATERAL JOIN` — use a CTE that groups/aggregates first, then joins it
-- [ ] `.prod` files are production-only and skipped by `pgdb testdb`
+- [ ] `.<env>.sql` files (e.g. `.prod.sql`) are skipped by `pgdb testdb` unless it's run with a matching `--env`
 - [ ] Every table (and non-obvious column) has a `COMMENT ON`, placed in the object's own `.sql` file
 - [ ] Untracked DB objects backfilled via `pgdb fetch-missing`, not left undocumented

pgdevkit-0.6.1/tests/test_envtag.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pgdevkit.envtag import env_allowed, file_env, strip_env_suffix
+
+
+class TestFileEnv:
+    def test_plain_sql_file_is_untagged(self):
+        assert file_env(Path("grants.sql")) is None
+
+    def test_init_sql_is_never_a_tag(self):
+        assert file_env(Path("user.init.sql")) is None
+
+    def test_prod_suffix_is_the_prod_tag(self):
+        assert file_env(Path("grants.prod.sql")) == "prod"
+
+    def test_arbitrary_env_name_is_a_tag(self):
+        assert file_env(Path("seed.staging.sql")) == "staging"
+        assert file_env(Path("seed.local_test.sql")) == "local_test"
+
+    def test_non_sql_file_is_never_tagged(self):
+        assert file_env(Path("widget.test_data.json")) is None
+
+
+class TestEnvAllowed:
+    def test_no_env_requested_allows_everything(self):
+        assert env_allowed(Path("grants.prod.sql"), None) is True
+        assert env_allowed(Path("grants.sql"), None) is True
+
+    def test_untagged_file_always_allowed(self):
+        assert env_allowed(Path("grants.sql"), "prod") is True
+        assert env_allowed(Path("grants.sql"), "staging") is True
+
+    def test_matching_tag_allowed(self):
+        assert env_allowed(Path("grants.prod.sql"), "prod") is True
+
+    def test_mismatched_tag_disallowed(self):
+        assert env_allowed(Path("grants.prod.sql"), "staging") is False
+        assert env_allowed(Path("grants.prod.sql"), "local_test") is False
+
+    def test_init_file_always_allowed(self):
+        assert env_allowed(Path("user.init.sql"), "prod") is True
+        assert env_allowed(Path("user.init.sql"), "staging") is True
+
+
+class TestStripEnvSuffix:
+    def test_untagged_file_unchanged(self):
+        assert strip_env_suffix(Path("grants.sql")) == "grants"
+
+    def test_tagged_file_matches_untagged_logical_name(self):
+        assert strip_env_suffix(Path("grants.prod.sql")) == "grants"
+        assert strip_env_suffix(Path("seed.local_test.sql")) == "seed"
+
+    def test_init_file_keeps_init_in_the_stem(self):
+        assert strip_env_suffix(Path("user.init.sql")) == "user.init"