pgdevkit 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.4.0
+Version: 0.6.0
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -79,7 +79,13 @@ which parses/introspects/diffs like any other column type; see
 handled on the CRUD side (write-side serialization only, no auto-parsing on
 read — `mssql-python` doesn't distinguish `json` columns from `nvarchar`).
 
-### Area tagging and filtering
+### Area and schema filtering
+
+Two independent, composable ways to narrow which files a command touches:
+**area** is an explicit opt-in tag; **schema** is derived automatically from
+each file's own SQL.
+
+#### Area tagging
 
 Any migration file or `database/` code file can declare one or more areas by
 starting with a `-- area:` comment:
@@ -97,43 +103,95 @@ first real statement); a `-- area:` comment later in the file doesn't count.
 A file with no directive is untagged, and untagged files are treated as
 shared/common.
 
-`pgdb compare`, `pgdb migrate check`, and `pgdb migrate apply` all accept:
+#### Schema filtering
+
+No tag needed — schema membership is parsed straight out of the SQL itself:
+every schema-qualified (or default-schema, when unqualified) table/view/
+function/index reference across every statement in the file, DDL or DML
+alike, plus any `CREATE SCHEMA name`. A file whose schema(s) can't be
+determined (unparseable content, or no table/schema reference in it at all)
+is treated the same as an untagged file — always kept.
+
+#### Options
+
+`pgdb compare`, `pgdb migrate check`, `pgdb migrate apply`, `pgdb testdb up`,
+and `pgdb testdb reset` all accept:
 
 - `--area NAME` (repeatable) — restrict to files declaring one of the given
   areas, **plus every untagged file** (untagged files always stay in scope).
 - `--exclude-area NAME` (repeatable) — drop files declaring one of the given
   areas; untagged files are never dropped by this.
+- `--schema NAME` (repeatable) — restrict to files referencing one of the
+  given schemas, **plus every file with no detectable schema reference**.
+- `--exclude-schema NAME` (repeatable) — drop files referencing one of the
+  given schemas; files with no detectable reference are never dropped.
 
-Both can be combined; a file matching both an included and an excluded area
-is excluded. Passing neither option applies no filtering (the default,
-unchanged behavior).
+All four can be combined — a file must pass every filter it's subject to (an
+area match doesn't excuse a schema mismatch, and vice versa), and a file
+matching both an included and an excluded value on the same axis is
+excluded. Passing none of them applies no filtering (the default, unchanged
+behavior).
 
 ```bash
 pgdb migrate apply path/to/database/_migration_scripts --url ... --area billing
 pgdb compare path/to/database/ --url ... --exclude-area reporting
+pgdb migrate check path/to/database/_migration_scripts --url ... --schema billing --exclude-schema reporting
+pgdb testdb up --schema billing
 ```
 
 `compare`'s default report (no `--report-extra-db`) only checks that the
 filtered scripts exist correctly in the DB, so it composes safely with area
-filtering. Passing `--report-extra-db` together with an area filter also
-reports every DB object outside the filtered area(s) as "missing in
-scripts" — since the live database has no concept of areas, only the
-scripts side is filtered — so treat that combination's "missing in scripts"
-results with that in mind (the CLI prints a warning when you combine them).
-
-`pgdb fetch-missing` deliberately has **no** `--area`/`--exclude-area`: it
-diffs the full database against scripts to find genuinely untracked
-objects, so narrowing the scripts side by area would make every object
-tracked only under a different area look "missing" too — and `--write`
-would then reconstruct a duplicate file for something that already exists.
-
-`pgdevkit.areas` exposes the same logic for scripting:
+and schema filtering. Passing `--report-extra-db` together with either kind
+of filter also reports every DB object outside the filtered area(s)/
+schema(s) as "missing in scripts" — since the live database has no concept
+of areas, and isn't itself filtered by `--schema` either — only the scripts
+side is filtered — so treat that combination's "missing in scripts" results
+with that in mind (the CLI prints a warning when you combine them).
+
+`pgdb fetch-missing` deliberately has **no** `--area`/`--exclude-area` (or
+`--schema`/`--exclude-schema`): it diffs the full database against scripts
+to find genuinely untracked objects, so narrowing the scripts side would
+make every object tracked under a different area/schema look "missing" too
+— and `--write` would then reconstruct a duplicate file for something that
+already exists.
+
+`pgdevkit.areas` exposes the tag-filtering logic for scripting:
 `parse_areas`/`file_areas` read a file's declared areas, and
 `area_allowed`/`filter_by_area` apply the `only`/`exclude` semantics above.
-`pgdevkit.migrate.list_migration_files`/`pending_migrations` and
-`pgdevkit.parser.parse_directory` take the same `areas`/`exclude_areas`
-keyword arguments (`pgdevkit.fetch_missing.find_missing_objects` doesn't,
-for the reason above).
+`pgdevkit.schemas` exposes the equivalent for schema filtering:
+`sql_schemas`/`file_schemas` detect a file's referenced schemas, and
+`schema_allowed`/`filter_by_schema` apply the same `only`/`exclude`
+semantics. `pgdevkit.migrate.list_migration_files`/`pending_migrations` and
+`pgdevkit.parser.parse_directory` take both pairs of keyword arguments
+(`areas`/`exclude_areas` and `schemas`/`exclude_schemas`);
+`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`
 
@@ -163,7 +221,15 @@ 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
+applied — e.g. `pgdb testdb up --schema billing` for a test DB with only the
+`billing` schema's tables/views/functions, without waiting on the rest of the
+project's schema to apply. `ensure_testdb`/`reset_testdb` take the same
+keyword arguments when called from Python (e.g. from a pytest fixture).
 
 Container connection defaults (`localhost:54322`, `postgres`/`testpwd`) can
 be overridden with `PGDEVKIT_TESTDB_HOST`, `PGDEVKIT_TESTDB_PORT`,

{pgdevkit-0.4.0 → pgdevkit-0.6.0}/README.md

@@ -58,7 +58,13 @@ which parses/introspects/diffs like any other column type; see
 handled on the CRUD side (write-side serialization only, no auto-parsing on
 read — `mssql-python` doesn't distinguish `json` columns from `nvarchar`).
 
-### Area tagging and filtering
+### Area and schema filtering
+
+Two independent, composable ways to narrow which files a command touches:
+**area** is an explicit opt-in tag; **schema** is derived automatically from
+each file's own SQL.
+
+#### Area tagging
 
 Any migration file or `database/` code file can declare one or more areas by
 starting with a `-- area:` comment:
@@ -76,43 +82,95 @@ first real statement); a `-- area:` comment later in the file doesn't count.
 A file with no directive is untagged, and untagged files are treated as
 shared/common.
 
-`pgdb compare`, `pgdb migrate check`, and `pgdb migrate apply` all accept:
+#### Schema filtering
+
+No tag needed — schema membership is parsed straight out of the SQL itself:
+every schema-qualified (or default-schema, when unqualified) table/view/
+function/index reference across every statement in the file, DDL or DML
+alike, plus any `CREATE SCHEMA name`. A file whose schema(s) can't be
+determined (unparseable content, or no table/schema reference in it at all)
+is treated the same as an untagged file — always kept.
+
+#### Options
+
+`pgdb compare`, `pgdb migrate check`, `pgdb migrate apply`, `pgdb testdb up`,
+and `pgdb testdb reset` all accept:
 
 - `--area NAME` (repeatable) — restrict to files declaring one of the given
   areas, **plus every untagged file** (untagged files always stay in scope).
 - `--exclude-area NAME` (repeatable) — drop files declaring one of the given
   areas; untagged files are never dropped by this.
+- `--schema NAME` (repeatable) — restrict to files referencing one of the
+  given schemas, **plus every file with no detectable schema reference**.
+- `--exclude-schema NAME` (repeatable) — drop files referencing one of the
+  given schemas; files with no detectable reference are never dropped.
 
-Both can be combined; a file matching both an included and an excluded area
-is excluded. Passing neither option applies no filtering (the default,
-unchanged behavior).
+All four can be combined — a file must pass every filter it's subject to (an
+area match doesn't excuse a schema mismatch, and vice versa), and a file
+matching both an included and an excluded value on the same axis is
+excluded. Passing none of them applies no filtering (the default, unchanged
+behavior).
 
 ```bash
 pgdb migrate apply path/to/database/_migration_scripts --url ... --area billing
 pgdb compare path/to/database/ --url ... --exclude-area reporting
+pgdb migrate check path/to/database/_migration_scripts --url ... --schema billing --exclude-schema reporting
+pgdb testdb up --schema billing
 ```
 
 `compare`'s default report (no `--report-extra-db`) only checks that the
 filtered scripts exist correctly in the DB, so it composes safely with area
-filtering. Passing `--report-extra-db` together with an area filter also
-reports every DB object outside the filtered area(s) as "missing in
-scripts" — since the live database has no concept of areas, only the
-scripts side is filtered — so treat that combination's "missing in scripts"
-results with that in mind (the CLI prints a warning when you combine them).
-
-`pgdb fetch-missing` deliberately has **no** `--area`/`--exclude-area`: it
-diffs the full database against scripts to find genuinely untracked
-objects, so narrowing the scripts side by area would make every object
-tracked only under a different area look "missing" too — and `--write`
-would then reconstruct a duplicate file for something that already exists.
-
-`pgdevkit.areas` exposes the same logic for scripting:
+and schema filtering. Passing `--report-extra-db` together with either kind
+of filter also reports every DB object outside the filtered area(s)/
+schema(s) as "missing in scripts" — since the live database has no concept
+of areas, and isn't itself filtered by `--schema` either — only the scripts
+side is filtered — so treat that combination's "missing in scripts" results
+with that in mind (the CLI prints a warning when you combine them).
+
+`pgdb fetch-missing` deliberately has **no** `--area`/`--exclude-area` (or
+`--schema`/`--exclude-schema`): it diffs the full database against scripts
+to find genuinely untracked objects, so narrowing the scripts side would
+make every object tracked under a different area/schema look "missing" too
+— and `--write` would then reconstruct a duplicate file for something that
+already exists.
+
+`pgdevkit.areas` exposes the tag-filtering logic for scripting:
 `parse_areas`/`file_areas` read a file's declared areas, and
 `area_allowed`/`filter_by_area` apply the `only`/`exclude` semantics above.
-`pgdevkit.migrate.list_migration_files`/`pending_migrations` and
-`pgdevkit.parser.parse_directory` take the same `areas`/`exclude_areas`
-keyword arguments (`pgdevkit.fetch_missing.find_missing_objects` doesn't,
-for the reason above).
+`pgdevkit.schemas` exposes the equivalent for schema filtering:
+`sql_schemas`/`file_schemas` detect a file's referenced schemas, and
+`schema_allowed`/`filter_by_schema` apply the same `only`/`exclude`
+semantics. `pgdevkit.migrate.list_migration_files`/`pending_migrations` and
+`pgdevkit.parser.parse_directory` take both pairs of keyword arguments
+(`areas`/`exclude_areas` and `schemas`/`exclude_schemas`);
+`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`
 
@@ -142,7 +200,15 @@ 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
+applied — e.g. `pgdb testdb up --schema billing` for a test DB with only the
+`billing` schema's tables/views/functions, without waiting on the rest of the
+project's schema to apply. `ensure_testdb`/`reset_testdb` take the same
+keyword arguments when called from Python (e.g. from a pytest fixture).
 
 Container connection defaults (`localhost:54322`, `postgres`/`testpwd`) can
 be overridden with `PGDEVKIT_TESTDB_HOST`, `PGDEVKIT_TESTDB_PORT`,

{pgdevkit-0.4.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.4.0 → pgdevkit-0.6.0}/pgdevkit/cli.py

@@ -29,9 +29,32 @@ _AREA_OPTION = typer.Option(
 _EXCLUDE_AREA_OPTION = typer.Option(
     [], "--exclude-area", help="Skip files declaring this area (repeatable); untagged files are never excluded"
 )
+_SCHEMA_OPTION = typer.Option(
+    [],
+    "--schema",
+    help="Restrict to files referencing this DB schema (repeatable); "
+    "files with no detectable schema reference always stay in scope",
+)
+_EXCLUDE_SCHEMA_OPTION = typer.Option(
+    [],
+    "--exclude-schema",
+    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_area_set(values: list[str]) -> frozenset[str] | None:
+def _as_set(values: list[str]) -> frozenset[str] | None:
     return frozenset(values) if values else None
 
 testdb_app = typer.Typer(name="testdb", help="Manage the shared local Postgres test container")
@@ -59,17 +82,20 @@ def compare(
     dialect: str = typer.Option("postgres", "--dialect", help="postgres (default) or mssql"),
     area: list[str] = _AREA_OPTION,
     exclude_area: list[str] = _EXCLUDE_AREA_OPTION,
+    schema: list[str] = _SCHEMA_OPTION,
+    exclude_schema: list[str] = _EXCLUDE_SCHEMA_OPTION,
     scripts_dir: Path = typer.Argument(..., help="Directory containing SQL scripts"),
 ) -> None:
     """Compare SQL scripts to a live database and report differences."""
     if not scripts_dir.is_dir():
         err_console.print(f"[red]Error:[/red] {scripts_dir} is not a directory")
         raise typer.Exit(2)
-    if report_extra_db and (area or exclude_area):
+    if report_extra_db and (area or exclude_area or schema or exclude_schema):
         console.print(
-            "[yellow]⚠[/yellow]  --report-extra-db with --area/--exclude-area will report every DB object "
-            "outside the filtered area(s) as \"missing in scripts\", since the live database has no concept "
-            "of areas — only the scripts side is filtered."
+            "[yellow]⚠[/yellow]  --report-extra-db with --area/--exclude-area/--schema/--exclude-schema will "
+            "report every DB object outside the filtered area(s)/schema(s) as \"missing in scripts\", since the "
+            "live database has no concept of areas — and isn't itself filtered by --schema either — only the "
+            "scripts side is filtered."
         )
 
     try:
@@ -91,7 +117,12 @@ def compare(
 
     with console.status("Parsing SQL scripts..."):
         scripts_schema = parse_directory(
-            scripts_dir, dialect=backend.dialect, areas=_as_area_set(area), exclude_areas=_as_area_set(exclude_area)
+            scripts_dir,
+            dialect=backend.dialect,
+            areas=_as_set(area),
+            exclude_areas=_as_set(exclude_area),
+            schemas=_as_set(schema),
+            exclude_schemas=_as_set(exclude_schema),
         )
 
     with console.status("Introspecting database..."):
@@ -188,17 +219,35 @@ def fetch_missing(
 
 
 @testdb_app.command("up")
-def testdb_up() -> None:
+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,
+    exclude_schema: list[str] = _EXCLUDE_SCHEMA_OPTION,
+) -> None:
     """Ensure the container is running, the workspace DB exists, and schema is applied."""
-    testdb.ensure_testdb()
+    testdb.ensure_testdb(
+        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()
     console.print(f"[green]Test DB ready:[/green] {info['database']} ({info['dsn']})")
 
 
 @testdb_app.command("reset")
-def testdb_reset() -> None:
+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,
+    exclude_schema: list[str] = _EXCLUDE_SCHEMA_OPTION,
+) -> None:
     """Drop and recreate only this workspace's database, then reapply schema + seed data."""
-    testdb.reset_testdb()
+    testdb.reset_testdb(
+        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()
     console.print(f"[green]Test DB reset:[/green] {info['database']}")
 
@@ -272,6 +321,9 @@ def migrate_check(
     ),
     area: list[str] = _AREA_OPTION,
     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():
@@ -281,7 +333,12 @@ def migrate_check(
     conninfo = build_conninfo(url, entra_user)
     tracking_table = tracking_table or migrate.default_tracking_table(migrations_dir)
     local_files = migrate.list_migration_files(
-        migrations_dir, areas=_as_area_set(area), exclude_areas=_as_area_set(exclude_area)
+        migrations_dir,
+        areas=_as_set(area),
+        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)
@@ -323,6 +380,9 @@ def migrate_apply(
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirm-target prompt"),
     area: list[str] = _AREA_OPTION,
     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():
@@ -331,7 +391,8 @@ def migrate_apply(
 
     conninfo = build_conninfo(url, entra_user)
     tracking_table = tracking_table or migrate.default_tracking_table(migrations_dir)
-    areas, exclude_areas = _as_area_set(area), _as_area_set(exclude_area)
+    areas, exclude_areas = _as_set(area), _as_set(exclude_area)
+    schemas, exclude_schemas = _as_set(schema), _as_set(exclude_schema)
     target_desc = url.rsplit("@", 1)[-1] if "@" in url else url
     if not yes:
         typer.confirm(f"About to run migrations against {target_desc}. Continue?", abort=True)
@@ -341,13 +402,23 @@ def migrate_apply(
     else:
         try:
             targets = migrate.pending_migrations(
-                migrations_dir, conninfo, tracking_table, areas=areas, exclude_areas=exclude_areas
+                migrations_dir,
+                conninfo,
+                tracking_table,
+                areas=areas,
+                exclude_areas=exclude_areas,
+                schemas=schemas,
+                exclude_schemas=exclude_schemas,
+                env=env,
             )
         except migrate.TrackingTableMissing:
             err_console.print(
                 f"[yellow]⚠[/yellow]  {tracking_table} not found — treating every migration as pending"
             )
-            targets = migrate.list_migration_files(migrations_dir, areas=areas, exclude_areas=exclude_areas)
+            targets = migrate.list_migration_files(
+                migrations_dir, areas=areas, exclude_areas=exclude_areas, schemas=schemas,
+                exclude_schemas=exclude_schemas, env=env,
+            )
 
     if not targets:
         console.print("No pending migrations.")

{pgdevkit-0.4.0 → pgdevkit-0.6.0}/pgdevkit/dialect.py

@@ -43,6 +43,16 @@ _MSSQL_TYPE_SYNONYMS = {
 }
 
 
+# Schemas that hold system catalog views/tables, never a file any project
+# using pgdevkit manages -- a reference to one (e.g. an idempotency guard
+# querying it, or a `SELECT ... FROM information_schema/pg_catalog/sys ...`)
+# is never a real schema-membership or cross-file-dependency signal. Shared
+# by `schemas.py` (schema-reference filtering) and `testdb/schema.py`
+# (dependency-safe apply ordering), which both walk the same sqlglot Table
+# nodes for a related-but-different purpose.
+SYSTEM_SCHEMAS = {"pg_catalog", "information_schema", "sys"}
+
+
 @dataclass(frozen=True)
 class Dialect:
     """A thin wrapper around a sqlglot dialect name plus the handful of

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)]