pgdevkit 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.5.0
+Version: 0.6.0
 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.0}/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.0}/docs/database-layout.md

@@ -71,10 +71,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 +164,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.0}/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.0/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.0}/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.0}/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.0}/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.0}/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,9 @@ def _iter_sql_files(
 ):
     """Yield (Path, sql_content) pairs in dependency-safe execution order.
 
+    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,8 +147,9 @@ 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]] = []
@@ -160,7 +166,7 @@ def _iter_sql_files(
         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):
@@ -261,6 +267,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 +276,9 @@ 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.
 
+    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 +296,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.0}/pyproject.toml

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

{pgdevkit-0.5.0 → pgdevkit-0.6.0}/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.0/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"

pgdevkit-0.6.0/tests/test_migrate_env.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pgdevkit.migrate import list_migration_files
+
+
+def _write(dir: Path, name: str, content: str = "select 1;\n") -> Path:
+    p = dir / name
+    p.write_text(content, encoding="utf-8")
+    return p
+
+
+class TestListMigrationFilesEnvFiltering:
+    def test_no_env_applies_every_file_regardless_of_tag(self, tmp_path: Path):
+        prod = _write(tmp_path, "001_prod.prod.sql")
+        common = _write(tmp_path, "002_common.sql")
+
+        assert list_migration_files(tmp_path) == sorted([prod, common])
+
+    def test_env_keeps_matching_tag_and_untagged(self, tmp_path: Path):
+        prod = _write(tmp_path, "001_backfill.prod.sql")
+        staging = _write(tmp_path, "002_backfill.staging.sql")
+        common = _write(tmp_path, "003_common.sql")
+
+        result = list_migration_files(tmp_path, env="prod")
+        assert set(result) == {prod, common}
+        assert staging not in result
+
+    def test_init_file_is_never_filtered_by_env(self, tmp_path: Path):
+        init = _write(tmp_path, "001_setup.init.sql")
+
+        assert list_migration_files(tmp_path, env="prod") == [init]
+        assert list_migration_files(tmp_path, env="staging") == [init]
+
+    def test_env_and_area_filters_compose(self, tmp_path: Path):
+        billing_prod = _write(tmp_path, "001_billing.prod.sql", "-- area: billing\nselect 1;\n")
+        billing_staging = _write(tmp_path, "002_billing.staging.sql", "-- area: billing\nselect 1;\n")
+        reporting_prod = _write(tmp_path, "003_reporting.prod.sql", "-- area: reporting\nselect 1;\n")
+
+        result = list_migration_files(tmp_path, areas=frozenset({"billing"}), env="prod")
+        assert result == [billing_prod]
+        assert billing_staging not in result
+        assert reporting_prod not in result

pgdevkit-0.6.0/tests/testdb/fixtures/database/app/tables/prod_only.prod.sql

@@ -0,0 +1,3 @@
+CREATE TABLE IF NOT EXISTS app.prod_only (
+    id serial PRIMARY KEY
+);

pgdevkit-0.6.0/tests/testdb/fixtures/database/app/tables/widget.init.sql

@@ -0,0 +1 @@
+ALTER TABLE app.widget ADD COLUMN IF NOT EXISTS init_flag boolean NOT NULL DEFAULT true;

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

@@ -114,6 +114,43 @@ async def test_apply_schema_seeds_composite_enum_and_jsonb_columns(schema_test_d
     assert tags == ["small", "shiny"]
 
 
+@requires_podman
+async def test_apply_schema_skips_env_tagged_file_for_a_different_env(schema_test_db):
+    # prod_only.prod.sql is tagged for "prod" -- with the default env
+    # ("local_test"), it must not be applied.
+    async with await psycopg.AsyncConnection.connect(_db_dsn(), autocommit=True) as con:
+        await apply_schema(con, FIXTURES)
+        async with con.cursor() as cur:
+            await cur.execute("SELECT to_regclass('app.prod_only')")
+            (regclass,) = await cur.fetchone()
+    assert regclass is None
+
+
+@requires_podman
+async def test_apply_schema_applies_env_tagged_file_for_the_matching_env(schema_test_db):
+    async with await psycopg.AsyncConnection.connect(_db_dsn(), autocommit=True) as con:
+        await apply_schema(con, FIXTURES, env="prod")
+        async with con.cursor() as cur:
+            await cur.execute("SELECT to_regclass('app.prod_only')")
+            (regclass,) = await cur.fetchone()
+    assert regclass is not None
+
+
+@requires_podman
+async def test_apply_schema_init_file_applies_regardless_of_env(schema_test_db):
+    # widget.init.sql adds init_flag to app.widget -- "init" is a reserved
+    # suffix, never an environment tag, so this must apply under any env.
+    async with await psycopg.AsyncConnection.connect(_db_dsn(), autocommit=True) as con:
+        await apply_schema(con, FIXTURES, env="staging")
+        async with con.cursor() as cur:
+            await cur.execute(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_schema = 'app' AND table_name = 'widget' AND column_name = 'init_flag'"
+            )
+            row = await cur.fetchone()
+    assert row is not None
+
+
 @requires_podman
 async def test_apply_schema_never_applies_migrations_dir(schema_test_db):
     # migrations/ is for one-time manual application against real databases,

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

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