svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/cli/cmds/db/ops_cmds.py

@@ -0,0 +1,270 @@
+"""Database operations CLI commands.
+
+Provides CLI commands for database administration:
+- wait: Wait for database to be ready before proceeding
+- kill-queries: Terminate queries blocking a specific table
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Optional
+
+import typer
+
+
+def cmd_wait(
+    database_url: Optional[str] = typer.Option(
+        None,
+        "--url",
+        "-u",
+        help="Database URL; overrides env SQL_URL.",
+    ),
+    timeout: int = typer.Option(
+        60,
+        "--timeout",
+        "-t",
+        help="Maximum time to wait in seconds.",
+    ),
+    interval: float = typer.Option(
+        2.0,
+        "--interval",
+        "-i",
+        help="Time between connection attempts in seconds.",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress progress messages.",
+    ),
+) -> None:
+    """
+    Wait for database to be ready.
+
+    Attempts to connect to the database repeatedly until successful
+    or timeout is reached. Useful in container startup scripts.
+
+    Exit codes:
+        0: Database is ready
+        1: Timeout reached, database not ready
+    """
+    url = database_url or os.getenv("SQL_URL") or os.getenv("DATABASE_URL")
+    if not url:
+        typer.secho(
+            "ERROR: No database URL. Set --url, SQL_URL, or DATABASE_URL.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+    async def _wait() -> bool:
+        """Async wait loop."""
+        from svc_infra.health import check_database
+
+        check = check_database(url)
+        deadline = time.monotonic() + timeout
+        attempt = 0
+
+        while time.monotonic() < deadline:
+            attempt += 1
+            if not quiet:
+                typer.echo(f"Attempt {attempt}: Connecting to database...")
+
+            result = await check()
+
+            if result.status == "healthy":
+                if not quiet:
+                    typer.secho(
+                        f"✓ Database ready ({result.latency_ms:.1f}ms)",
+                        fg=typer.colors.GREEN,
+                    )
+                return True
+
+            if not quiet:
+                msg = result.message or "Connection failed"
+                typer.echo(f"  → {msg}")
+
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                await asyncio.sleep(min(interval, remaining))
+
+        return False
+
+    success = asyncio.run(_wait())
+    if not success:
+        typer.secho(
+            f"ERROR: Database not ready after {timeout}s",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+
+def cmd_kill_queries(
+    table: str = typer.Argument(
+        ...,
+        help="Table name to find blocking queries for.",
+    ),
+    database_url: Optional[str] = typer.Option(
+        None,
+        "--url",
+        "-u",
+        help="Database URL; overrides env SQL_URL.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="Show queries that would be killed without actually killing them.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Terminate immediately (pg_terminate_backend) instead of cancel (pg_cancel_backend).",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress output except errors.",
+    ),
+) -> None:
+    """
+    Kill queries blocking operations on a table.
+
+    Finds queries that hold locks on the specified table and attempts
+    to cancel or terminate them. Useful when migrations are blocked.
+
+    By default uses pg_cancel_backend (graceful). Use --force for
+    pg_terminate_backend (immediate termination).
+
+    Examples:
+        svc-infra db kill-queries users
+        svc-infra db kill-queries users --dry-run
+        svc-infra db kill-queries users --force
+    """
+    url = database_url or os.getenv("SQL_URL") or os.getenv("DATABASE_URL")
+    if not url:
+        typer.secho(
+            "ERROR: No database URL. Set --url, SQL_URL, or DATABASE_URL.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+    async def _kill_queries() -> int:
+        """Find and kill blocking queries. Returns count of killed queries."""
+        try:
+            import asyncpg
+        except ImportError:
+            typer.secho(
+                "ERROR: asyncpg not installed. Run: pip install asyncpg",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(1)
+
+        # Normalize URL for asyncpg
+        db_url = url
+        if db_url.startswith("postgres://"):
+            db_url = db_url.replace("postgres://", "postgresql://", 1)
+        if "+asyncpg" in db_url:
+            db_url = db_url.replace("+asyncpg", "")
+
+        try:
+            conn = await asyncpg.connect(db_url)
+        except Exception as e:
+            typer.secho(
+                f"ERROR: Failed to connect to database: {e}",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(1)
+
+        try:
+            # Find queries with locks on the table
+            # Uses pg_stat_activity joined with pg_locks to find blocking queries
+            find_query = """
+                SELECT DISTINCT
+                    a.pid,
+                    a.usename,
+                    a.application_name,
+                    a.state,
+                    a.query,
+                    a.query_start,
+                    l.locktype,
+                    l.mode
+                FROM pg_stat_activity a
+                JOIN pg_locks l ON a.pid = l.pid
+                WHERE l.relation = $1::regclass
+                  AND a.pid != pg_backend_pid()
+                ORDER BY a.query_start
+            """
+
+            try:
+                rows = await conn.fetch(find_query, table)
+            except asyncpg.UndefinedTableError:
+                typer.secho(
+                    f"ERROR: Table '{table}' does not exist",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(1)
+
+            if not rows:
+                if not quiet:
+                    typer.echo(f"No active queries found on table '{table}'")
+                return 0
+
+            if not quiet:
+                typer.echo(f"Found {len(rows)} query(ies) with locks on '{table}':\n")
+                for row in rows:
+                    query_preview = (row["query"] or "")[:80].replace("\n", " ")
+                    if len(row["query"] or "") > 80:
+                        query_preview += "..."
+                    typer.echo(f"  PID {row['pid']}: {query_preview}")
+                    typer.echo(f"    User: {row['usename']}, State: {row['state']}")
+                    typer.echo(f"    Lock: {row['mode']} on {row['locktype']}")
+                    typer.echo("")
+
+            if dry_run:
+                typer.echo("Dry run - no queries killed.")
+                return 0
+
+            # Kill the queries
+            kill_fn = "pg_terminate_backend" if force else "pg_cancel_backend"
+            killed = 0
+
+            for row in rows:
+                pid = row["pid"]
+                try:
+                    result = await conn.fetchval(f"SELECT {kill_fn}($1)", pid)
+                    if result:
+                        killed += 1
+                        if not quiet:
+                            action = "Terminated" if force else "Cancelled"
+                            typer.secho(f"  {action} PID {pid}", fg=typer.colors.GREEN)
+                    else:
+                        if not quiet:
+                            typer.echo(
+                                f"  PID {pid}: already finished or permission denied"
+                            )
+                except Exception as e:
+                    if not quiet:
+                        typer.secho(f"  PID {pid}: Error - {e}", fg=typer.colors.YELLOW)
+
+            if not quiet:
+                typer.echo(f"\n{killed}/{len(rows)} queries killed.")
+            return killed
+
+        finally:
+            await conn.close()
+
+    count = asyncio.run(_kill_queries())
+    if count == 0 and not dry_run:
+        # Exit with 0 even if no queries found - that's success
+        pass
+
+
+def register(app: typer.Typer) -> None:
+    """Register database operations commands with the CLI app."""
+    app.command("wait")(cmd_wait)
+    app.command("kill-queries")(cmd_kill_queries)

svc_infra/cli/cmds/db/sql/alembic_cmds.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import json
 import os
+from importlib import import_module
 from typing import List, Optional
 
 import typer
@@ -75,10 +77,16 @@ def cmd_revision(
     database_url: Optional[str] = typer.Option(
         None, help="Database URL; overrides env for this command."
     ),
-    autogenerate: bool = typer.Option(False, help="Autogenerate migrations by comparing metadata."),
-    head: Optional[str] = typer.Option("head", help="Set the head to base this revision on."),
+    autogenerate: bool = typer.Option(
+        False, help="Autogenerate migrations by comparing metadata."
+    ),
+    head: Optional[str] = typer.Option(
+        "head", help="Set the head to base this revision on."
+    ),
     branch_label: Optional[str] = typer.Option(None, help="Branch label."),
-    version_path: Optional[str] = typer.Option(None, help="Alternative versions/ path."),
+    version_path: Optional[str] = typer.Option(
+        None, help="Alternative versions/ path."
+    ),
     sql: bool = typer.Option(False, help="Don't generate Python; dump SQL to stdout."),
 ):
     """Create a new Alembic revision, either empty or autogenerated."""
@@ -94,7 +102,9 @@ def cmd_revision(
 
 
 def cmd_upgrade(
-    revision_target: str = typer.Argument("head", help="Target revision (default head)."),
+    revision_target: str = typer.Argument(
+        "head", help="Target revision (default head)."
+    ),
     database_url: Optional[str] = typer.Option(
         None, help="Database URL; overrides env for this command."
     ),
@@ -123,7 +133,11 @@ def cmd_current(
 ):
     """Display the current revision for each database."""
     apply_database_url(database_url)
-    core_current(verbose=verbose)
+    result = core_current(verbose=verbose)
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        typer.echo(str(result))
 
 
 def cmd_history(
@@ -152,7 +166,9 @@ def cmd_merge_heads(
     database_url: Optional[str] = typer.Option(
         None, help="Database URL; overrides env for this command."
     ),
-    message: Optional[str] = typer.Option(None, "-m", "--message", help="Merge revision message."),
+    message: Optional[str] = typer.Option(
+        None, "-m", "--message", help="Merge revision message."
+    ),
 ):
     """Create a merge revision for multiple heads."""
     apply_database_url(database_url)
@@ -164,8 +180,12 @@ def cmd_setup_and_migrate(
         None,
         help="Overrides env for this command. Async vs sync is auto-detected from the URL.",
     ),
-    overwrite_scaffold: bool = typer.Option(False, help="Overwrite alembic scaffold if present."),
-    create_db_if_missing: bool = typer.Option(True, help="Create the database/schema if missing."),
+    overwrite_scaffold: bool = typer.Option(
+        False, help="Overwrite alembic scaffold if present."
+    ),
+    create_db_if_missing: bool = typer.Option(
+        True, help="Create the database/schema if missing."
+    ),
     create_followup_revision: bool = typer.Option(
         True, help="Create an autogen follow-up revision if revisions already exist."
     ),
@@ -188,7 +208,7 @@ def cmd_setup_and_migrate(
     Async vs. sync is inferred from SQL_URL.
     """
     final_pkgs = _find_pkgs(with_payments, discover_packages)
-    core_setup_and_migrate(
+    result = core_setup_and_migrate(
         overwrite_scaffold=overwrite_scaffold,
         create_db_if_missing=create_db_if_missing,
         create_followup_revision=create_followup_revision,
@@ -197,15 +217,80 @@ def cmd_setup_and_migrate(
         discover_packages=final_pkgs or None,
         database_url=database_url,
     )
+    # Echo a concise JSON result so tests and users can introspect outcome
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        # Fallback to plain string if not JSON-serializable for any reason
+        typer.echo(str(result))
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-init")(cmd_init)
-    app.command("sql-revision")(cmd_revision)
-    app.command("sql-upgrade")(cmd_upgrade)
-    app.command("sql-downgrade")(cmd_downgrade)
-    app.command("sql-current")(cmd_current)
-    app.command("sql-history")(cmd_history)
-    app.command("sql-stamp")(cmd_stamp)
-    app.command("sql-merge-heads")(cmd_merge_heads)
-    app.command("sql-setup-and-migrate")(cmd_setup_and_migrate)
+    # Register under the 'sql' group app
+    app.command("init")(cmd_init)
+    app.command("revision")(cmd_revision)
+    app.command("upgrade")(cmd_upgrade)
+    # Allow unknown options so users can pass "-1" like Alembic without Click treating it as an option
+    app.command(
+        "downgrade",
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )(cmd_downgrade)
+    app.command("current")(cmd_current)
+    app.command("history")(cmd_history)
+    app.command("stamp")(cmd_stamp)
+    app.command("merge-heads")(cmd_merge_heads)
+    app.command("setup-and-migrate")(cmd_setup_and_migrate)
+    app.command("seed")(cmd_seed)
+
+
+def _import_callable(path: str):
+    mod_name, _, fn_name = path.partition(":")
+    if not mod_name or not fn_name:
+        raise typer.BadParameter("Expected format 'module.path:callable'")
+    # Back-compat: after moving tests under tests/unit, allow legacy test module
+    # dotted paths like 'tests.db.sql.test_sql_seed_cli:my_seed'.
+    mod = None
+    unit_mod = None
+    if mod_name.startswith("tests.db."):
+        # Try legacy import first (shim module), then unit module fallback
+        try:
+            mod = import_module(mod_name)
+        except ModuleNotFoundError:
+            pass
+        unit_name = mod_name.replace("tests.db.", "tests.unit.db.", 1)
+        try:
+            unit_mod = import_module(unit_name)
+        except ModuleNotFoundError:
+            unit_mod = None
+        # If both exist, unify shared state where applicable
+        if mod is not None and unit_mod is not None:
+            # Example: tests use a global `called` dict; point legacy to unit
+            try:
+                if hasattr(unit_mod, "called"):
+                    setattr(mod, "called", getattr(unit_mod, "called"))
+            except Exception:
+                pass
+        # If legacy mod missing but unit exists, use unit
+        if mod is None and unit_mod is not None:
+            mod = unit_mod
+    else:
+        mod = import_module(mod_name)
+    fn = getattr(mod, fn_name, None)
+    if not callable(fn):
+        raise typer.BadParameter(
+            f"Callable '{fn_name}' not found in module '{mod_name}'"
+        )
+    return fn
+
+
+def cmd_seed(
+    target: str = typer.Argument(..., help="Seed callable path 'module:func'"),
+    database_url: Optional[str] = typer.Option(
+        None,
+        help="Database URL; overrides env for this command.",
+    ),
+):
+    """Run a user-provided seed function to load fixtures/reference data."""
+    apply_database_url(database_url)
+    fn = _import_callable(target)
+    fn()

svc_infra/cli/cmds/db/sql/sql_export_cmds.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional, cast
+
+import typer
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+
+from svc_infra.db.sql.utils import build_engine
+
+try:  # SQLAlchemy async extras are optional
+    import sqlalchemy.ext.asyncio as sa_async
+except Exception:  # pragma: no cover - fallback when async extras unavailable
+    sa_async = None  # type: ignore[assignment]
+
+
+def export_tenant(
+    table: str = typer.Argument(
+        ..., help="Qualified table name to export (e.g., public.items)"
+    ),
+    tenant_id: str = typer.Option(
+        ..., "--tenant-id", help="Tenant id value to filter by."
+    ),
+    tenant_field: str = typer.Option(
+        "tenant_id", help="Column name for tenant id filter."
+    ),
+    output: Optional[Path] = typer.Option(
+        None, "--output", help="Output file; defaults to stdout."
+    ),
+    limit: Optional[int] = typer.Option(None, help="Max rows to export."),
+    database_url: Optional[str] = typer.Option(
+        None, "--database-url", help="Overrides env SQL_URL for this command."
+    ),
+):
+    """Export rows for a tenant from a given SQL table as JSON array."""
+    if database_url:
+        os.environ["SQL_URL"] = database_url
+
+    url = os.getenv("SQL_URL")
+    if not url:
+        typer.echo("SQL_URL is required (or pass --database-url)", err=True)
+        raise typer.Exit(code=2)
+
+    engine = build_engine(url)
+    rows: list[dict[str, Any]]
+    query = f"SELECT * FROM {table} WHERE {tenant_field} = :tenant_id"
+    if limit and limit > 0:
+        query += " LIMIT :limit"
+
+    params: dict[str, Any] = {"tenant_id": tenant_id}
+    if limit and limit > 0:
+        params["limit"] = int(limit)
+
+    stmt = text(query)
+
+    is_async_engine = sa_async is not None and isinstance(engine, sa_async.AsyncEngine)
+
+    if is_async_engine:
+        async_engine = cast(Any, engine)
+
+        async def _fetch() -> list[dict[str, Any]]:
+            async with async_engine.connect() as conn:
+                result = await conn.execute(stmt, params)
+                return [dict(row) for row in result.mappings()]
+
+        rows = asyncio.run(_fetch())
+    else:
+        sync_engine = cast(Engine, engine)
+        with sync_engine.connect() as conn:
+            result = conn.execute(stmt, params)
+            rows = [dict(row) for row in result.mappings()]
+
+    data = json.dumps(rows, indent=2)
+    if output:
+        output.write_text(data)
+        typer.echo(str(output))
+    else:
+        sys.stdout.write(data)
+
+
+def register(app_root: typer.Typer) -> None:
+    # Attach directly to the provided 'sql' group app
+    app_root.command("export-tenant")(export_tenant)

svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py

@@ -134,6 +134,6 @@ def cmd_scaffold_schemas(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-scaffold")(cmd_scaffold)
-    app.command("sql-scaffold-models")(cmd_scaffold_models)
-    app.command("sql-scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-models")(cmd_scaffold_models)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)

svc_infra/cli/cmds/docs/docs_cmds.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+from importlib.resources import as_file
+from importlib.resources import files as pkg_files
+from pathlib import Path
+from typing import Dict, List
+
+import click
+import typer
+from typer.core import TyperGroup
+
+from svc_infra.app.root import resolve_project_root
+
+
+def _norm(name: str) -> str:
+    return name.strip().lower().replace(" ", "-").replace("_", "-")
+
+
+def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
+    topics: Dict[str, Path] = {}
+    if docs_dir.exists() and docs_dir.is_dir():
+        for p in sorted(docs_dir.glob("*.md")):
+            if p.is_file():
+                topics[_norm(p.stem)] = p
+    return topics
+
+
+def _discover_pkg_topics() -> Dict[str, Path]:
+    """
+    Discover docs shipped inside the installed package at svc_infra/docs/*,
+    using importlib.resources so this works for wheels, sdists, and zipped wheels.
+    """
+    topics: Dict[str, Path] = {}
+    try:
+        docs_root = pkg_files("svc_infra").joinpath("docs")
+        # docs_root is a Traversable; it may be inside a zip. Iterate safely.
+        for entry in docs_root.iterdir():
+            if entry.name.endswith(".md"):
+                # materialize to a real tempfile path if needed
+                with as_file(entry) as concrete:
+                    p = Path(concrete)
+                    if p.exists() and p.is_file():
+                        topics[_norm(p.stem)] = p
+    except Exception:
+        # If the package has no docs directory, just return empty.
+        pass
+    return topics
+
+
+def _resolve_docs_dir(ctx: click.Context) -> Path | None:
+    """
+    Optional override precedence:
+      1) SVC_INFRA_DOCS_DIR env var
+      2) *Only when working inside the svc-infra repo itself*: repo-root /docs
+    """
+    # 1) Env var
+    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
+    if env_dir:
+        p = Path(env_dir).expanduser()
+        if p.exists():
+            return p
+
+    # 2) In-repo convenience (so `svc-infra docs` works inside this repo)
+    try:
+        root = resolve_project_root()
+        proj_docs = root / "docs"
+        if proj_docs.exists():
+            return proj_docs
+    except Exception:
+        pass
+
+    return None
+
+
+class DocsGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> List[str]:
+        names: List[str] = list(super().list_commands(ctx) or [])
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        pkg = _discover_pkg_topics()
+        names.extend(fs.keys())
+        names.extend([k for k in pkg.keys() if k not in fs])
+        return sorted(set(names))
+
+    def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
+        cmd = super().get_command(ctx, name)
+        if cmd is not None:
+            return cmd
+
+        key = _norm(name)
+
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            file_path = fs[key]
+
+            @click.command(name=name)
+            def _show_fs() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_fs
+
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            file_path = pkg[key]
+
+            @click.command(name=name)
+            def _show_pkg() -> None:
+                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
+
+            return _show_pkg
+
+        return None
+
+
+def register(app: typer.Typer) -> None:
+    docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
+
+    @docs_app.callback(invoke_without_command=True)
+    def _docs_options() -> None:
+        # No group-level options; dynamic commands and 'show' handle topics.
+        return None
+
+    @docs_app.command(
+        "show", help="Show docs for a topic (alternative to dynamic subcommand)"
+    )
+    def show(topic: str) -> None:
+        key = _norm(topic)
+        ctx = click.get_current_context()
+        dir_to_use = _resolve_docs_dir(ctx)
+        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
+        if key in fs:
+            typer.echo(fs[key].read_text(encoding="utf-8", errors="replace"))
+            return
+        pkg = _discover_pkg_topics()
+        if key in pkg:
+            typer.echo(pkg[key].read_text(encoding="utf-8", errors="replace"))
+            return
+        raise typer.BadParameter(f"Unknown topic: {topic}")
+
+    app.add_typer(docs_app, name="docs")

svc_infra/cli/cmds/dx/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import typer
+
+from .dx_cmds import app as dx_app
+
+
+def register_dx(root: typer.Typer) -> None:
+    root.add_typer(dx_app, name="dx")
+
+
+__all__ = ["register_dx"]