# Flow F6 — Service startup + schema migration

> One-shot per process start. Idempotent migrator (`CREATE ... IF NOT EXISTS`). Post-B9 the migrator additionally `DROP TABLE IF EXISTS orthophotos / gps_corrections` for fielded edge devices that previously ran the legacy schema.

## Description

`Program.cs` builds the DI graph from environment, runs `DatabaseMigrator.Migrate(db)` once inside a startup scope, then starts serving HTTP. The migrator only owns the 4 tables this service is responsible for (`vehicles`, `missions`, `waypoints`, `map_objects`); the borrowed tables (`media`, `annotations`, `detection`) are migrated by their owner services in their own startups.

## Preconditions

- `DATABASE_URL` resolves (env or hardcoded dev fallback).
- `postgres-local` is reachable.
- The `azaion` database itself exists in PostgreSQL (created at provisioning time, NOT by this migrator).

## Sequence Diagram

```mermaid
sequenceDiagram
    autonumber
    participant Docker as Docker / Watchtower
    participant Host as 07_host (Program.cs)
    participant Cfg as IConfiguration
    participant Identity as 05_identity
    participant DI as DI container
    participant Migrator as DatabaseMigrator
    participant DB as postgres-local

    Docker->>Host: ENTRYPOINT dotnet Azaion.Missions.dll
    Host->>Cfg: read DATABASE_URL → ConvertPostgresUrl → Npgsql connection string
    Host->>Cfg: read JWT_SECRET (env or hardcoded fallback)
    Host->>Identity: AddJwtAuth(jwtSecret) — DI registration only, no network
    Host->>DI: register controllers + middleware + scoped AppDataConnection + scoped services
    Host->>DI: build Host
    Host->>Migrator: scope.Resolve<AppDataConnection>(); Migrate(db)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS vehicles (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS missions (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS waypoints (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS map_objects (...)
    Migrator->>DB: CREATE INDEX IF NOT EXISTS ix_missions_vehicle_id, ix_waypoints_mission_id, ix_map_objects_mission_id
    Migrator->>DB: DROP TABLE IF EXISTS orthophotos
    Migrator->>DB: DROP TABLE IF EXISTS gps_corrections
    note right of Migrator: B9 one-shot. Idempotent on devices that already cleaned up.
    Migrator-->>Host: void
    Host->>Host: register ErrorHandlingMiddleware FIRST in pipeline
    Host->>Host: UseAuthentication / UseAuthorization
    Host->>Host: MapControllers + MapGet("/health") + UseSwagger
    Host->>Docker: app.Run() — listening on 0.0.0.0:8080
```

## Flowchart

```mermaid
flowchart TD
    Start([Container start]) --> ReadCfg[Read DATABASE_URL + JWT_SECRET]
    ReadCfg --> RegDI[DI registrations: controllers, middleware, scoped DB + services]
    RegDI --> Build[Build Host]
    Build --> OpenScope[Open startup scope]
    OpenScope --> Migrate[Run DatabaseMigrator.Migrate]
    Migrate --> Create["CREATE TABLE IF NOT EXISTS x4 + indexes"]
    Create --> Drop["DROP TABLE IF EXISTS orthophotos, gps_corrections (B9)"]
    Drop --> Pipeline[Wire pipeline: error MW first, auth, controllers, /health, Swagger]
    Pipeline --> Run([app.Run on :8080])
    Migrate -. on failure .-> Crash([Process exits non-zero — Watchtower restarts])
```

## Data Flow

| Step | From | To | Data | Format |
|------|------|----|------|--------|
| 1 | Environment / appsettings | `Program.cs` | `DATABASE_URL`, `JWT_SECRET` | string |
| 2 | `Program.cs` | DI container | service registrations | C# code |
| 3 | `DatabaseMigrator` | `postgres-local` | DDL statements (CREATE / INDEX / DROP) | SQL |
| 4 | `Program.cs` | OS / Docker | bind to `0.0.0.0:8080` | TCP listener |

## Error Scenarios

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| `postgres-local` unreachable | Migrate step | Npgsql `IOException` / `SocketException` | Process exits non-zero. Watchtower restarts; `flight-gate` prevents restart mid-mission. **Fix**: ensure `postgres-local` healthcheck passes before `missions` starts (compose `depends_on` with `condition: service_healthy`) |
| `azaion` database missing | Migrate step | Npgsql `3D000` (`invalid_catalog_name`) | Process exits. Operator must create the database — provisioning concern, not this service. Documented in `../../suite/_docs/00_top_level_architecture.md` |
| `DROP TABLE IF EXISTS orthophotos` fails because table is locked by `gps-denied` | B9 one-shot | Lock timeout or `55006` | Process exits, Watchtower restarts in a few seconds. **Out-of-band ordering**: deploy `gps-denied` FIRST so it has its own copy of the schema before `missions` drops the legacy tables. Documented in B9 ticket |
| One `CREATE TABLE` succeeds, the next fails | Mid-Migrate | Npgsql exception on later statement | Process exits. Each statement is individually idempotent (`IF NOT EXISTS`) so the next startup retries safely from the start. No partial-migration cleanup needed |
| Wrong PostgreSQL version (e.g., < 13) | Migrate step | Specific syntax errors in newer features | Process exits. Suite-supported version is PG 16+; older devices need a Postgres upgrade |
| `DATABASE_URL` malformed (e.g. user password contains `@`) | `ConvertPostgresUrl` | parse failure / silent mis-parse | `ConvertPostgresUrl` does NOT URL-decode user/password — caveat for credentials with `@`, `:`, `/`, `%`. `07_host` Caveats. Mitigation: avoid those chars in passwords, OR pass a raw Npgsql key=value string instead of a URL |

## Performance Expectations

| Metric | Target | Notes |
|--------|--------|-------|
| Cold start total time | <2 seconds typical on Jetson Orin | Migrator runs ~10 DDL statements; all are no-ops on a steady-state device |
| Cold start with legacy GPS-Denied tables present | +1 second | First-time-on-device B9 `DROP` adds two DDL statements |
| Crash recovery (Watchtower restart) | ~10 seconds | Container restart latency dominates |