# ADR-004 — چرا PostgreSQL مرجع وضعیت باشد؟

Why PostgreSQL for authoritative state?

Status: proposed · Date: 2026-10-15

## مسئله / Context

run، بودجه و release به قید یکتا، تغییر شرطی و commit پایدار نیاز دارند.

Runs, budgets, and releases need unique constraints, conditional updates, and durable commits.

## گزینه‌ها / Alternatives

PostgreSQL؛ document store؛ event log به‌عنوان تنها مرجع.

PostgreSQL, document storage, or an event log as the sole authority.

## انتخاب فعلی / Choice

پیشنهاد: PostgreSQL برای metadata و state؛ artifact بزرگ بیرون DB و با pointer/hash.

Propose PostgreSQL for metadata/state; store large artifacts externally with pointers/hashes.

## چرایی و trade-off / Rationale and trade-off

transaction محلی، UNIQUE و CAS ریسکِ run تکراری و overspend را محدود می‌کنند؛ JSON همچنان برای payload مناسب است.

Local transactions, uniqueness, and CAS reduce duplicate-run/overspend risks; JSON still suits payloads.

## فرض‌ها / Assumptions

E01 پایلوت و E10 burst؛ اندازهٔ state واقعی هنوز نداریم.

Pilot E01 and burst E10; actual state sizes are not measured.

## روش آزمون / Validation

race روی idempotency/budget؛ EXPLAIN برای claim؛ crash پس از commit؛ تست restore.

Idempotency/budget races, claim query plans, post-commit crashes, and restore tests.

## بازنگری / Revisit

وقتی قفل، I/O یا حجم index در workload واقعی bottleneck شد، partition/sharding را با ADR مستقل بررسی کن.

When measured locks, I/O, or index size becomes a bottleneck, evaluate partitioning/sharding in a new ADR.

DDIA: 3, 4, 8, 10