pgdevkit 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

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/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/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/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/migrate.py

@@ -19,6 +19,9 @@ 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
 
 _IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"
 _DEFAULT_TRACKING_TABLE = "public.schema_migrations"
@@ -124,61 +127,12 @@ def _split_sql(sql: str) -> list[str]:
     return stmts
 
 
-def _strip_line_comments(sql: str) -> str:
-    """Drop '--' line comments, respecting string literals and $$...$$ blocks."""
-    buf: list[str] = []
-    i = 0
-    in_string = False
-    in_line_comment = False
-    dollar_tag: str | None = None
-
-    while i < len(sql):
-        c = sql[i]
-        if in_line_comment:
-            if c == "\n":
-                in_line_comment = False
-                buf.append(c)
-        elif dollar_tag is not None:
-            buf.append(c)
-            if c == "$" and sql[i:i + len(dollar_tag)] == dollar_tag:
-                buf.extend(list(dollar_tag[1:]))
-                i += len(dollar_tag)
-                dollar_tag = None
-                continue
-        elif in_string:
-            if c == "'" and i + 1 < len(sql) and sql[i + 1] == "'":
-                buf.append(c)
-                buf.append(sql[i + 1])
-                i += 2
-                continue
-            elif c == "'":
-                in_string = False
-            buf.append(c)
-        elif c == "-" and i + 1 < len(sql) and sql[i + 1] == "-":
-            in_line_comment = True
-        elif c == "$":
-            m = re.match(r"\$([A-Za-z0-9_]*)\$", sql[i:])
-            if m:
-                dollar_tag = m.group(0)
-                buf.extend(list(dollar_tag))
-                i += len(dollar_tag)
-                continue
-            buf.append(c)
-        elif c == "'":
-            in_string = True
-            buf.append(c)
-        else:
-            buf.append(c)
-        i += 1
-    return "".join(buf)
-
-
 def _created_table_names(stmts: list[str]) -> list[str]:
     """Names of tables any CREATE TABLE statement targets, parsed via sqlglot (falls back to
     regex on comment-stripped text for statements sqlglot's postgres dialect can't parse)."""
     names: list[str] = []
     for stmt in stmts:
-        stripped = _strip_line_comments(stmt)
+        stripped = strip_line_comments(stmt)
         if not re.search(r"CREATE\s+TABLE", stripped, re.IGNORECASE):
             continue  # skip sqlglot entirely for statements that can't be a CREATE TABLE
         try:
@@ -220,7 +174,7 @@ def _idempotent_target(stmt: str) -> tuple[str, ...] | None:
     COLUMN. None if the statement isn't one of these shapes — including any CREATE OR
     REPLACE, which is never safe to treat as a no-op just because the object exists, since
     the migration could be replacing it with different content."""
-    stripped = _strip_line_comments(stmt).strip()
+    stripped = strip_line_comments(stmt).strip()
     if re.search(r"\bOR\s+REPLACE\b", stripped, re.IGNORECASE):
         return None
 
@@ -281,9 +235,19 @@ def list_migration_files(
     *,
     areas: frozenset[str] | None = None,
     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"))
-    return filter_by_area(files, only=areas, exclude=exclude_areas)
+    files = filter_by_area(files, only=areas, exclude=exclude_areas)
+    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]]:
@@ -306,9 +270,19 @@ def pending_migrations(
     *,
     areas: frozenset[str] | None = None,
     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)
+    files = list_migration_files(
+        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/parser.py

@@ -10,6 +10,7 @@ import sqlglot.expressions as exp
 
 from .areas import area_allowed, parse_areas
 from .dialect import Dialect, POSTGRES, resolve_dialect
+from .schemas import schema_allowed, sql_schemas
 from .models import (
     ColumnDef, ConstraintDef, CompositeTypeDef, DatabaseSchema,
     EnumDef, FunctionDef, IndexDef, TableDef, ViewDef,
@@ -55,15 +56,21 @@ def parse_directory(
     dialect: str | Dialect = "postgres",
     areas: frozenset[str] | None = None,
     exclude_areas: frozenset[str] | None = None,
+    schemas: frozenset[str] | None = None,
+    exclude_schemas: frozenset[str] | None = None,
 ) -> DatabaseSchema:
     resolved = resolve_dialect(dialect)
     db_schema = DatabaseSchema()
     for sql_file in sorted(_iter_sql_files(scripts_dir)):
-        # Read once and reuse for both the area check and parsing, rather than
-        # filtering the file list up front (which would need its own read).
+        # Read once and reuse for the area/schema checks and parsing, rather
+        # than filtering the file list up front (which would need its own read).
         content = sql_file.read_text(encoding="utf-8")
         if (areas or exclude_areas) and not area_allowed(parse_areas(content), only=areas, exclude=exclude_areas):
             continue
+        if (schemas or exclude_schemas) and not schema_allowed(
+            sql_schemas(content, resolved), only=schemas, exclude=exclude_schemas
+        ):
+            continue
         _parse_file(sql_file, db_schema, resolved, content=content)
     return db_schema
 

pgdevkit/schemas.py

@@ -0,0 +1,118 @@
+"""Schema-membership filtering, composable with (but independent of) the
+`-- area:` tag filtering in `areas.py`.
+
+Unlike area, which is an explicit opt-in tag, a file's schema membership is
+derived by parsing its SQL: every schema-qualified (or default-schema, when
+unqualified) table/view/function/index/schema reference across every
+statement in the file, DDL or DML alike.
+
+A file whose schema(s) can't be determined -- content sqlglot can't parse at
+all, or with no table/schema reference in it (e.g. a DO block touching no
+table) -- is treated the same as an untagged file for `-- area:`: `only`
+filters always keep it, `exclude` filters never drop it. Being unable to
+prove a file belongs to an excluded schema is not the same as proving it
+doesn't, so this errs toward keeping the file in scope rather than silently
+dropping it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import sqlglot
+import sqlglot.expressions as exp
+
+from .dialect import Dialect, POSTGRES, SYSTEM_SCHEMAS
+from .sql_text import strip_line_comments
+
+_CREATE_SCHEMA_RE = re.compile(
+    r"CREATE\s+SCHEMA\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:AUTHORIZATION\s+)?\"?(\w+)\"?", re.IGNORECASE
+)
+_QUALIFIED_REF_RE = re.compile(r"\b(\w+)\.\w+")
+
+
+def _regex_fallback(sql: str) -> frozenset[str]:
+    """Crude schema scan used when sqlglot can't parse `sql` at all, or found
+    no reference. Errs toward over-matching (any `schema.name`-shaped token)
+    rather than under-matching -- a false positive here only keeps a file in
+    scope for one extra schema filter, where a false negative would silently
+    drop it from an `only` filter. Comments are stripped first so a schema
+    merely *mentioned* in one (e.g. "-- see billing.invoice for context")
+    isn't mistaken for a real reference; string literals are left as-is
+    (matching one inside a literal is the same over-matching tradeoff as
+    above, not worth the complexity of also blanking them out)."""
+    stripped = strip_line_comments(sql)
+    schemas = set(_CREATE_SCHEMA_RE.findall(stripped))
+    schemas.update(m.group(1) for m in _QUALIFIED_REF_RE.finditer(stripped))
+    return frozenset(s for s in schemas if s.lower() not in SYSTEM_SCHEMAS)
+
+
+def sql_schemas(content: str, dialect: Dialect = POSTGRES) -> frozenset[str]:
+    """Schema names referenced anywhere in `content`: every table/view/
+    function/index reference's schema (its `dialect.default_schema` when
+    unqualified), plus any `CREATE SCHEMA name`. Falls back to a regex scan
+    when sqlglot can't parse the content, or finds no reference at all."""
+    try:
+        exprs = sqlglot.parse(content, dialect=dialect.sqlglot_name, error_level=sqlglot.ErrorLevel.IGNORE)
+    except Exception:  # noqa: BLE001
+        return _regex_fallback(content)
+
+    schemas: set[str] = set()
+    for e in exprs:
+        if e is None:
+            continue
+        for t in e.find_all(exp.Table):
+            # T-SQL's `EXEC('...dynamic sql...')` parses as a Table subquery
+            # whose "name" is the whole literal string, not a real
+            # identifier -- e.g. a quoted "CREATE SCHEMA app". Guard against
+            # treating that as a schema-qualified (or default-schema) table
+            # reference by rejecting a name containing whitespace -- a real
+            # identifier, quoted or not (even one with hyphens or other
+            # punctuation), never has any, while embedded SQL text always
+            # does. Still accepts an empty name, the legitimate shape
+            # sqlglot gives a bare `CREATE SCHEMA x` (whose schema name ends
+            # up in `db`, not `this`).
+            if t.name and re.search(r"\s", t.name):
+                continue
+            db_node = t.args.get("db")
+            name = db_node.name if db_node else dialect.default_schema
+            if name.lower() not in SYSTEM_SCHEMAS:
+                schemas.add(name)
+
+    if not schemas:
+        return _regex_fallback(content)
+    return frozenset(schemas)
+
+
+def file_schemas(path: Path, dialect: Dialect = POSTGRES) -> frozenset[str]:
+    """Schema names referenced in the file at `path`."""
+    return sql_schemas(path.read_text(encoding="utf-8"), dialect)
+
+
+def schema_allowed(
+    schemas: frozenset[str],
+    *,
+    only: frozenset[str] | None = None,
+    exclude: frozenset[str] | None = None,
+) -> bool:
+    """Whether a file that references `schemas` passes an `only`/`exclude` filter."""
+    if exclude and schemas & exclude:
+        return False
+    if only and schemas and not (schemas & only):
+        return False
+    return True
+
+
+def filter_by_schema(
+    paths: list[Path],
+    *,
+    only: frozenset[str] | None = None,
+    exclude: frozenset[str] | None = None,
+    dialect: Dialect = POSTGRES,
+) -> list[Path]:
+    """`paths` restricted by an `only`/`exclude` schema filter. Returns `paths`
+    unchanged (no file reads) when neither filter is set."""
+    if not only and not exclude:
+        return paths
+    return [p for p in paths if schema_allowed(file_schemas(p, dialect), only=only, exclude=exclude)]

pgdevkit/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/sql_text.py

@@ -0,0 +1,56 @@
+"""Small text-level SQL helpers shared by modules that can't import each
+other directly (`migrate.py` imports `schemas.py`, so `schemas.py` can't
+import back from `migrate.py`)."""
+
+from __future__ import annotations
+
+import re
+
+
+def strip_line_comments(sql: str) -> str:
+    """Drop '--' line comments, respecting string literals and $$...$$ blocks."""
+    buf: list[str] = []
+    i = 0
+    in_string = False
+    in_line_comment = False
+    dollar_tag: str | None = None
+
+    while i < len(sql):
+        c = sql[i]
+        if in_line_comment:
+            if c == "\n":
+                in_line_comment = False
+                buf.append(c)
+        elif dollar_tag is not None:
+            buf.append(c)
+            if c == "$" and sql[i:i + len(dollar_tag)] == dollar_tag:
+                buf.extend(list(dollar_tag[1:]))
+                i += len(dollar_tag)
+                dollar_tag = None
+                continue
+        elif in_string:
+            if c == "'" and i + 1 < len(sql) and sql[i + 1] == "'":
+                buf.append(c)
+                buf.append(sql[i + 1])
+                i += 2
+                continue
+            elif c == "'":
+                in_string = False
+            buf.append(c)
+        elif c == "-" and i + 1 < len(sql) and sql[i + 1] == "-":
+            in_line_comment = True
+        elif c == "$":
+            m = re.match(r"\$([A-Za-z0-9_]*)\$", sql[i:])
+            if m:
+                dollar_tag = m.group(0)
+                buf.extend(list(dollar_tag))
+                i += len(dollar_tag)
+                continue
+            buf.append(c)
+        elif c == "'":
+            in_string = True
+            buf.append(c)
+        else:
+            buf.append(c)
+        i += 1
+    return "".join(buf)

pgdevkit/testdb/api.py

@@ -68,24 +68,59 @@ async def _drop_database(db_name: str) -> None:
         await con.execute(SQL("DROP DATABASE IF EXISTS {}").format(Identifier(db_name)))
 
 
-async def _apply(config: ProjectConfig, db_name: str, force_reset: bool) -> None:
+async def _apply(
+    config: ProjectConfig,
+    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,
+    exclude_schemas: frozenset[str] | None = None,
+) -> None:
     async with await psycopg.AsyncConnection.connect(_db_dsn(db_name), autocommit=True) as con:
         await apply_schema(
             con,
             config.root / config.database_dir,
             extensions=config.extensions,
             force_reset=force_reset,
+            env=env,
+            areas=areas,
+            exclude_areas=exclude_areas,
+            schemas=schemas,
+            exclude_schemas=exclude_schemas,
         )
 
 
-def ensure_testdb(project_root: Path | None = None, force_reset: bool = False) -> dict[str, str]:
+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,
+    exclude_schemas: frozenset[str] | None = None,
+) -> dict[str, str]:
     """Ensure the shared container is running, this workspace's database
     exists, and its schema is applied. Returns the {PREFIX}POSTGRES_* env
     vars for this workspace (or the mssql equivalent's env vars, per
-    `config.engine`)."""
+    `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
+    what gets (re)applied."""
     config, db_name = _resolve(project_root)
     if config.engine == "mssql":
-        return _mssql_api().ensure_testdb(config, db_name, force_reset)
+        return _mssql_api().ensure_testdb(
+            config, db_name, force_reset,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+        )
 
     ensure_container()
 
@@ -93,16 +128,30 @@ def ensure_testdb(project_root: Path | None = None, force_reset: bool = False) -
         if force_reset:
             await _drop_database(db_name)
         await _ensure_database(db_name)
-        await _apply(config, db_name, force_reset)
+        await _apply(
+            config, db_name, force_reset,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+        )
 
     asyncio.run(_run())
     return _env_for(config, db_name)
 
 
-def reset_testdb(project_root: Path | None = None) -> dict[str, str]:
+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,
+    exclude_schemas: frozenset[str] | None = None,
+) -> dict[str, str]:
     """Drop and recreate only this workspace's database, then reapply
     schema and seed data."""
-    return ensure_testdb(project_root, force_reset=True)
+    return ensure_testdb(
+        project_root, force_reset=True,
+        env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+    )
 
 
 def clean_testdb(project_root: Path | None = None, all: bool = False) -> None:

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
@@ -101,7 +102,17 @@ async def _insert_test_data(json_file: Path, table: str, force_reset: bool, conn
     await asyncio.to_thread(_run)
 
 
-async def _apply(config: ProjectConfig, db_name: str, force_reset: bool) -> None:
+async def _apply(
+    config: ProjectConfig,
+    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,
+    exclude_schemas: frozenset[str] | None = None,
+) -> None:
     def _connect() -> Any:
         return mssql_python.connect(_db_dsn(db_name), autocommit=True)
 
@@ -110,30 +121,48 @@ async def _apply(config: ProjectConfig, db_name: str, force_reset: bool) -> None
         database_dir = config.root / config.database_dir
         if not database_dir.is_dir():
             return
-        for file, sql in _iter_sql_files(database_dir, MSSQL):
+        for file, sql in _iter_sql_files(
+            database_dir, MSSQL,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+        ):
             for batch in query.split_tsql_batches(sql):
 
                 def _exec(batch: str = batch) -> None:
                     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)
 
 
-def ensure_testdb(config: ProjectConfig, db_name: str, force_reset: bool) -> dict[str, str]:
+def ensure_testdb(
+    config: ProjectConfig,
+    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,
+    exclude_schemas: frozenset[str] | None = None,
+) -> dict[str, str]:
     ensure_mssql_container()
 
     async def _run() -> None:
         if force_reset:
             await _drop_database(db_name)
         await _ensure_database(db_name)
-        await _apply(config, db_name, force_reset)
+        await _apply(
+            config, db_name, force_reset,
+            env=env, areas=areas, exclude_areas=exclude_areas, schemas=schemas, exclude_schemas=exclude_schemas,
+        )
 
     asyncio.run(_run())
     return _env_for(config, db_name)

pgdevkit/testdb/schema.py

@@ -13,9 +13,12 @@ import sqlglot.expressions as exp
 from psycopg.rows import dict_row
 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
+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
 
 logger = logging.getLogger(__name__)
 logging.getLogger("sqlglot").setLevel(logging.ERROR)
@@ -38,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:
@@ -65,16 +68,14 @@ _SCHEMA_QUALIFIED_TYPES = {
 }
 
 
-# Schemas that hold system catalog views/tables, never a file this project
-# manages -- a reference to one is never a real cross-file dependency to
-# wait for. Matters most for T-SQL, where "IF NOT EXISTS (SELECT ... FROM
-# sys.schemas/sys.tables/sys.objects ...) BEGIN CREATE ... END" is the
-# idiomatic idempotency-guard pattern (T-SQL has no native "CREATE TABLE IF
-# NOT EXISTS"/"CREATE SCHEMA IF NOT EXISTS"), so without this exclusion
-# nearly every T-SQL file would pick up a spurious, never-resolvable
-# dependency on "sys.*" and get shuffled into the delayed-retry path, whose
-# reverse-order resolution can then apply files out of their intended order.
-_SYSTEM_SCHEMAS = {"pg_catalog", "information_schema", "sys"}
+# SYSTEM_SCHEMAS (see dialect.py) matters most here for T-SQL, where
+# "IF NOT EXISTS (SELECT ... FROM sys.schemas/sys.tables/sys.objects ...)
+# BEGIN CREATE ... END" is the idiomatic idempotency-guard pattern (T-SQL has
+# no native "CREATE TABLE IF NOT EXISTS"/"CREATE SCHEMA IF NOT EXISTS"), so
+# without this exclusion nearly every T-SQL file would pick up a spurious,
+# never-resolvable dependency on "sys.*" and get shuffled into the
+# delayed-retry path, whose reverse-order resolution can then apply files
+# out of their intended order.
 
 _DECLARE_RE = re.compile(
     r"CREATE\s+(?:OR\s+REPLACE\s+)?(?:TABLE|VIEW|FUNCTION|PROCEDURE|TYPE|SCHEMA)\s+(\w+\.\w+)", re.IGNORECASE
@@ -89,7 +90,7 @@ def _get_sql_deps_regex_fallback(sql: str) -> set[str]:
     is fine."""
     declares = set(_DECLARE_RE.findall(sql))
     deps = set(_DEPEND_RE.findall(sql))
-    deps = {d for d in deps if d.split(".", 1)[0].lower() not in _SYSTEM_SCHEMAS}
+    deps = {d for d in deps if d.split(".", 1)[0].lower() not in SYSTEM_SCHEMAS}
     return deps - declares
 
 
@@ -109,7 +110,7 @@ def _get_sql_deps(sql: str, dialect: Dialect = POSTGRES) -> set[str]:
         for t in e.find_all(exp.Table):
             db_node = t.args.get("db")
             if t.args.get("this") is not None and db_node is not None:
-                if db_node.name.lower() in _SYSTEM_SCHEMAS:
+                if db_node.name.lower() in SYSTEM_SCHEMAS:
                     continue
                 # exp.table_name(), not str(t): str() includes " AS alias" for
                 # an aliased reference (e.g. "FROM editing.visit v"), which
@@ -119,8 +120,25 @@ def _get_sql_deps(sql: str, dialect: Dialect = POSTGRES) -> set[str]:
     return deps
 
 
-def _iter_sql_files(database_dir: Path, dialect: Dialect = POSTGRES):
-    """Yield (Path, sql_content) pairs in dependency-safe execution order."""
+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,
+    exclude_schemas: frozenset[str] | None = None,
+):
+    """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`/
+    `parse_directory` make for migrations/database code files."""
     files: list[Path] = []
     for root, dirs, dbfiles in os.walk(database_dir):
         dirs[:] = [d for d in dirs if d not in IGNORED_DIR_NAMES]
@@ -129,8 +147,9 @@ def _iter_sql_files(database_dir: Path, dialect: Dialect = POSTGRES):
         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]] = []
@@ -138,10 +157,16 @@ def _iter_sql_files(database_dir: Path, dialect: Dialect = POSTGRES):
 
     for file in sorted(files, key=lambda p: (_get_type_order(p), p.name)):
         content = file.read_text(encoding="utf-8")
+        if (areas or exclude_areas) and not area_allowed(parse_areas(content), only=areas, exclude=exclude_areas):
+            continue
+        if (schemas or exclude_schemas) and not schema_allowed(
+            sql_schemas(content, dialect), only=schemas, exclude=exclude_schemas
+        ):
+            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):
@@ -242,14 +267,27 @@ 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,
+    exclude_schemas: frozenset[str] | None = None,
 ) -> None:
     """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
-    `database_dir` must reflect the current, final schema on their own."""
+    `database_dir` must reflect the current, final schema on their own.
+
+    `areas`/`exclude_areas` and `schemas`/`exclude_schemas` restrict which
+    files get applied, the same as `pgdevkit migrate`/`compare` — handy for
+    standing up a test DB scoped to one area or schema instead of the whole
+    project."""
     await con.set_autocommit(True)
     for extension in extensions:
         await con.execute(SQL("CREATE EXTENSION IF NOT EXISTS {e}").format(e=Identifier(extension)))
@@ -258,14 +296,24 @@ 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):
+    for file, sql in _iter_sql_files(
+        database_dir,
+        dialect,
+        env=env,
+        areas=areas,
+        exclude_areas=exclude_areas,
+        schemas=schemas,
+        exclude_schemas=exclude_schemas,
+    ):
         try:
             await _apply(file, sql)
         except Exception as e:  # noqa: BLE001

{pgdevkit-0.4.0.dist-info → pgdevkit-0.6.0.dist-info}/METADATA

@@ -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.dist-info → pgdevkit-0.6.0.dist-info}/RECORD

@@ -1,16 +1,19 @@
 pgdevkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pgdevkit/areas.py,sha256=iEmOObYxhZyDFl2iQVf1OQJN4JtZ-H3EL-qMfxYZdSQ,2203
-pgdevkit/cli.py,sha256=gZt4BlEuw4hhMq0dyMRCe1a3-Ci23yUDg-6Sc_H-OSo,19193
+pgdevkit/cli.py,sha256=vCxea9c4PxfkpKyUJoMGdUaiLD1bwGtRVDgXbT4XAZc,21826
 pgdevkit/connection.py,sha256=x49aXKsJfyOsDTlqURs9idQUWaD-RO-XdtAqsG3guBI,4000
-pgdevkit/dialect.py,sha256=PL5Y8QPZNnoHIvAPomczGQX7IjZwxMgKGuREX80SwFA,3105
+pgdevkit/dialect.py,sha256=gZwn4UNZ8PYBPC4CnYnfA95C7ppv7sWmpZSF8pjSPVw,3659
 pgdevkit/diff.py,sha256=Y2TbjwpFHYik0wZDhoI--9EAlIfp4AUg8BUubkOXyUg,9295
+pgdevkit/envtag.py,sha256=FdRqjLRdS9O9LSvoEzrRsFNeqiyZTLLzFgEkIirJyZI,2006
 pgdevkit/fetch_missing.py,sha256=vb8hXWBKMWgqkxHso5SuhX9l6rxNXfaybAEsajPLYow,8495
 pgdevkit/introspect.py,sha256=QYIlRuZk4lBHGxaW7zb_kFRIuNfi3AxH0Q2F_GKzlVI,7870
 pgdevkit/lakebase.py,sha256=0PABOk4p-2klLTY8QAUibQf9QeyNHKywUWEWGdkUY8k,3165
-pgdevkit/migrate.py,sha256=_8U-TG4MRZQasdm0UticdbM4rhthoZ9QSF9L4NX3Xq8,14057
+pgdevkit/migrate.py,sha256=AnlxOy6Sk0iQlGq5lHYIaIBDwljO9EhCVwDkyRZmvQQ,13499
 pgdevkit/models.py,sha256=dAZ8f7pgDsxoLVrDWsM4h0qwJ0pOzXDdWMGsnjrW80E,2103
 pgdevkit/mssql_introspect.py,sha256=Fhv1N4zHYEDZ0PEy0OIpawUmoIFeoi-Lm97pmEyDmYY,12031
-pgdevkit/parser.py,sha256=RWtCDx98OU3T7fmEA7ZZN82Fqo6wlbv03O_BEKwZGQo,16561
+pgdevkit/parser.py,sha256=FmXL6-eCFzP_0FNyTrg4wF3aPzPeq7re2i0xvrSJIcs,16885
+pgdevkit/schemas.py,sha256=zZsg3m9FtI7IUG8e8HfRruCh6-O6bdpbA7Kjnk3AYJg,5053
+pgdevkit/sql_text.py,sha256=ednfdfxGBTWYqQ5Q3l3Zv9vrjjFmLiRlGKyq3tcozco,1744
 pgdevkit/backends/__init__.py,sha256=ys4VBglMImRtnudJBlTPVBNevDMRippuwAJOz0yRKiY,610
 pgdevkit/backends/base.py,sha256=0i0KLCYVWlpVFnUoq2t0LCRE_abyWPPIhw1bMxmW9KQ,1048
 pgdevkit/backends/mssql.py,sha256=pocBdoQ14ZnYLutXEOStVmJvmpclXGs3gaxHN0uJCMk,1068
@@ -25,22 +28,22 @@ pgdevkit/db/mssql_crud.py,sha256=yN4izZ0fsFwAs14008JECHH4dqjNbdHUHGEG8kidyNs,113
 pgdevkit/db/mssql_sql.py,sha256=DO3UMsTFN9pg0tNdaPGb0wf6lWlHGcqwqzkrGVhJF2g,2292
 pgdevkit/testdb/__init__.py,sha256=LpdC2XMBxqn9JrGmXhIho3sK8O1aNo_aD7leKyBr-Lo,204
 pgdevkit/testdb/_docker.py,sha256=kj_0xrGO_mxHlK83ilsB-yE0ELX1kpH22ruYrS-N3iU,1467
-pgdevkit/testdb/api.py,sha256=l1hqX7lLLLzk3hMgbtg7EpbZ7SdwPVPwupBCPu3xRRg,6038
+pgdevkit/testdb/api.py,sha256=K-y4O6nC3z_gr9LtVHe-v-T-1UjhmFMw1j-dLa0FcnY,7680
 pgdevkit/testdb/config.py,sha256=vjcDr3jH3-5VakNAEMqQu_ZHPXiYIvM1_BSETSJW5QU,2164
 pgdevkit/testdb/constants.py,sha256=xi8uIoEgN9LrRkr41j3mmWB9PqqU0r8aCUb2JJXBAs0,1165
 pgdevkit/testdb/container.py,sha256=kELTb6qaECAO9a5Bwvx1btv6i5QKRFAa9PX6auWymNo,2807
 pgdevkit/testdb/naming.py,sha256=Kyk5qEfxUkbggUG5bD7U7CJ_kAET332VPQNB-O5kvTY,1318
 pgdevkit/testdb/query.py,sha256=iYpy_EoYIq5USfwr6pNktmDjcGi_yQx0vHvjHZNGRr0,3854
-pgdevkit/testdb/schema.py,sha256=0N0Q_BQGh2kuAqa_j-DdbjYlTUOOZSEtaoUOApxQg_Y,12049
+pgdevkit/testdb/schema.py,sha256=tLd5ovQSXdFoOOl9KWBI35wZHqhD_XIgWfwBVDIZJj0,13838
 pgdevkit/testdb/mssql/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
-pgdevkit/testdb/mssql/api.py,sha256=42RAuJeiZlK1WJaTIYoj6l8GEAbEyt6LgAoF3G2jxnw,7537
+pgdevkit/testdb/mssql/api.py,sha256=sFVSSQbN3Jk62YRQkT6atLSsl1-8hJVjCko5goOQkio,8374
 pgdevkit/testdb/mssql/constants.py,sha256=7n_NcYuhabbtb18CqG_H_rRbI7Wb_qu_l4nKk3281vI,2847
 pgdevkit/testdb/mssql/container.py,sha256=_rG0AMDXrNwok_E60Xai0DZdRiZ6Ba1j3GaLUnSAueg,3364
-pgdevkit/docs/database-layout.md,sha256=4GBwv4PA2cKHl2BxwLd-awLOe9he9ie4X6CpQWjIEyI,6820
-pgdevkit/skills/pgdevkit/SKILL.md,sha256=6uxe6BQwOLexGiBpf00VTFTHOiWJo5k2Qqzu172rb4I,12156
+pgdevkit/docs/database-layout.md,sha256=eqsEWuA0Vuqj5jRCXx24J45D1EjnDe3KNUQLxpdsW9M,7454
+pgdevkit/skills/pgdevkit/SKILL.md,sha256=ADqEaQtMJPUUAiieqokzUUmIf27bWWJNB1ZvsfgiKAE,12205
 pgdevkit/skills/pgdevkit/references/dynamic-sql.md,sha256=aTR1sx81moiTwaMaiOecaqk-9rT8y5Zxz7W1BoC3vK0,2774
 pgdevkit/skills/pgdevkit/references/temporal-tables.md,sha256=LwZnItvQWI7bB0oRHxIfUc0ynnq7N0V5Mnv-QHvFN3Q,1364
-pgdevkit-0.4.0.dist-info/METADATA,sha256=KgPFnAsptfih47V8mmLRNJ43aKBq013EWMH2M3EgDhs,15524
-pgdevkit-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-pgdevkit-0.4.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
-pgdevkit-0.4.0.dist-info/RECORD,,
+pgdevkit-0.6.0.dist-info/METADATA,sha256=_aDm11tWJ9KphnjydC8Wq2nAKNkHd_xprRYiztnlPmc,18982
+pgdevkit-0.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pgdevkit-0.6.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
+pgdevkit-0.6.0.dist-info/RECORD,,