Add workspace_db_names(), document orphaned-DB cleanup in README

README.md

@@ -231,6 +231,13 @@ belongs to a live worktree too:
 extra_db_suffixes = ["_myservice"]
 ```
 
+`pgdevkit.testdb.workspace_db_names(project_root=None)` is the
+single-workspace analog of `find_orphaned_dbs()`: it returns the exact set
+of DB names (main + any `extra_db_suffixes`) owned by the branch currently
+checked out at `project_root`, without touching Postgres or diffing against
+other worktrees. Useful for a caller that's about to remove one specific
+worktree and wants to know exactly which DB(s) go with it.
+
 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

pgdevkit/testdb/__init__.py

@@ -7,6 +7,7 @@
     run_sql,
     shell_argv,
     status,
+    workspace_db_names,
 )
 
 __all__ = [
@@ -18,4 +19,5 @@
     "run_sql",
     "shell_argv",
     "status",
+    "workspace_db_names",
 ]

pgdevkit/testdb/api.py

@@ -189,6 +189,20 @@ def find_orphaned_dbs(project_root: Path | None = None) -> list[str]:
     return asyncio.run(_find_orphaned_dbs(config))
 
 
+def workspace_db_names(project_root: Path | None = None) -> frozenset[str]:
+    """Every DB name this exact workspace (the branch currently checked out
+    at `project_root`) owns: its main workspace DB plus one
+    `<main>{suffix}` sibling per configured `extra_db_suffixes` entry. The
+    single-workspace analog of what `find_orphaned_dbs` computes across
+    every *live* worktree -- for a caller that wants "which DBs belong to
+    this one worktree right now" (e.g. to drop them before removing the
+    worktree itself), as opposed to a whole-project orphan sweep. Engine
+    (postgres/mssql) doesn't affect naming, so this doesn't dispatch on it."""
+    config = load_config(project_root)
+    branch = current_branch(config.root)
+    return frozenset(expected_db_names(config, [branch]))
+
+
 def clean_testdb(project_root: Path | None = None, all: bool = False, orphaned: bool = False) -> None:
     """Drop this workspace's database. With all=True, drop every database
     belonging to this project (matched by its name-slug prefix), across

pyproject.toml

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

tests/testdb/test_api.py

@@ -9,7 +9,14 @@
 import pytest
 
 from pgdevkit.testdb import constants
-from pgdevkit.testdb.api import clean_testdb, ensure_testdb, find_orphaned_dbs, reset_testdb, status
+from pgdevkit.testdb.api import (
+    clean_testdb,
+    ensure_testdb,
+    find_orphaned_dbs,
+    reset_testdb,
+    status,
+    workspace_db_names,
+)
 from pgdevkit.testdb.config import load_config
 from pgdevkit.testdb.naming import slugify
 from tests.testdb.conftest import requires_podman
@@ -204,3 +211,34 @@ def test_find_orphaned_dbs_respects_extra_db_suffixes(
         assert find_orphaned_dbs(repo) == [stray_db]
     finally:
         clean_testdb(repo, all=True)
+
+
+def test_workspace_db_names_is_just_the_main_db_with_no_extra_suffixes(
+    project_factory: Callable[..., Path],
+):
+    project = project_factory("wdntest", "main")
+    assert workspace_db_names(project) == {status(project)["database"]}
+
+
+def test_workspace_db_names_includes_configured_extra_db_suffixes(
+    project_factory: Callable[..., Path],
+):
+    project = project_factory("wdntest2", "main")
+    pyproject = project / "pyproject.toml"
+    pyproject.write_text(
+        pyproject.read_text(encoding="utf-8").rstrip("\n") + '\nextra_db_suffixes = ["_sibling"]\n',
+        encoding="utf-8",
+    )
+    main_db = status(project)["database"]
+    assert workspace_db_names(project) == {main_db, f"{main_db}_sibling"}
+
+
+def test_workspace_db_names_differs_from_a_sibling_worktrees_branch(
+    worktree_project_factory: Callable[..., tuple[Path, Callable[[str], Path]]],
+):
+    repo, add_worktree = worktree_project_factory("wdntest3")
+    feature = add_worktree("feature")
+
+    assert workspace_db_names(repo) == {status(repo)["database"]}
+    assert workspace_db_names(feature) == {status(feature)["database"]}
+    assert workspace_db_names(repo) != workspace_db_names(feature)