aegis-stack 0.8.0__tar.gz → 0.9.0__tar.gz

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/CHANGELOG.md

@@ -5,6 +5,35 @@
   The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Traffic monitor ("who's hammering you")**: Overseer's Backend modal gains a
+  **Traffic** tab showing top source IPs by request volume over a rolling
+  window, flagging any single source that dominates traffic (read-time
+  dominance check). A `TrafficMiddleware` tallies requests per client IP
+  (proxy-aware via `get_client_ip`), backed by Redis when the component is
+  present (shared across the webserver/scheduler/worker processes, survives a
+  restart for the bucket TTL) and an in-memory store otherwise (per-process,
+  resets on restart) — the same Redis-or-dict fallback `CacheService` uses, so
+  the live panel works with or without Redis. Recording is fire-and-forget so
+  it never adds latency to the request path. Admin-gated `GET
+  /api/v1/traffic/sources` (open on auth-less stacks, matching `/health/`).
+  Tunable via `TRAFFIC_MONITOR_ENABLED`, `TRAFFIC_WINDOW_HOURS`,
+  `TRAFFIC_DOMINANCE_SHARE`, `TRAFFIC_DOMINANCE_FLOOR`.
+
+### Changed
+
+- **Rolling deploy no longer depends on `docker-rollout`**: `aegis deploy
+  --rolling` now rolls the webserver in-process, starting a second replica
+  and polling its container HEALTHCHECK status (`healthy`/`unhealthy`/
+  `starting`) instead of shelling out to the `docker-rollout` plugin. The
+  container's own HEALTHCHECK budget (`start_period + retries x interval`)
+  is the single source of truth, so a slow-but-healthy boot is never rolled
+  back by a wall clock, and no extra tooling needs to be installed on the
+  deploy host. `--rollout-timeout` is now only a long runaway-guard ceiling.
+
 ## [0.8.0] - 2026-06-15
 
 ### Added

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: aegis-stack
-Version: 0.8.0
+Version: 0.9.0
 Summary: A production-ready FastAPI platform with modular components and a built-in control plane. Try: uvx aegis-stack init my-project
-Project-URL: Homepage, https://docs.aegis-stack.io/
+Project-URL: Homepage, https://aegis-stack.io
 Project-URL: Documentation, https://docs.aegis-stack.io/
 Project-URL: Repository, https://github.com/lbedner/aegis-stack.git
 Project-URL: Issues, https://github.com/lbedner/aegis-stack/issues
 Author-email: Leonard Bedner <gamecoder99@gmail.com>
 License: MIT
 License-File: LICENSE
-Keywords: boilerplate,cli,cookiecutter,database,fastapi,generator,python,scaffold,scheduler,stack,template,uvx,worker
+Keywords: boilerplate,cli,copier,database,fastapi,generator,python,scaffold,scheduler,stack,template,uvx,worker
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -30,8 +30,9 @@ Requires-Dist: copier<9.15,>=9.11.2
 Requires-Dist: filelock>=3.20.1
 Requires-Dist: packaging>=24.0
 Requires-Dist: pillow>=12.2.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0.0
-Requires-Dist: typer==0.26.7
+Requires-Dist: typer==0.26.8
 Requires-Dist: urllib3>=2.7.0
 Provides-Extra: dev
 Requires-Dist: aegis-plugin-test; extra == 'dev'
@@ -85,7 +86,7 @@ Aegis Stack scaffolds complete FastAPI applications with auth, payments, workers
 ## Quick Start
 
 ```bash
-uvx aegis-stack init my-api && cd my-api && make serve
+uvx aegis-stack init my-api
 ```
 
 `init` opens a full-screen guided setup that walks through every component and service with explanations. Prefer the classic one-line prompts? Pass `--quick`.
@@ -94,6 +95,9 @@ uvx aegis-stack init my-api && cd my-api && make serve
 <summary><strong>More examples</strong></summary>
 
 ```bash
+# Skip the guided setup, use the classic one-line prompts
+uvx aegis-stack init my-api --quick
+
 # Add user authentication out of the box
 uvx aegis-stack init user-app --services auth
 
@@ -106,7 +110,7 @@ uvx aegis-stack init full-app --services auth,payment,comms --components worker,
 
 </details>
 
-> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Use `aegis --lang <code>` or set `AEGIS_LANG`.
+> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Run e.g. `uvx aegis-stack --lang zh init my-api`, or set `AEGIS_LANG=zh`.
 
 **Installation alternatives:** See the [Installation Guide](https://docs.aegis-stack.io/installation/) for `uv tool install`, `pip install`, and development setup.
 
@@ -126,7 +130,7 @@ uvx aegis-stack init full-app --services auth,payment,comms --components worker,
 | **[CLI](https://docs.aegis-stack.io/cli-reference/)** | Typer, first-class system interface | ![Always](https://img.shields.io/badge/-always_on-2ea043) |
 | **[Frontend](https://docs.aegis-stack.io/components/frontend/)** | Flet, ships with the Overseer system dashboard | ![Always](https://img.shields.io/badge/-always_on-2ea043) |
 | **[Cache](https://docs.aegis-stack.io/components/)** | Redis for caching, sessions, pub/sub | ![Optional](https://img.shields.io/badge/-optional-blue) |
-| **[Database](https://docs.aegis-stack.io/components/database/)** | Postgres or SQLite + SQLModel ORM | ![Optional](https://img.shields.io/badge/-optional-blue) |
+| **[Database](https://docs.aegis-stack.io/components/database/)** | Postgres (self-hosted or Neon serverless) or SQLite + SQLModel ORM | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Inference](https://docs.aegis-stack.io/components/)** | Local AI models via Ollama | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Ingress](https://docs.aegis-stack.io/components/ingress/)** | Traefik v3 reverse proxy with TLS | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Observability](https://docs.aegis-stack.io/components/observability/)** | Pydantic Logfire tracing + metrics + logging | ![Optional](https://img.shields.io/badge/-optional-blue) |
@@ -165,7 +169,7 @@ Aegis Stack is the orchestration layer. Services and components wire into best-i
 <td align="center" width="16.66%"><a href="https://github.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/github-dark.svg"><img src="docs/images/integrations/github.svg" loading="lazy" style="height:32px;width:auto" alt="GitHub" title="GitHub: OAuth provider" /></picture></a></td>
 <td align="center" width="16.66%"><a href="https://www.google.com"><img src="docs/images/integrations/google.svg" loading="lazy" style="height:32px;width:auto" alt="Google" title="Google: AI provider and OAuth" /></a></td>
 <td align="center" width="16.66%"><a href="https://www.langchain.com"><img src="docs/images/integrations/langchain.png" loading="lazy" style="height:32px;width:auto" alt="LangChain" title="LangChain: AI provider abstraction" /></a></td>
-<td align="center" width="16.66%"><a href="https://neon.tech"><img src="docs/images/integrations/neon.svg" loading="lazy" style="height:32px;width:auto" alt="Neon" title="Neon: Serverless Postgres (planned)" /></a></td>
+<td align="center" width="16.66%"><a href="https://neon.tech"><img src="docs/images/integrations/neon.svg" loading="lazy" style="height:32px;width:auto" alt="Neon" title="Neon: Serverless Postgres, database provider" /></a></td>
 <td align="center" width="16.66%"><a href="https://ollama.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/ollama-dark.svg"><img src="docs/images/integrations/ollama.svg" loading="lazy" style="height:32px;width:auto" alt="Ollama" title="Ollama: Local LLM runtime" /></picture></a></td>
 <td align="center" width="16.66%"><a href="https://plausible.io"><img src="docs/images/integrations/plausibleanalytics.svg" loading="lazy" style="height:32px;width:auto" alt="Plausible" title="Plausible: Analytics source for Insights service" /></a></td>
 </tr>

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/README.md

@@ -27,7 +27,7 @@ Aegis Stack scaffolds complete FastAPI applications with auth, payments, workers
 ## Quick Start
 
 ```bash
-uvx aegis-stack init my-api && cd my-api && make serve
+uvx aegis-stack init my-api
 ```
 
 `init` opens a full-screen guided setup that walks through every component and service with explanations. Prefer the classic one-line prompts? Pass `--quick`.
@@ -36,6 +36,9 @@ uvx aegis-stack init my-api && cd my-api && make serve
 <summary><strong>More examples</strong></summary>
 
 ```bash
+# Skip the guided setup, use the classic one-line prompts
+uvx aegis-stack init my-api --quick
+
 # Add user authentication out of the box
 uvx aegis-stack init user-app --services auth
 
@@ -48,7 +51,7 @@ uvx aegis-stack init full-app --services auth,payment,comms --components worker,
 
 </details>
 
-> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Use `aegis --lang <code>` or set `AEGIS_LANG`.
+> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Run e.g. `uvx aegis-stack --lang zh init my-api`, or set `AEGIS_LANG=zh`.
 
 **Installation alternatives:** See the [Installation Guide](https://docs.aegis-stack.io/installation/) for `uv tool install`, `pip install`, and development setup.
 
@@ -68,7 +71,7 @@ uvx aegis-stack init full-app --services auth,payment,comms --components worker,
 | **[CLI](https://docs.aegis-stack.io/cli-reference/)** | Typer, first-class system interface | ![Always](https://img.shields.io/badge/-always_on-2ea043) |
 | **[Frontend](https://docs.aegis-stack.io/components/frontend/)** | Flet, ships with the Overseer system dashboard | ![Always](https://img.shields.io/badge/-always_on-2ea043) |
 | **[Cache](https://docs.aegis-stack.io/components/)** | Redis for caching, sessions, pub/sub | ![Optional](https://img.shields.io/badge/-optional-blue) |
-| **[Database](https://docs.aegis-stack.io/components/database/)** | Postgres or SQLite + SQLModel ORM | ![Optional](https://img.shields.io/badge/-optional-blue) |
+| **[Database](https://docs.aegis-stack.io/components/database/)** | Postgres (self-hosted or Neon serverless) or SQLite + SQLModel ORM | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Inference](https://docs.aegis-stack.io/components/)** | Local AI models via Ollama | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Ingress](https://docs.aegis-stack.io/components/ingress/)** | Traefik v3 reverse proxy with TLS | ![Optional](https://img.shields.io/badge/-optional-blue) |
 | **[Observability](https://docs.aegis-stack.io/components/observability/)** | Pydantic Logfire tracing + metrics + logging | ![Optional](https://img.shields.io/badge/-optional-blue) |
@@ -107,7 +110,7 @@ Aegis Stack is the orchestration layer. Services and components wire into best-i
 <td align="center" width="16.66%"><a href="https://github.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/github-dark.svg"><img src="docs/images/integrations/github.svg" loading="lazy" style="height:32px;width:auto" alt="GitHub" title="GitHub: OAuth provider" /></picture></a></td>
 <td align="center" width="16.66%"><a href="https://www.google.com"><img src="docs/images/integrations/google.svg" loading="lazy" style="height:32px;width:auto" alt="Google" title="Google: AI provider and OAuth" /></a></td>
 <td align="center" width="16.66%"><a href="https://www.langchain.com"><img src="docs/images/integrations/langchain.png" loading="lazy" style="height:32px;width:auto" alt="LangChain" title="LangChain: AI provider abstraction" /></a></td>
-<td align="center" width="16.66%"><a href="https://neon.tech"><img src="docs/images/integrations/neon.svg" loading="lazy" style="height:32px;width:auto" alt="Neon" title="Neon: Serverless Postgres (planned)" /></a></td>
+<td align="center" width="16.66%"><a href="https://neon.tech"><img src="docs/images/integrations/neon.svg" loading="lazy" style="height:32px;width:auto" alt="Neon" title="Neon: Serverless Postgres, database provider" /></a></td>
 <td align="center" width="16.66%"><a href="https://ollama.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/ollama-dark.svg"><img src="docs/images/integrations/ollama.svg" loading="lazy" style="height:32px;width:auto" alt="Ollama" title="Ollama: Local LLM runtime" /></picture></a></td>
 <td align="center" width="16.66%"><a href="https://plausible.io"><img src="docs/images/integrations/plausibleanalytics.svg" loading="lazy" style="height:32px;width:auto" alt="Plausible" title="Plausible: Analytics source for Insights service" /></a></td>
 </tr>

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/aegis/__init__.py

@@ -2,4 +2,4 @@
 Aegis Stack CLI - Component generation and project management tools.
 """
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/aegis/cli/guided.py

@@ -49,6 +49,7 @@ from rich.text import Text
 from ..constants import (
     DOCS_BASE_URL,
     AIProviders,
+    PostgresProviders,
     StorageBackends,
     WorkerBackends,
 )
@@ -418,18 +419,26 @@ class GuidedSelectionUI:
         choices = [
             _Choice(
                 StorageBackends.MEMORY,
-                "In-memory",
-                "No persistence. Jobs reset on restart — skip if unsure.",
+                _g("choice.name.in_memory", "In-memory"),
+                _g(
+                    "choice.scheduler.memory",
+                    "No persistence. Jobs reset on restart — skip if unsure.",
+                ),
             ),
             _Choice(
                 StorageBackends.SQLITE,
                 "SQLite",
-                "Persist job history in a file database.",
+                _g(
+                    "choice.scheduler.sqlite", "Persist job history in a file database."
+                ),
             ),
             _Choice(
                 StorageBackends.POSTGRES,
                 "PostgreSQL",
-                "Persist job history, production-grade.",
+                _g(
+                    "choice.scheduler.postgres",
+                    "Persist job history, production-grade.",
+                ),
             ),
         ]
         return choices[
@@ -448,20 +457,29 @@ class GuidedSelectionUI:
             _Choice(
                 WorkerBackends.ARQ,
                 "arq",
-                "Simple, well-tested async worker with minimal "
-                "configuration. Best for I/O-bound tasks. The default.",
+                _g(
+                    "choice.worker.arq",
+                    "Simple, well-tested async worker with minimal "
+                    "configuration. Best for I/O-bound tasks. The default.",
+                ),
             ),
             _Choice(
                 WorkerBackends.DRAMATIQ,
                 "Dramatiq",
-                "Multi-process actor model. Best for CPU-bound tasks that "
-                "benefit from multiple OS processes.",
+                _g(
+                    "choice.worker.dramatiq",
+                    "Multi-process actor model. Best for CPU-bound tasks that "
+                    "benefit from multiple OS processes.",
+                ),
             ),
             _Choice(
                 WorkerBackends.TASKIQ,
                 "TaskIQ",
-                "Async-native with per-queue brokers and Redis Streams "
-                "transport with acknowledgements.",
+                _g(
+                    "choice.worker.taskiq",
+                    "Async-native with per-queue brokers and Redis Streams "
+                    "transport with acknowledgements.",
+                ),
             ),
         ]
         return choices[
@@ -472,20 +490,23 @@ class GuidedSelectionUI:
             )
         ].value
 
-    def choose_database_engine(self, context: str) -> str:
+    def choose_database_engine(self, context: str) -> tuple[str, str | None]:
         choices = [
             _Choice(
                 StorageBackends.SQLITE,
                 "SQLite",
-                "Zero-config file database. Great for development.",
+                _g(
+                    "choice.db.sqlite",
+                    "Zero-config file database. Great for development.",
+                ),
             ),
             _Choice(
                 StorageBackends.POSTGRES,
                 "PostgreSQL",
-                "Production-grade, pooled connections.",
+                _g("choice.db.postgres", "Production-grade, pooled connections."),
             ),
         ]
-        return choices[
+        engine = choices[
             self._select(
                 _g(
                     "prompt.database_engine",
@@ -496,12 +517,53 @@ class GuidedSelectionUI:
                 crumb="amend",
             )
         ].value
+        if engine == StorageBackends.POSTGRES:
+            return engine, self._choose_postgres_provider(context)
+        return engine, None
+
+    def _choose_postgres_provider(self, context: str) -> str:
+        """ONE screen for the PostgreSQL host: local container vs Neon (vs ...)."""
+        choices = [
+            _Choice(
+                PostgresProviders.CONTAINER,
+                "Local container",
+                _g(
+                    "choice.db_provider.container",
+                    "Local postgres:16 container, dev and prod.",
+                ),
+            ),
+            _Choice(
+                PostgresProviders.NEON,
+                "Neon",
+                _g(
+                    "choice.db_provider.neon",
+                    "Serverless Postgres: cloud in prod, local container in dev.",
+                ),
+            ),
+        ]
+        return choices[
+            self._select(
+                _g(
+                    "prompt.postgres_provider",
+                    "PostgreSQL host for {context}",
+                    context=context,
+                ),
+                choices,
+                crumb="amend",
+            )
+        ].value
 
     def configure_auth(self, service_name: str) -> str:
         choices = [
-            _Choice("basic", "Basic", "Email and password with JWT sessions."),
-            _Choice("rbac", "RBAC", "Adds roles and permissions."),
-            _Choice("org", "Org", "Multi-tenant organizations."),
+            _Choice(
+                "basic",
+                "Basic",
+                _g("choice.auth.basic", "Email and password with JWT sessions."),
+            ),
+            _Choice(
+                "rbac", "RBAC", _g("choice.auth.rbac", "Adds roles and permissions.")
+            ),
+            _Choice("org", "Org", _g("choice.auth.org", "Multi-tenant organizations.")),
         ]
         return choices[
             self._select(
@@ -514,9 +576,18 @@ class GuidedSelectionUI:
     ) -> tuple[str, str, list[str], bool, bool]:
         framework = [
             _Choice(
-                "pydantic-ai", "Pydantic AI", "Typed and lightweight. The default."
+                "pydantic-ai",
+                "Pydantic AI",
+                _g(
+                    "choice.framework.pydantic_ai",
+                    "Typed and lightweight. The default.",
+                ),
+            ),
+            _Choice(
+                "langchain",
+                "LangChain",
+                _g("choice.framework.langchain", "Large ecosystem, many integrations."),
             ),
-            _Choice("langchain", "LangChain", "Large ecosystem, many integrations."),
         ]
         fw = framework[
             self._select(
@@ -529,17 +600,22 @@ class GuidedSelectionUI:
             return self._configure_ai_extras(fw, existing_engine)
         backend = [
             _Choice(
-                StorageBackends.MEMORY, "In-memory", "No history, nothing to set up."
+                StorageBackends.MEMORY,
+                _g("choice.name.in_memory", "In-memory"),
+                _g("choice.storage.memory", "No history, nothing to set up."),
             ),
             _Choice(
                 StorageBackends.SQLITE,
                 "SQLite",
-                "Persistent chat history in a file database.",
+                _g(
+                    "choice.storage.sqlite",
+                    "Persistent chat history in a file database.",
+                ),
             ),
             _Choice(
                 StorageBackends.POSTGRES,
                 "PostgreSQL",
-                "Persistent and production-grade.",
+                _g("choice.storage.postgres", "Persistent and production-grade."),
             ),
         ]
         be = backend[
@@ -555,7 +631,12 @@ class GuidedSelectionUI:
         self, fw: str, be: str
     ) -> tuple[str, str, list[str], bool, bool]:
         provider_choices = [
-            _Choice(provider_id, name, f"{description}. {pricing}.")
+            _Choice(
+                provider_id,
+                name,
+                f"{_g(f'choice.provider.{provider_id}.desc', description)}. "
+                f"{_g(f'choice.provider.{provider_id}.pricing', pricing)}.",
+            )
             for provider_id, name, description, pricing, _ in AIProviders.PROVIDER_INFO
         ]
         preselected = {

{aegis_stack-0.8.0 → aegis_stack-0.9.0}/aegis/cli/interactive.py

@@ -22,6 +22,7 @@ from ..constants import (
     ComponentNames,
     Messages,
     OllamaMode,
+    PostgresProviders,
     StorageBackends,
     WorkerBackends,
 )
@@ -132,9 +133,67 @@ def get_database_engine_selection() -> str | None:
 
 
 def clear_database_engine_selection() -> None:
-    """Clear stored database engine selection (useful for testing)."""
-    global _database_engine_selection
+    """Clear the stored database engine and its PostgreSQL host (useful for testing).
+
+    The host is a sub-property of the engine, so clearing the engine must also
+    clear the host or a stale provider could be reused after the engine resets.
+    """
+    global _database_engine_selection, _postgres_provider_selection
     _database_engine_selection = None
+    _postgres_provider_selection = None
+
+
+# Global variable to store the PostgreSQL host (provider) selection. Neon is a
+# provider of the postgres engine, not a separate engine, so it lives alongside
+# the engine choice rather than inside it.
+_postgres_provider_selection: str | None = None
+
+
+def select_postgres_provider(context: str = "Database") -> str:
+    """Interactive PostgreSQL host selection (local container vs Neon, ...).
+
+    Only meaningful once the engine is postgres. Memoized like the engine so a
+    project resolves one host. Returns a ``PostgresProviders`` value.
+    """
+    global _postgres_provider_selection
+
+    if _postgres_provider_selection is not None:
+        return _postgres_provider_selection
+
+    choices = [
+        questionary.Choice(
+            title=t("interactive.db_provider_container"),
+            value=PostgresProviders.CONTAINER,
+        ),
+        questionary.Choice(
+            title=t("interactive.db_provider_neon"),
+            value=PostgresProviders.NEON,
+        ),
+    ]
+
+    result = questionary.select(
+        t("interactive.db_provider_select"),
+        choices=choices,
+        default=PostgresProviders.CONTAINER,
+        style=brand.questionary_style(),
+    ).ask()
+
+    if result is None:
+        raise typer.Abort()
+
+    _postgres_provider_selection = result
+    return result
+
+
+def get_postgres_provider_selection() -> str | None:
+    """Get the current PostgreSQL host (provider) selection."""
+    return _postgres_provider_selection
+
+
+def clear_postgres_provider_selection() -> None:
+    """Clear stored PostgreSQL host selection (useful for testing)."""
+    global _postgres_provider_selection
+    _postgres_provider_selection = None
 
 
 def select_worker_backend() -> str:
@@ -210,6 +269,10 @@ class ProjectSelection:
     services: list[str] = field(default_factory=list)
     scheduler_backend: str = StorageBackends.MEMORY
     database_engine: str | None = None
+    # PostgreSQL host, only meaningful when database_engine is postgres. Neon is
+    # a provider of the postgres engine, encoded into the component bracket
+    # (``database[neon]``) for downstream generation.
+    postgres_provider: str = PostgresProviders.CONTAINER
     database_added_by_scheduler: bool = False
 
 
@@ -240,7 +303,7 @@ class SelectionUI(Protocol):
 
     def choose_worker_backend(self) -> str: ...
 
-    def choose_database_engine(self, context: str) -> str: ...
+    def choose_database_engine(self, context: str) -> tuple[str, str | None]: ...
 
     def choose_scheduler_backend(self) -> str: ...
 
@@ -288,8 +351,11 @@ class TyperSelectionUI:
     def choose_worker_backend(self) -> str:
         return select_worker_backend()
 
-    def choose_database_engine(self, context: str) -> str:
-        return select_database_engine(context=context)
+    def choose_database_engine(self, context: str) -> tuple[str, str | None]:
+        engine = select_database_engine(context=context)
+        if engine == StorageBackends.POSTGRES:
+            return engine, select_postgres_provider(context=context)
+        return engine, None
 
     def choose_scheduler_backend(self) -> str:
         # Quick-mode shape preserved exactly: the persistence yes/no, then
@@ -383,6 +449,15 @@ def _step_database(
         return
 
     state.components.append(ComponentNames.DATABASE)
+
+    # Engine, then (for postgres) the host: SQLite / PostgreSQL, and when
+    # PostgreSQL, a local container vs Neon. Only postgres pins the engine onto
+    # state; SQLite stays the implicit default (plain ``database``).
+    engine, provider = ui.choose_database_engine(context="Database")
+    if engine == StorageBackends.POSTGRES:
+        state.database_engine = StorageBackends.POSTGRES
+        state.postgres_provider = provider or PostgresProviders.CONTAINER
+
     if ComponentNames.SCHEDULER in state.components:
         ui.echo(f"\n{t('interactive.bonus_backup')}")
         ui.success(t("interactive.backup_desc"))
@@ -442,9 +517,16 @@ def run_project_selection(ui: SelectionUI) -> ProjectSelection:
     # and downstream resolution.
     if ComponentNames.DATABASE in state.components and state.database_engine:
         db_index = state.components.index(ComponentNames.DATABASE)
-        state.components[db_index] = (
-            f"{ComponentNames.DATABASE}[{state.database_engine}]"
-        )
+        # Neon is a postgres provider: encode it as database[neon] so the
+        # generator normalizes it back to engine=postgres + provider=neon.
+        if (
+            state.database_engine == StorageBackends.POSTGRES
+            and state.postgres_provider == PostgresProviders.NEON
+        ):
+            token = PostgresProviders.NEON
+        else:
+            token = state.database_engine
+        state.components[db_index] = f"{ComponentNames.DATABASE}[{token}]"
     if (
         ComponentNames.SCHEDULER in state.components
         and state.scheduler_backend != StorageBackends.MEMORY
@@ -547,7 +629,11 @@ def _project_database_engine(state: ProjectSelection) -> str | None:
     for comp in state.components:
         base, _, rest = comp.partition("[")
         if base == ComponentNames.DATABASE:
-            return rest.rstrip("]") if rest else StorageBackends.SQLITE
+            engine = rest.rstrip("]") if rest else StorageBackends.SQLITE
+            # Neon is a postgres provider; engine-flavored reuse sees postgres.
+            if engine == PostgresProviders.NEON:
+                return StorageBackends.POSTGRES
+            return engine
     return None
 
 
@@ -806,6 +892,7 @@ def clear_all_ai_selections() -> None:
     clear_skip_llm_sync_selection()
     clear_ollama_mode_selection()
     clear_database_engine_selection()
+    clear_postgres_provider_selection()
     clear_auth_level_selection()