# Persistence and database

StellaOps uses PostgreSQL as the canonical system of record. This document
summarizes the persistence rules, schema layout, and migration approach.

Principles
- Determinism first: stable ordering, UTC timestamps, canonical JSON for hashes.
- Tenant isolation: every row carries tenant_id and row level security is used.
- Gradual migration: Mongo to Postgres via a strangler approach with rollback.
- JSONB for flexibility: semi structured payloads stay JSONB; core entities are normalized.

Schema families (authoritative DDLs)
- authority, vuln, vex, scheduler, notify, policy
- packs are included with policy
- issuer and audit are staged or proposed

Operational inputs
- Config template: docs/db/persistence-config-template.yaml
- Cluster provisioning: docs/db/cluster-provisioning.md
- Local dev: docs/db/local-postgres.md

Change control and verification
- Follow rules in docs/db/RULES.md for naming, constraints, and RLS.
- Use docs/db/SPECIFICATION.md as the schema source of truth.
- Verify changes using docs/db/VERIFICATION.md before release.

Migration notes
- Conversion planning: docs/db/CONVERSION_PLAN.md
- Module phased tasks: docs/db/tasks/PHASE_*.md
- Reports and verification evidence live under docs/db/reports/

Related references
- ADR: docs/adr/0001-postgresql-for-control-plane.md
- Module architecture: docs/modules/*/architecture.md