tempest-fastapi-sdk 0.46.0__tar.gz → 0.47.0__tar.gz

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.47.0] — 2026-06-11
+
+### Added
+
+- **`tempest db seed`** — runs a project seed callable
+  (default `src.db.seeds:seed`, dotted `module:callable`, sync or async,
+  taking one `AsyncSession`) inside a managed session: commit on
+  success, rollback on error. The SDK only wires the session lifecycle;
+  the callable owns what gets inserted. Prints the row count when the
+  callable returns an `int`.
+- **`tempest secrets rotate`** — generates fresh URL-safe secrets for
+  the keys a service signs/authenticates with (`JWT_SECRET` /
+  `TOKEN_SECRET` by default; override with `--keys`) and rewrites the
+  matching `.env` lines **in place** (existing keys replaced, missing
+  keys appended) after a `.env.bak` backup. `--print` writes nothing and
+  emits the values to stdout; `--length` sets the entropy; `--no-backup`
+  skips the backup.
+
+### Docs
+
+- CLI recipe (bilingual) gains **`db seed`** and **`secrets rotate`**
+  sections; README CLI section and recipes index updated.
+
 ## [0.46.0] — 2026-06-11
 
 ### Added

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.46.0
+Version: 0.47.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -3411,6 +3411,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### Secrets — `tempest secrets`
+
+Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+
+```bash
+tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
+tempest secrets rotate --print                        # just print, write nothing
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+tempest secrets rotate --length 64 --no-backup
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/README.md

@@ -3309,6 +3309,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### Secrets — `tempest secrets`
+
+Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+
+```bash
+tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
+tempest secrets rotate --print                        # just print, write nothing
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+tempest secrets rotate --length 64 --no-backup
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/cli.en.md

@@ -140,8 +140,29 @@ tempest db downgrade <rev>                       # roll back to a specific revis
 tempest db current                               # print the applied revision
 tempest db history                               # revisions newest → oldest
 tempest db history -v                            # with full message body
+tempest db seed                                  # runs src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # custom callable
 ```
 
+#### Seed the database — `tempest db seed`
+
+Runs a project seed callable inside a managed session (commit on success, rollback on error). The callable takes a positional `AsyncSession` and may be sync or async; what it inserts is up to you — the SDK only wires the session lifecycle. Defaults to importing `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Seed initial categories. Return the count (optional)."""
+    session.add_all([CategoryModel(name="Books"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
+```
+
+When the callable returns an `int`, the CLI prints the count: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Users — `tempest user`
 
 Seed and list users using the project's concrete ``UserModel`` (default ``src.db.models:UserModel``). Bootstraps the first admin without manual SQL.
@@ -180,6 +201,27 @@ tempest user list --admin                        # admins only
 
 ``DATABASE_URL`` resolves the same way as ``tempest db`` (env var > settings > alembic.ini).
 
+### Secrets — `tempest secrets`
+
+Generate and rotate application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines **in place** — backing up the old file first — and leaving every other line untouched.
+
+```bash
+# Rotate JWT_SECRET and TOKEN_SECRET in .env (writes .env.bak)
+tempest secrets rotate
+
+# Just print the new values (writes nothing) — pipe into a secret manager
+tempest secrets rotate --print
+
+# Custom keys and file
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# More entropy, no backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotating `JWT_SECRET` invalidates every token signed with the old value: users are logged out and pending reset/activation links stop working. Rotate during a maintenance window and restart the service to load the new values.
+
 ### Regenerating `docker-compose.yaml` in an existing project
 
 When you change installed extras (`uv add "tempest-fastapi-sdk[minio]"`) or the SDK bumps image versions, regenerate with:

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/cli.md

@@ -188,8 +188,29 @@ tempest db downgrade <rev>                       # rollback até rev específico
 tempest db current                               # imprime revision aplicado
 tempest db history                               # histórico de revisions
 tempest db history -v                            # com message body completo
+tempest db seed                                  # roda src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # callable customizado
 ```
 
+#### Popular o banco — `tempest db seed`
+
+Roda um callable de seed do projeto dentro de uma sessão gerenciada (commit no sucesso, rollback no erro). O callable recebe uma `AsyncSession` posicional e pode ser sync ou async; o que ele insere é decisão sua — o SDK só cuida do ciclo de vida da sessão. Por padrão importa `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Popula categorias iniciais. Retorna a contagem (opcional)."""
+    session.add_all([CategoryModel(name="Livros"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
+```
+
+Quando o callable devolve um `int`, a CLI mostra a contagem: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Usuários — `tempest user`
 
 Insere/lista usuários direto no banco usando o `UserModel` concreto do projeto (default `src.db.models:UserModel`). Útil pra bootstrapear o primeiro admin sem rodar SQL manual.
@@ -228,6 +249,27 @@ tempest user list --admin                        # só admins
 
 Resolução do `DATABASE_URL` igual ao `tempest db` (env var > settings > alembic.ini).
 
+### Segredos — `tempest secrets`
+
+Gera e rotaciona os segredos da aplicação (`JWT_SECRET` / `TOKEN_SECRET` por padrão), reescrevendo as linhas correspondentes no `.env` **no lugar** — fazendo backup do arquivo antigo antes — e deixando as outras linhas intactas.
+
+```bash
+# Rotaciona JWT_SECRET e TOKEN_SECRET no .env (gera .env.bak)
+tempest secrets rotate
+
+# Só imprime os novos valores (não escreve nada) — pra pipar num secret manager
+tempest secrets rotate --print
+
+# Chaves e arquivo customizados
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# Mais entropia, sem backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotacionar `JWT_SECRET` invalida todo token assinado com o valor antigo: usuários são deslogados e links de reset/ativação pendentes param de funcionar. Rotacione numa janela de manutenção e reinicie o serviço pra carregar os novos valores.
+
 #### Gates de qualidade
 
 Os comandos de lint chamam a ferramenta do projeto. Eles procuram o executável no `PATH` primeiro e, caso contrário, caem para `uv run <tool>` para que um virtualenv local do projeto funcione sem ativação manual.

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/index.en.md

@@ -27,7 +27,7 @@ Bite-sized "I want to wire X" walkthroughs. Each page starts with **what problem
 | **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |
 | **[Testing »](testing.md)** | `test_session`, `test_database`, in-memory SQLite, pytest fixtures |
 | **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
 | **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |
 

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/docs/recipes/index.md

@@ -27,7 +27,7 @@ Passo a passo curtos no estilo "quero conectar X". Cada página começa com **qu
 | **[Utilitários »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, tokens opacos (`generate_opaque_token`) |
 | **[Testes »](testing.md)** | `test_session`, `test_database`, SQLite em memória, fixtures pytest |
 | **[Deploy seguro »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (barra DROPs), `GracefulShutdownMiddleware` |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Segurança »](security.md)** | `AttemptThrottle`, helpers de token opaco, `HardenedStaticFiles`, headers de segurança |
 | **[Helpers brasileiros »](br-helpers.md)** | validação + normalização de CPF / CNPJ / CEP / telefone |
 

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.46.0"
+version = "0.47.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/__init__.py

@@ -250,7 +250,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.46.0"
+__version__: str = "0.47.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/cli/db.py

@@ -20,12 +20,21 @@ stripped automatically before Alembic runs.
 
 from __future__ import annotations
 
+import asyncio
+import importlib
+import inspect
 import os
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
 
 import typer
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+
 
 def _resolve_database_url(explicit: str | None) -> str | None:
     """Pick the DB URL using the documented priority order.
@@ -95,6 +104,70 @@ def _helper(
     return AlembicHelper(str(ini), db_url=database_url)
 
 
+def _load_seed_callable(spec: str) -> Callable[[AsyncSession], Any]:
+    """Import a ``module.path:callable`` seed entry point.
+
+    Args:
+        spec (str): Dotted spec ``"module.path:callable"``.
+
+    Returns:
+        Callable[[AsyncSession], Any]: The seed callable (sync or async).
+
+    Raises:
+        typer.Exit: When the spec is malformed, the import fails, or the
+            attribute is not callable.
+    """
+    module_path, _, attr = spec.partition(":")
+    if not module_path or not attr:
+        typer.echo(
+            f"error: --seed must be 'module.path:callable', got {spec!r}",
+            err=True,
+        )
+        raise typer.Exit(2)
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        typer.echo(f"error: cannot import {module_path!r}: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    seed: object = getattr(module, attr, None)
+    if not callable(seed):
+        typer.echo(
+            f"error: {spec} is not callable (got {type(seed).__name__}).",
+            err=True,
+        )
+        raise typer.Exit(2)
+    return cast("Callable[[AsyncSession], Any]", seed)
+
+
+async def _run_seed(database_url: str, seed: Callable[[AsyncSession], Any]) -> Any:
+    """Open one managed session and run the seed callable in it.
+
+    Args:
+        database_url (str): The resolved database URL.
+        seed (Callable[[AsyncSession], Any]): The seed callable; awaited
+            when it returns a coroutine.
+
+    Returns:
+        Any: Whatever the seed callable returns (e.g. a row count), or
+        ``None``.
+    """
+    from tempest_fastapi_sdk import AsyncDatabaseManager
+
+    manager = AsyncDatabaseManager(database_url)
+    await manager.connect()
+    try:
+        async with manager.get_session_context() as session:
+            result = seed(session)
+            if inspect.isawaitable(result):
+                result = await result
+            return result
+    finally:
+        await manager.disconnect()
+
+
 db_app: typer.Typer = typer.Typer(
     name="db",
     help="Alembic migration helpers (create / apply / inspect).",
@@ -242,6 +315,46 @@ def db_current(
     typer.echo(current or "(no revision applied)")
 
 
+@db_app.command("seed")
+def db_seed(
+    seed_spec: str = typer.Option(
+        "src.db.seeds:seed",
+        "--seed",
+        "-s",
+        help=(
+            "Dotted 'module.path:callable' to run. The callable receives "
+            "one positional AsyncSession and may be sync or async. Defaults "
+            "to the scaffolded 'src.db.seeds:seed'."
+        ),
+    ),
+    database_url: str | None = typer.Option(
+        None,
+        "--database-url",
+        help="Override DATABASE_URL for this run.",
+    ),
+) -> None:
+    """Run a project seed callable inside one managed session.
+
+    Builds an :class:`AsyncDatabaseManager` from the resolved URL, opens
+    a session (committed on success, rolled back on error), and invokes
+    the dotted callable with it. The callable owns what gets inserted —
+    the SDK only wires the session lifecycle so seeding looks the same
+    across every service.
+    """
+    url = _resolve_database_url(database_url)
+    if url is None:
+        typer.echo(
+            "error: no database URL. Pass --database-url, set DATABASE_URL, "
+            "or run inside a project with src/core/settings.py.",
+            err=True,
+        )
+        raise typer.Exit(2)
+    seed_callable = _load_seed_callable(seed_spec)
+    result = asyncio.run(_run_seed(url, seed_callable))
+    suffix = f" ({result} rows)" if isinstance(result, int) else ""
+    typer.echo(f"Seeded via {seed_spec}{suffix}.")
+
+
 @db_app.command("history")
 def db_history(
     verbose: bool = typer.Option(

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.47.0}/tempest_fastapi_sdk/cli/main.py

@@ -14,6 +14,7 @@ from tempest_fastapi_sdk.cli import generate as generate_module
 from tempest_fastapi_sdk.cli import lint as lint_module
 from tempest_fastapi_sdk.cli import new as new_module
 from tempest_fastapi_sdk.cli.db import db_app
+from tempest_fastapi_sdk.cli.secrets import secrets_app
 from tempest_fastapi_sdk.cli.user import user_app
 
 # Typer >= 0.13 vendors its own copy of Click under ``typer._click``, so a
@@ -136,6 +137,7 @@ app: typer.Typer = typer.Typer(
 )
 app.add_typer(db_app, name="db")
 app.add_typer(user_app, name="user")
+app.add_typer(secrets_app, name="secrets")
 
 
 def _print_version(value: bool) -> None:

tempest_fastapi_sdk-0.47.0/tempest_fastapi_sdk/cli/secrets.py

@@ -0,0 +1,159 @@
+"""``tempest secrets`` — generate and rotate application secrets.
+
+Rotating a leaked (or simply stale) signing secret should be one
+command, not a hunt through ``.env`` with a hand-rolled
+``openssl rand``. ``tempest secrets rotate`` generates fresh,
+URL-safe random values for the secret keys a Tempest service uses
+(``JWT_SECRET`` / ``TOKEN_SECRET`` by default), rewrites the matching
+lines in ``.env`` in place — backing the old file up first — and
+leaves every other line untouched.
+
+!!! warning
+    Rotating ``JWT_SECRET`` invalidates every token signed with the
+    old one: users are logged out and pending password-reset /
+    activation links stop working. Rotate during a maintenance window
+    (or run two secrets in parallel if you need zero-downtime
+    rotation).
+"""
+
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+
+import typer
+
+# Secret env vars a Tempest service signs/authenticates with. MinIO and
+# database credentials are intentionally excluded — those are external
+# credentials, not values the service is free to regenerate.
+_DEFAULT_KEYS: tuple[str, ...] = ("JWT_SECRET", "TOKEN_SECRET")
+
+secrets_app: typer.Typer = typer.Typer(
+    name="secrets",
+    help="Generate and rotate application secrets.",
+    no_args_is_help=True,
+)
+
+
+def _generate(length: int) -> str:
+    """Return a URL-safe random secret with at least ``length`` bytes.
+
+    Args:
+        length (int): Number of random bytes of entropy.
+
+    Returns:
+        str: A URL-safe token (longer than ``length`` chars due to the
+        base64 encoding).
+    """
+    return secrets.token_urlsafe(length)
+
+
+def _rewrite_env(path: Path, new_values: dict[str, str]) -> tuple[list[str], list[str]]:
+    """Apply ``new_values`` to a ``.env`` file's content.
+
+    Existing ``KEY=...`` lines are replaced in place (preserving order
+    and surrounding lines); keys not present are appended at the end.
+
+    Args:
+        path (Path): The ``.env`` file (may not exist yet).
+        new_values (dict[str, str]): ``KEY -> new secret`` mapping.
+
+    Returns:
+        tuple[list[str], list[str]]: ``(updated_keys, appended_keys)``.
+    """
+    lines = path.read_text(encoding="utf-8").splitlines() if path.is_file() else []
+    remaining = dict(new_values)
+    updated: list[str] = []
+    out: list[str] = []
+    for line in lines:
+        stripped = line.lstrip()
+        replaced = False
+        for key in list(remaining):
+            if stripped.startswith(f"{key}="):
+                out.append(f"{key}={remaining.pop(key)}")
+                updated.append(key)
+                replaced = True
+                break
+        if not replaced:
+            out.append(line)
+    appended = list(remaining)
+    for key in appended:
+        out.append(f"{key}={remaining[key]}")
+    path.write_text("\n".join(out) + "\n", encoding="utf-8")
+    return updated, appended
+
+
+@secrets_app.command("rotate")
+def secrets_rotate(
+    keys: str = typer.Option(
+        ",".join(_DEFAULT_KEYS),
+        "--keys",
+        "-k",
+        help=(
+            "Comma-separated env var names to rotate. Defaults to "
+            "'JWT_SECRET,TOKEN_SECRET'."
+        ),
+    ),
+    env_file: str = typer.Option(
+        ".env",
+        "--env",
+        "-e",
+        help="Path to the .env file to rewrite.",
+    ),
+    length: int = typer.Option(
+        48,
+        "--length",
+        "-l",
+        min=16,
+        help="Bytes of entropy per secret (URL-safe encoded longer).",
+    ),
+    show: bool = typer.Option(
+        False,
+        "--print",
+        help="Print the generated secrets to stdout instead of writing .env.",
+    ),
+    no_backup: bool = typer.Option(
+        False,
+        "--no-backup",
+        help="Skip writing the .env.bak backup before rewriting.",
+    ),
+) -> None:
+    """Generate fresh secrets and write them to ``.env`` (or print them).
+
+    With ``--print`` nothing is written — the new values go to stdout so
+    you can pipe them into a secret manager. Otherwise the ``.env`` file
+    is rewritten in place (existing keys replaced, missing keys
+    appended) after a ``.env.bak`` backup.
+    """
+    names = [k.strip() for k in keys.split(",") if k.strip()]
+    if not names:
+        typer.echo("error: --keys produced no names.", err=True)
+        raise typer.Exit(2)
+
+    new_values = {name: _generate(length) for name in names}
+
+    if show:
+        for name, value in new_values.items():
+            typer.echo(f"{name}={value}")
+        return
+
+    path = Path(env_file).expanduser()
+    if path.is_file() and not no_backup:
+        backup = path.with_suffix(path.suffix + ".bak")
+        backup.write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+        typer.echo(f"Backed up {path} -> {backup}")
+
+    updated, appended = _rewrite_env(path, new_values)
+    for key in updated:
+        typer.echo(f"rotated {key}")
+    for key in appended:
+        typer.echo(f"added {key}")
+    typer.echo(
+        "Done. Rotating JWT_SECRET invalidates existing tokens — "
+        "restart the service to load the new values."
+    )
+
+
+__all__: list[str] = [
+    "secrets_app",
+]

tempest_fastapi_sdk-0.47.0/tests/cli/test_db_seed.py

@@ -0,0 +1,107 @@
+"""Tests for ``tempest db seed``."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import types
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+from sqlalchemy import String, select
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import Mapped, mapped_column
+from typer.testing import CliRunner
+
+from tempest_fastapi_sdk import BaseModel
+from tempest_fastapi_sdk.cli.main import app
+
+runner = CliRunner()
+
+
+class _SeedThingModel(BaseModel):
+    """Row inserted by the seed callable under test."""
+
+    __tablename__ = "seed_thing"
+
+    name: Mapped[str] = mapped_column(String(50), nullable=False)
+
+
+async def _seed(session: AsyncSession) -> int:
+    """Async seed callable: insert two rows, return the count."""
+    session.add_all([_SeedThingModel(name="a"), _SeedThingModel(name="b")])
+    await session.flush()
+    return 2
+
+
+def _sync_seed(session: AsyncSession) -> None:
+    """Sync seed callable: insert one row, return nothing."""
+    session.add(_SeedThingModel(name="sync"))
+
+
+# Expose the callables via an importable dotted module.
+_module = types.ModuleType("cli_seed_module")
+_module.seed = _seed  # type: ignore[attr-defined]
+_module.sync_seed = _sync_seed  # type: ignore[attr-defined]
+sys.modules["cli_seed_module"] = _module
+
+
+@pytest.fixture
+def project_db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[str]:
+    """Fresh on-disk SQLite with the seed table created."""
+    monkeypatch.chdir(tmp_path)
+    db_path = tmp_path / "app.db"
+    url = f"sqlite+aiosqlite:///{db_path}"
+    monkeypatch.setenv("DATABASE_URL", url)
+
+    async def _create_schema() -> None:
+        engine = create_async_engine(url)
+        async with engine.begin() as conn:
+            await conn.run_sync(BaseModel.metadata.create_all)
+        await engine.dispose()
+
+    asyncio.run(_create_schema())
+    yield url
+
+
+def _count_rows(url: str) -> int:
+    async def _run() -> int:
+        engine = create_async_engine(url)
+        try:
+            async with AsyncSession(engine) as session:
+                result = await session.execute(select(_SeedThingModel))
+                return len(list(result.scalars().all()))
+        finally:
+            await engine.dispose()
+
+    return asyncio.run(_run())
+
+
+class TestSeed:
+    def test_async_seed_runs_and_commits(self, project_db: str) -> None:
+        result = runner.invoke(app, ["db", "seed", "--seed", "cli_seed_module:seed"])
+        assert result.exit_code == 0, result.stdout + result.stderr
+        assert "(2 rows)" in result.stdout
+        assert _count_rows(project_db) == 2
+
+    def test_sync_seed_runs(self, project_db: str) -> None:
+        result = runner.invoke(
+            app, ["db", "seed", "--seed", "cli_seed_module:sync_seed"]
+        )
+        assert result.exit_code == 0, result.stdout + result.stderr
+        assert _count_rows(project_db) == 1
+
+
+class TestSeedErrors:
+    def test_bad_spec_errors(self, project_db: str) -> None:
+        result = runner.invoke(app, ["db", "seed", "--seed", "nocolon"])
+        assert result.exit_code == 2
+
+    def test_not_callable_errors(self, project_db: str) -> None:
+        result = runner.invoke(app, ["db", "seed", "--seed", "cli_seed_module:__doc__"])
+        assert result.exit_code == 2
+
+    def test_missing_module_errors(self, project_db: str) -> None:
+        result = runner.invoke(app, ["db", "seed", "--seed", "no.such.module:seed"])
+        assert result.exit_code == 2