git.stella-ops.org/docs/db/local-postgres.md

Local PostgreSQL for StellaOps (Scheduler focus)

This doc describes how to bring up a local PostgreSQL 17 instance for Scheduler development and tests.

Quick start (Docker)

# from repo root
docker compose -f ops/devops/local-postgres/docker-compose.yml up -d

Defaults:

• Host/Port: localhost:5432
• User: stella
• Password: stella
• Database: stella

Verify:

docker ps --filter name=stella-postgres
docker exec -it stella-postgres psql -U stella -d stella -c 'select version();'

Stop/cleanup:

docker compose -f ops/devops/local-postgres/docker-compose.yml down
# keep data
docker volume ls | grep stella-postgres-data
# remove data volume if you want a clean slate
docker volume rm stella-postgres-data

Connection strings

• ADO.NET: Host=localhost;Port=5432;Username=stella;Password=stella;Database=stella;Include Error Detail=true
• Npgsql env example:
  • PGHOST=localhost
  • PGPORT=5432
  • PGUSER=stella
  • PGPASSWORD=stella
  • PGDATABASE=stella

Using with Scheduler Postgres storage

• Scheduler Postgres repositories connect via SchedulerDataSource using tenant-aware connections; for local work set your appsettings or environment to the connection string above.
• Integration tests currently rely on Testcontainers; if Docker is available the tests will spin up their own isolated container. When Docker is unavailable, run against this local instance by exporting the variables above and disabling Testcontainers in your local run configuration if supported.

Notes

• 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.

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.