up

docs/db/local-postgres.md

@@ -47,3 +47,29 @@ docker volume rm stella-postgres-data
 - Image: `postgres:17` (latest GA at time of writing).
 - Healthcheck is built into the compose service; wait for `healthy` before running tests.
 - Keep volumes deterministic: the compose file names the volume `stella-postgres-data`.
+
+## Scheduler Mongo → Postgres backfill
+
+Use the new `Scheduler.Backfill` tool to copy Scheduler data from MongoDB into the Postgres schema.
+
+```bash
+dotnet run \
+  --project src/Scheduler/Tools/Scheduler.Backfill/Scheduler.Backfill.csproj \
+  --mongo "${MONGO_CONNECTION_STRING:-mongodb://localhost:27017}" \
+  --mongo-db "${MONGO_DATABASE:-stellaops_scheduler}" \
+  --pg "Host=localhost;Port=5432;Username=stella;Password=stella;Database=stella" \
+  --batch 500
+```
+
+Flags:
+- `--dry-run` to validate without writing.
+- `--batch` to tune insert batch size (defaults to 500).
+
+What it does:
+- Reads `schedules` and `runs` collections.
+- Serialises documents with `CanonicalJsonSerializer` for deterministic JSON.
+- Upserts into `scheduler.schedules` and `scheduler.runs` tables (created by migration `001_initial_schema.sql`).
+
+Verification tips:
+- Compare counts after backfill: `select count(*) from scheduler.schedules;` and `...runs;`.
+- Spot-check next-fire timing by comparing `cron_expression` and `timezone` with the Mongo source; deterministic ordering is preserved via canonical JSON.