pgdevkit 0.3.8__tar.gz → 0.5.0__tar.gz

pgdevkit-0.5.0/.github/workflows/auto-release.yml

@@ -0,0 +1,83 @@
+# Auto-tags, cuts a GitHub Release, and dispatches a PyPI publish whenever
+# pyproject.toml's version changes on main and the Python Test workflow has
+# passed for that commit. No manual "cut a release" step needed.
+#
+# Two GitHub Actions quirks shaped this design -- both hit and confirmed the
+# hard way, so read before "simplifying" this:
+#
+# 1. GitHub Actions doesn't fire other workflows' triggers (release:
+#    published included) for events performed with the automatic
+#    GITHUB_TOKEN, to prevent recursive runs. So creating the release here
+#    would NOT, on its own, trigger python-publish.yml's `release: published`
+#    listener. workflow_dispatch is the documented exception to that rule --
+#    an API-triggered workflow_dispatch DOES start a new run even when
+#    triggered by GITHUB_TOKEN -- so this dispatches python-publish.yml
+#    directly instead of relying on the release event to cascade.
+#
+# 2. The obvious alternative -- calling python-publish.yml's job directly via
+#    workflow_call instead of dispatching it as a separate run -- avoids (1)
+#    entirely, but breaks PyPI's OIDC trusted publishing: PyPI explicitly
+#    does not support trusted publishing from reusable/called workflows (the
+#    token's claims show a "reusable workflow" parent chain that PyPI's
+#    trusted-publisher matching rejects). So python-publish.yml must stay a
+#    plain, directly-triggered top-level workflow -- no workflow_call trigger
+#    on it, and nothing here should invoke it as `uses:`.
+
+name: Auto Release
+
+on:
+  workflow_run:
+    workflows: ["Python Test"]
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          version=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "([^"]+)"/\1/')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Skip if this version is already on PyPI
+        id: check
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          if curl -fsS https://pypi.org/pypi/pgdevkit/json | jq -e --arg v "$version" '.releases[$v] != null' >/dev/null; then
+            echo "published=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "published=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create tag and GitHub release, if missing
+        if: steps.check.outputs.published == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! gh release view "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            gh release create "v${{ steps.version.outputs.version }}" \
+              --title "v${{ steps.version.outputs.version }}" \
+              --target "${{ github.event.workflow_run.head_sha }}" \
+              --generate-notes
+          fi
+
+      - name: Dispatch PyPI publish
+        if: steps.check.outputs.published == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run python-publish.yml --ref main

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.3.8
+Version: 0.5.0
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -79,6 +79,94 @@ 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 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:
+
+```sql
+-- area: billing
+CREATE TABLE billing.invoices (id int primary key);
+```
+
+A file can declare more than one area, either comma-separated on one line
+(`-- area: billing, reporting`) or across several `-- area:` lines — the
+declared areas union. The directive is only recognized in the file's leading
+comment block (blank lines and `--` comments at the very top, stopping at the
+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.
+
+#### 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.
+
+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
+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.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.
+
 ## `pgdb testdb`
 
 Manages a single shared, Podman-backed Postgres container for local tests
@@ -109,6 +197,13 @@ def ensure_test_postgres():
 
 CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`.
 
+`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_TESTDB_USER`, `PGDEVKIT_TESTDB_PASSWORD`. Before touching the
@@ -259,3 +354,29 @@ async with pool.connection() as con:
     widget = await pg_retrieve(con, Widget, {"id": 1})
     await pg_upsert(con, Widget(id=1, name="thing"), Widget)
 ```
+
+## Releasing
+
+Bump `version` in `pyproject.toml` as part of your PR, same as any other
+change. Once that PR merges to `main` and the `Python Test` workflow passes
+for that commit, `.github/workflows/auto-release.yml` automatically tags it
+`vX.Y.Z`, cuts a GitHub Release (skipping if that version was already
+released, e.g. a merge that didn't touch the version), and dispatches
+`python-publish.yml` to publish it to PyPI — no manual release step, and no
+extra secret to configure. Two non-obvious GitHub Actions quirks shaped
+this (see the comments at the top of `auto-release.yml` for the full
+reasoning, since both were hit and confirmed the hard way):
+
+- A release created with the default `GITHUB_TOKEN` does **not** trigger
+  other workflows' `release: published` listeners (an anti-recursion
+  safeguard) — `workflow_dispatch` is the documented exception, so
+  `auto-release.yml` dispatches `python-publish.yml` directly (`gh workflow
+  run`) instead of relying on the release to cascade into it.
+- `python-publish.yml` deliberately stays a plain, directly-triggered
+  top-level workflow rather than something `auto-release.yml` calls via
+  `workflow_call`: PyPI's OIDC trusted publishing does not support
+  reusable/called workflows and silently rejects the token in that shape.
+
+`workflow_dispatch` (or an actual GitHub UI release) on `python-publish.yml`
+still works as a manual fallback if you ever need to re-publish a version
+without going through `auto-release.yml`.

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

@@ -58,6 +58,94 @@ 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 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:
+
+```sql
+-- area: billing
+CREATE TABLE billing.invoices (id int primary key);
+```
+
+A file can declare more than one area, either comma-separated on one line
+(`-- area: billing, reporting`) or across several `-- area:` lines — the
+declared areas union. The directive is only recognized in the file's leading
+comment block (blank lines and `--` comments at the very top, stopping at the
+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.
+
+#### 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.
+
+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
+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.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.
+
 ## `pgdb testdb`
 
 Manages a single shared, Podman-backed Postgres container for local tests
@@ -88,6 +176,13 @@ def ensure_test_postgres():
 
 CLI: `pgdb testdb up|reset|run-sql|status|shell|clean`.
 
+`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_TESTDB_USER`, `PGDEVKIT_TESTDB_PASSWORD`. Before touching the
@@ -238,3 +333,29 @@ async with pool.connection() as con:
     widget = await pg_retrieve(con, Widget, {"id": 1})
     await pg_upsert(con, Widget(id=1, name="thing"), Widget)
 ```
+
+## Releasing
+
+Bump `version` in `pyproject.toml` as part of your PR, same as any other
+change. Once that PR merges to `main` and the `Python Test` workflow passes
+for that commit, `.github/workflows/auto-release.yml` automatically tags it
+`vX.Y.Z`, cuts a GitHub Release (skipping if that version was already
+released, e.g. a merge that didn't touch the version), and dispatches
+`python-publish.yml` to publish it to PyPI — no manual release step, and no
+extra secret to configure. Two non-obvious GitHub Actions quirks shaped
+this (see the comments at the top of `auto-release.yml` for the full
+reasoning, since both were hit and confirmed the hard way):
+
+- A release created with the default `GITHUB_TOKEN` does **not** trigger
+  other workflows' `release: published` listeners (an anti-recursion
+  safeguard) — `workflow_dispatch` is the documented exception, so
+  `auto-release.yml` dispatches `python-publish.yml` directly (`gh workflow
+  run`) instead of relying on the release to cascade into it.
+- `python-publish.yml` deliberately stays a plain, directly-triggered
+  top-level workflow rather than something `auto-release.yml` calls via
+  `workflow_call`: PyPI's OIDC trusted publishing does not support
+  reusable/called workflows and silently rejects the token in that shape.
+
+`workflow_dispatch` (or an actual GitHub UI release) on `python-publish.yml`
+still works as a manual fallback if you ever need to re-publish a version
+without going through `auto-release.yml`.

pgdevkit-0.5.0/pgdevkit/areas.py

@@ -0,0 +1,64 @@
+"""Optional `-- area: NAME[, NAME...]` tag recognized in the leading comment
+block of a migration file or a `database/` code file (blank lines and `--`
+comments at the very top, stopping at the first real statement — like a file
+header). A file may declare more than one area, either as a comma-separated
+list on one line or across several `-- area:` lines (the areas union).
+
+A file with no such directive is "untagged" and is treated as shared/common:
+`only` filters always keep untagged files, and `exclude` filters never drop
+them — only a file that explicitly declares an excluded area is dropped.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_AREA_LINE = re.compile(r"^\s*--\s*area\s*:\s*(.+?)\s*$", re.IGNORECASE)
+
+
+def parse_areas(content: str) -> frozenset[str]:
+    """Area names declared in `content`'s leading comment block."""
+    areas: set[str] = set()
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if not stripped.startswith("--"):
+            break
+        m = _AREA_LINE.match(stripped)
+        if m:
+            areas.update(a.strip() for a in m.group(1).split(",") if a.strip())
+    return frozenset(areas)
+
+
+def file_areas(path: Path) -> frozenset[str]:
+    """Area names declared in the file at `path`."""
+    return parse_areas(path.read_text(encoding="utf-8"))
+
+
+def area_allowed(
+    areas: frozenset[str],
+    *,
+    only: frozenset[str] | None = None,
+    exclude: frozenset[str] | None = None,
+) -> bool:
+    """Whether a file that declares `areas` passes an `only`/`exclude` filter."""
+    if exclude and areas & exclude:
+        return False
+    if only and areas and not (areas & only):
+        return False
+    return True
+
+
+def filter_by_area(
+    paths: list[Path],
+    *,
+    only: frozenset[str] | None = None,
+    exclude: frozenset[str] | None = None,
+) -> list[Path]:
+    """`paths` restricted by an `only`/`exclude` area 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 area_allowed(file_areas(p), only=only, exclude=exclude)]

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

@@ -23,6 +23,29 @@ app = typer.Typer(name="pgdb", help="PostgreSQL database schema tools")
 console = Console()
 err_console = Console(stderr=True)
 
+_AREA_OPTION = typer.Option(
+    [], "--area", help="Restrict to files declaring this area (repeatable); untagged files always stay in scope"
+)
+_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",
+)
+
+
+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")
 app.add_typer(testdb_app, name="testdb")
 
@@ -46,12 +69,23 @@ def compare(
     ),
     report_extra_db: bool = typer.Option(False, "--report-extra-db", help="Report objects in DB but not in scripts"),
     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 or schema or exclude_schema):
+        console.print(
+            "[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:
         conninfo = build_conninfo(
@@ -71,7 +105,14 @@ def compare(
         raise typer.Exit(2)
 
     with console.status("Parsing SQL scripts..."):
-        scripts_schema = parse_directory(scripts_dir, dialect=backend.dialect)
+        scripts_schema = parse_directory(
+            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..."):
         db_schema = backend.introspect(conninfo)
@@ -110,7 +151,11 @@ def fetch_missing(
     only: list[str] = typer.Option([], "--only", help="Only fetch schema.name (repeatable); default is everything"),
 ) -> None:
     """Find tables/views/functions that exist in the database but aren't
-    tracked under scripts_dir, and reverse-engineer their DDL into new files."""
+    tracked under scripts_dir, and reverse-engineer their DDL into new files.
+
+    No --area/--exclude-area here (unlike compare/migrate): this diffs the
+    full live database against scripts, so filtering the scripts side by
+    area would misreport objects tracked under other areas as missing."""
     if not scripts_dir.is_dir():
         err_console.print(f"[red]Error:[/red] {scripts_dir} is not a directory")
         raise typer.Exit(2)
@@ -163,17 +208,33 @@ def fetch_missing(
 
 
 @testdb_app.command("up")
-def testdb_up() -> None:
+def testdb_up(
+    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(
+        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(
+    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(
+        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']}")
 
@@ -245,6 +306,10 @@ def migrate_check(
         help="schema.table recording applied migrations "
         "(default: tool.pgdevkit.migrations_table in pyproject.toml, else public.schema_migrations)",
     ),
+    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:
     """List which migration files under migrations_dir are applied vs. pending."""
     if not migrations_dir.is_dir():
@@ -253,7 +318,13 @@ 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)
+    local_files = migrate.list_migration_files(
+        migrations_dir,
+        areas=_as_set(area),
+        exclude_areas=_as_set(exclude_area),
+        schemas=_as_set(schema),
+        exclude_schemas=_as_set(exclude_schema),
+    )
     try:
         applied = migrate.applied_migrations(conninfo, tracking_table)
     except migrate.TrackingTableMissing:
@@ -292,6 +363,10 @@ def migrate_apply(
     ),
     ask: bool = typer.Option(False, "--ask", help="Show and confirm each migration before running it"),
     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,
 ) -> None:
     """Apply pending migration files, in filename order, tracking each in tracking_table."""
     if not migrations_dir.is_dir():
@@ -300,6 +375,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_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)
@@ -308,12 +385,23 @@ def migrate_apply(
         targets = [migrations_dir / file]
     else:
         try:
-            targets = migrate.pending_migrations(migrations_dir, conninfo, tracking_table)
+            targets = migrate.pending_migrations(
+                migrations_dir,
+                conninfo,
+                tracking_table,
+                areas=areas,
+                exclude_areas=exclude_areas,
+                schemas=schemas,
+                exclude_schemas=exclude_schemas,
+            )
         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)
+            targets = migrate.list_migration_files(
+                migrations_dir, areas=areas, exclude_areas=exclude_areas, schemas=schemas,
+                exclude_schemas=exclude_schemas,
+            )
 
     if not targets:
         console.print("No pending migrations.")

{pgdevkit-0.3.8 → pgdevkit-0.5.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.3.8 → pgdevkit-0.5.0}/pgdevkit/fetch_missing.py

@@ -50,7 +50,12 @@ def layer_folder_for(scripts_dir: Path, schema: str) -> Path:
 
 def find_missing_objects(scripts_dir: Path, conninfo: str) -> list[MissingObject]:
     """Tables, views, and functions that exist in the live database but
-    aren't tracked as .sql files under scripts_dir."""
+    aren't tracked as .sql files under scripts_dir.
+
+    Deliberately not area-filterable: this diffs the *full* database against
+    scripts with report_extra_db=True, so narrowing the scripts side to one
+    area would make every object tracked only under a different area look
+    "missing" too — and --write would reconstruct a duplicate file for it."""
     scripts = parse_directory(scripts_dir)
     db = introspect_db(conninfo)
     diffs = compute_diff(scripts, db, report_extra_db=True)