# State 005: Replacing H2 with PostgreSQL

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

State `005-postgres-database-replacement` is the first architecture-focused database transition after `004-containerized-compose-runtime`.

This change keeps the same baseline functional behavior, APIs, and runtime entry model from state `004`, while replacing the underlying database runtime from H2 to PostgreSQL.

## Why This State

The project needed a more production-like SQL engine without adding heavy setup overhead. PostgreSQL gives us that while keeping local Docker Compose usage straightforward.

This validates the SpecKit-first approach: define a focused architecture delta, generate the state, run smoke checks, and publish a clean generated code branch.

## What Changed

*   Added a PostgreSQL container runtime with deterministic init SQL.
*   Updated `account-service`, `position-service`, and `trade-processor` to use PostgreSQL datasource/driver settings.
*   Preserved baseline flow behavior (`F1` to `F4`) and existing REST/event contracts.
*   Added state-specific runtime scripts and smoke tests for PostgreSQL readiness + baseline compatibility.

## Spec + Decision Links

*   State spec pack: [/specs/postgres-database-replacement](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/specs/postgres-database-replacement.md)
*   ADR: [/docs/adr/006-state-005-use-postgres-for-database-replacement](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/adr/006-state-005-use-postgres-for-database-replacement.md)
*   Learning guide: [/docs/learning/state-005-postgres-database-replacement](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/learning/state-005-postgres-database-replacement.md)
*   Generated code branch: [code/generated-state-005-postgres-database-replacement](https://github.com/finos/traderX/tree/code/generated-state-005-postgres-database-replacement)
*   Compare vs parent (`004`): [code/generated-state-004-containerized-compose-runtime...code/generated-state-005-postgres-database-replacement](https://github.com/finos/traderX/compare/code%2Fgenerated-state-004-containerized-compose-runtime...code%2Fgenerated-state-005-postgres-database-replacement)

## Why This Matters For The Learning Graph

State `005` demonstrates that architecture substitutions can be done as isolated, reversible state transitions:

*   branch from a stable parent state,
*   apply one focused replacement axis,
*   keep the rest of the system stable,
*   publish as an independent generated branch for developers to inspect and run.