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

svc_infra/cli/__init__.py

@@ -4,10 +4,17 @@ import typer
 
 from svc_infra.cli.cmds import (
     _HELP,
+    jobs_app,
     register_alembic,
+    register_db_ops,
+    register_docs,
+    register_dx,
+    register_health,
     register_mongo,
     register_mongo_scaffold,
     register_obs,
+    register_sdk,
+    register_sql_export,
     register_sql_scaffold,
 )
 from svc_infra.cli.foundation.typer_bootstrap import pre_cli
@@ -15,16 +22,53 @@ from svc_infra.cli.foundation.typer_bootstrap import pre_cli
 app = typer.Typer(no_args_is_help=True, add_completion=False, help=_HELP)
 pre_cli(app)
 
-# --- sql commands ---
-register_alembic(app)
-register_sql_scaffold(app)
+# --- db ops group ---
+db_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Database operations"
+)
+register_db_ops(db_app)
+app.add_typer(db_app, name="db")
+
+# --- sql group ---
+sql_app = typer.Typer(no_args_is_help=True, add_completion=False, help="SQL commands")
+register_alembic(sql_app)
+register_sql_scaffold(sql_app)
+register_sql_export(sql_app)
+app.add_typer(sql_app, name="sql")
+
+# --- mongo group ---
+mongo_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="MongoDB commands"
+)
+register_mongo(mongo_app)
+register_mongo_scaffold(mongo_app)
+app.add_typer(mongo_app, name="mongo")
+
+# --- health group ---
+health_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Health checks"
+)
+register_health(health_app)
+app.add_typer(health_app, name="health")
+
+# -- obs group ---
+obs_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Observability commands"
+)
+register_obs(obs_app)
+app.add_typer(obs_app, name="obs")
+
+# -- dx commands ---
+register_dx(app)
+
+# -- jobs commands ---
+app.add_typer(jobs_app, name="jobs")
 
-# --- nosql commands ---
-register_mongo(app)
-register_mongo_scaffold(app)
+# -- sdk commands ---
+register_sdk(app)
 
-# -- observability commands ---
-register_obs(app)
+# -- docs commands ---
+register_docs(app)
 
 
 def main():

svc_infra/cli/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

svc_infra/cli/cmds/__init__.py

@@ -1,18 +1,55 @@
-from svc_infra.cli.cmds.db.nosql.mongo.mongo_cmds import register as register_mongo
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+try:
+    from svc_infra.cli.cmds.db.nosql.mongo.mongo_cmds import register as register_mongo
+except ModuleNotFoundError as exc:
+    _mongo_import_error = exc
+
+    def register_mongo(app: typer.Typer) -> None:  # type: ignore[no-redef]
+        def _unavailable() -> Any:
+            raise ModuleNotFoundError(
+                "MongoDB CLI commands require optional dependencies. Install pymongo and motor "
+                "to enable `svc-infra mongo ...` commands."
+            ) from _mongo_import_error
+
+        # Provide a single helpful command instead of failing CLI import.
+        app.command("unavailable")(_unavailable)
+
+
 from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
     register as register_mongo_scaffold,
 )
+from svc_infra.cli.cmds.db.ops_cmds import register as register_db_ops
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
-from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import register as register_sql_scaffold
+from svc_infra.cli.cmds.db.sql.sql_export_cmds import register as register_sql_export
+from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import (
+    register as register_sql_scaffold,
+)
+from svc_infra.cli.cmds.docs.docs_cmds import register as register_docs
+from svc_infra.cli.cmds.dx import register_dx
+from svc_infra.cli.cmds.health.health_cmds import register as register_health
+from svc_infra.cli.cmds.jobs.jobs_cmds import app as jobs_app
 from svc_infra.cli.cmds.obs.obs_cmds import register as register_obs
+from svc_infra.cli.cmds.sdk.sdk_cmds import register as register_sdk
 
 from .help import _HELP
 
 __all__ = [
     "register_alembic",
     "register_sql_scaffold",
+    "register_sql_export",
     "register_mongo",
     "register_mongo_scaffold",
+    "register_db_ops",
     "register_obs",
+    "jobs_app",
+    "register_sdk",
+    "register_dx",
+    "register_docs",
+    "register_health",
     "_HELP",
 ]

svc_infra/cli/cmds/db/nosql/mongo/mongo_cmds.py

@@ -172,7 +172,9 @@ def cmd_ping(
 
     import asyncio
 
-    from svc_infra.db.nosql.mongo.client import acquire_db  # local import to avoid side effects
+    from svc_infra.db.nosql.mongo.client import (
+        acquire_db,
+    )  # local import to avoid side effects
 
     async def _run():
         await init_mongo()
@@ -188,6 +190,7 @@ def cmd_ping(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("mongo-prepare")(cmd_prepare)
-    app.command("mongo-setup-and-prepare")(cmd_setup_and_prepare)
-    app.command("mongo-ping")(cmd_ping)
+    # Attach to 'mongo' group app
+    app.command("prepare")(cmd_prepare)
+    app.command("setup-and-prepare")(cmd_setup_and_prepare)
+    app.command("ping")(cmd_ping)

svc_infra/cli/cmds/db/nosql/mongo/mongo_scaffold_cmds.py

@@ -17,7 +17,9 @@ def cmd_scaffold(
     entity_name: str = typer.Option(
         "Item", help="Entity class name (e.g., User, Member, Product)."
     ),
-    documents_dir: Path = typer.Option(..., help="Directory for Mongo document models."),
+    documents_dir: Path = typer.Option(
+        ..., help="Directory for Mongo document models."
+    ),
     schemas_dir: Path = typer.Option(..., help="Directory for Pydantic CRUD schemas."),
     overwrite: bool = typer.Option(False, help="Overwrite existing files."),
     same_dir: bool = typer.Option(
@@ -127,7 +129,7 @@ def register(app: typer.Typer) -> None:
       • mongo-scaffold-schemas
       • mongo-scaffold-resources
     """
-    app.command("mongo-scaffold")(cmd_scaffold)
-    app.command("mongo-scaffold-documents")(cmd_scaffold_documents)
-    app.command("mongo-scaffold-schemas")(cmd_scaffold_schemas)
-    app.command("mongo-scaffold-resources")(cmd_scaffold_resources)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-documents")(cmd_scaffold_documents)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold-resources")(cmd_scaffold_resources)

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