# Local PostgreSQL for StellaOps

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

## Quick start (Docker)

```bash
# 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`

Features enabled:
- `pg_stat_statements` for query performance analysis
- Pre-created schemas: authority, vuln, vex, scheduler, notify, policy, concelier, audit
- Extensions: pg_trgm, btree_gin, pgcrypto

Verify:
```bash
docker ps --filter name=stella-postgres
docker exec -it stella-postgres psql -U stella -d stella -c 'SELECT version();'
docker exec -it stella-postgres psql -U stella -d stella -c '\dn'  # List schemas
docker exec -it stella-postgres psql -U stella -d stella -c '\dx'  # List extensions
```

Stop/cleanup:
```bash
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 module storage
- Module repositories connect via their respective DataSource types using tenant-aware connections; for local work set your appsettings or environment to the connection string above.
- Integration tests 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 environment variables above.

## 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`.
- Schemas are pre-created via init scripts in `ops/devops/local-postgres/init/`.

## Operations guide

For production deployment, performance tuning, monitoring, and backup/restore procedures, see [`docs/operations/postgresql-guide.md`](../operations/postgresql-guide.md).