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

svc_infra/cache/tags.py

@@ -28,50 +28,25 @@ async def invalidate_tags(*tags: str) -> int:
     if not tags:
         return 0
 
-    count = 0
+    # Preserve order while de-duplicating.
+    tags_to_delete = list(dict.fromkeys(tags))
 
-    # Strategy 1: Modern cashews invalidate with tags parameter
+    # Cashews supports explicit tag deletion via delete_tags().
     try:
-        result = await _cache.invalidate(tags=list(tags))
-        return int(result) if isinstance(result, int) else len(tags)
-    except (TypeError, AttributeError):
-        pass
+        if hasattr(_cache, "delete_tags"):
+            await _cache.delete_tags(*tags_to_delete)
+            return len(tags_to_delete)
     except Exception as e:
-        logger.warning(f"Modern tag invalidation failed: {e}")
-
-    # Strategy 2: Legacy cashews invalidate with positional args
-    try:
-        result = await _cache.invalidate(*tags)
-        return int(result) if isinstance(result, int) else len(tags)
-    except (TypeError, AttributeError):
-        pass
-    except Exception as e:
-        logger.warning(f"Legacy tag invalidation failed: {e}")
-
-    # Strategy 3: Individual tag methods
-    for tag in tags:
-        for method_name in ("delete_tag", "invalidate_tag", "tag_invalidate"):
-            if hasattr(_cache, method_name):
-                try:
-                    method = getattr(_cache, method_name)
-                    result = await method(tag)
-                    count += int(result) if isinstance(result, int) else 1
-                    break
-                except Exception as e:
-                    logger.debug(f"Tag method {method_name} failed for tag {tag}: {e}")
-                    continue
-        else:
-            # Strategy 4: Pattern matching fallback
-            for method_name in ("delete_match", "invalidate_match", "invalidate"):
-                if hasattr(_cache, method_name):
-                    try:
-                        method = getattr(_cache, method_name)
-                        pattern = f"*{tag}*"
-                        result = await method(pattern)
-                        count += int(result) if isinstance(result, int) else 1
-                        break
-                    except Exception as e:
-                        logger.debug(f"Pattern method {method_name} failed for tag {tag}: {e}")
-                        continue
-
-    return count
+        logger.warning(f"Cache tag invalidation failed: {e}")
+
+    # Fallback: attempt private per-tag deletion when available.
+    deleted = 0
+    for tag in tags_to_delete:
+        try:
+            if hasattr(_cache, "_delete_tag"):
+                await _cache._delete_tag(tag)
+                deleted += 1
+        except Exception as e:
+            logger.debug(f"Tag deletion failed for tag {tag}: {e}")
+
+    return deleted

svc_infra/cache/ttl.py

@@ -6,7 +6,6 @@ via environment variables with sensible defaults.
 """
 
 import os
-from typing import Optional
 
 
 def _get_env_int(key: str, default: int) -> int:
@@ -36,7 +35,7 @@ TTL_SHORT: int = _get_env_int("CACHE_TTL_SHORT", 30)  # 30 seconds
 TTL_LONG: int = _get_env_int("CACHE_TTL_LONG", 3600)  # 1 hour
 
 
-def get_ttl(duration_type: str) -> Optional[int]:
+def get_ttl(duration_type: str) -> int | None:
     """
     Get TTL value by duration type name.
 
@@ -60,7 +59,7 @@ def get_ttl(duration_type: str) -> Optional[int]:
     return ttl_map.get(duration_type.lower())
 
 
-def validate_ttl(ttl: Optional[int]) -> int:
+def validate_ttl(ttl: int | None) -> int:
     """
     Validate and normalize a TTL value.
 

svc_infra/cache/utils.py

@@ -8,7 +8,8 @@ hashing complex objects, and formatting key templates.
 import hashlib
 import json
 import logging
-from typing import Any, Iterable, Union
+from collections.abc import Iterable
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -42,7 +43,7 @@ def stable_hash(*args: Any, **kwargs: Any) -> str:
     return hashlib.sha1(raw.encode("utf-8")).hexdigest()
 
 
-def join_key(parts: Iterable[Union[str, int, None]]) -> str:
+def join_key(parts: Iterable[str | int | None]) -> str:
     """
     Join key parts into a cache key, filtering out empty values.
 
@@ -98,7 +99,7 @@ def format_tuple_key(key_tuple: tuple[str, ...], **kwargs) -> str:
         raise ValueError(f"Failed to format key template: {e}") from e
 
 
-def normalize_cache_key(key: Union[str, tuple[str, ...]], **kwargs) -> str:
+def normalize_cache_key(key: str | tuple[str, ...], **kwargs) -> str:
     """
     Normalize a cache key from various input formats.
 

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,45 @@ 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")
 
-# --- nosql commands ---
-register_mongo(app)
-register_mongo_scaffold(app)
+# --- 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")
 
-# -- observability commands ---
-register_obs(app)
+# --- 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")
+
+# -- sdk commands ---
+register_sdk(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

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import importlib
 import os
-from typing import Any, Optional, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 import typer
 
@@ -17,7 +18,7 @@ from svc_infra.db.nosql.utils import prepare_process_env
 # -------------------- helpers --------------------
 
 
-def _apply_mongo_env(mongo_url: Optional[str], mongo_db: Optional[str]) -> None:
+def _apply_mongo_env(mongo_url: str | None, mongo_db: str | None) -> None:
     """If provided, set MONGO_URL / MONGO_DB for the current process."""
     if mongo_url:
         os.environ["MONGO_URL"] = mongo_url
@@ -63,13 +64,13 @@ def cmd_prepare(
         "--resources",
         help="Dotted path to NoSqlResource(s). e.g. 'app.db.mongo:RESOURCES'",
     ),
-    mongo_url: Optional[str] = typer.Option(
+    mongo_url: str | None = typer.Option(
         None, "--mongo-url", help="Overrides env MONGO_URL for this command."
     ),
-    mongo_db: Optional[str] = typer.Option(
+    mongo_db: str | None = typer.Option(
         None, "--mongo-db", help="Overrides env MONGO_DB for this command."
     ),
-    service_id: Optional[str] = typer.Option(
+    service_id: str | None = typer.Option(
         None,
         "--service-id",
         help="Stable ID for this service/app. Defaults to top-level module name.",
@@ -125,13 +126,13 @@ def cmd_setup_and_prepare(
         "--resources",
         help="Dotted path to NoSqlResource(s). e.g. 'app.db.mongo:RESOURCES'",
     ),
-    mongo_url: Optional[str] = typer.Option(
+    mongo_url: str | None = typer.Option(
         None, "--mongo-url", help="Overrides env MONGO_URL for this command."
     ),
-    mongo_db: Optional[str] = typer.Option(
+    mongo_db: str | None = typer.Option(
         None, "--mongo-db", help="Overrides env MONGO_DB for this command."
     ),
-    service_id: Optional[str] = typer.Option(
+    service_id: str | None = typer.Option(
         None,
         "--service-id",
         help="Stable ID for this service/app. Defaults to top-level module name.",
@@ -157,10 +158,10 @@ def cmd_setup_and_prepare(
 
 
 def cmd_ping(
-    mongo_url: Optional[str] = typer.Option(
+    mongo_url: str | None = typer.Option(
         None, "--mongo-url", help="Overrides env MONGO_URL for this command."
     ),
-    mongo_db: Optional[str] = typer.Option(
+    mongo_db: str | None = typer.Option(
         None, "--mongo-db", help="Overrides env MONGO_DB for this command."
     ),
 ):
@@ -172,7 +173,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 +191,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

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Optional
 
 import typer
 
@@ -25,10 +24,10 @@ def cmd_scaffold(
         "--same-dir/--no-same-dir",
         help="Put documents & schemas into the same directory.",
     ),
-    documents_filename: Optional[str] = typer.Option(
+    documents_filename: str | None = typer.Option(
         None, help="Custom filename for documents (separate-dir mode)."
     ),
-    schemas_filename: Optional[str] = typer.Option(
+    schemas_filename: str | None = typer.Option(
         None, help="Custom filename for schemas (separate-dir mode)."
     ),
 ):
@@ -53,7 +52,7 @@ def cmd_scaffold_documents(
     dest_dir: Path = typer.Option(..., "--dest-dir", resolve_path=True),
     entity_name: str = typer.Option("Item", "--entity-name"),
     overwrite: bool = typer.Option(False, "--overwrite/--no-overwrite"),
-    documents_filename: Optional[str] = typer.Option(
+    documents_filename: str | None = typer.Option(
         None,
         "--documents-filename",
         help="Filename to write (e.g. product_doc.py). Defaults to <snake(entity)>.py",
@@ -73,7 +72,7 @@ def cmd_scaffold_schemas(
     dest_dir: Path = typer.Option(..., "--dest-dir", resolve_path=True),
     entity_name: str = typer.Option("Item", "--entity-name"),
     overwrite: bool = typer.Option(False, "--overwrite/--no-overwrite"),
-    schemas_filename: Optional[str] = typer.Option(
+    schemas_filename: str | None = typer.Option(
         None,
         "--schemas-filename",
         help="Filename to write (e.g. product_schemas.py). Defaults to <snake(entity)>.py",
@@ -96,7 +95,7 @@ def cmd_scaffold_resources(
         "--entity-name",
         help="Used only to prefill example placeholders.",
     ),
-    filename: Optional[str] = typer.Option(
+    filename: str | None = typer.Option(
         None,
         "--filename",
         help='Output filename (default: "resources.py")',
@@ -127,7 +126,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,267 @@
+"""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
+
+import typer
+
+
+def cmd_wait(
+    database_url: str | None = 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: str | None = 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)