Veritabanı Veri Modeli

Index Adı	Tablo	Tip	Kolon(lar)	Amacı
idx_stories_user_cursor	stories	B-Tree Composite	user_id, created_at DESC, id DESC	Cursor-based pagination (OFFSET yerine)
idx_story_chunks_ordering	story_chunks	UNIQUE B-Tree	story_id, chunk_index	Kronolojik sıralama + uniqueness garantisi
idx_story_chunks_embedding	story_chunks	HNSW Conditional	embedding (WHERE IS NOT NULL)	RAG semantic search — ~12ms @ 1M satır
idx_story_decisions_story	story_decisions	B-Tree Composite	story_id, created_at	Hikayeye ait kararları kronolojik çek
idx_story_decisions_embedding	story_decisions	HNSW Conditional	embedding (WHERE IS NOT NULL)	RAG related_decisions semantic search
idx_stories_cache_dirty	stories	Partial B-Tree	cache_dirty WHERE true	Sadece dirty story'leri tara (Q16 — sessions'tan taşındı)
idx_outbox_pending	outbox	Partial B-Tree	status, created_at WHERE pending	Worker polling — bekleyen event'leri çek
idx_outbox_story_pending	outbox	Partial B-Tree	story_id, created_at WHERE pending	Per-story outbox kontrolü (Phase 1)
idx_outbox_cleanup	outbox	Partial B-Tree	status, sent_at WHERE sent	Cleanup cron — eski sent kayıtları sil
idx_outbox_dead_letter	outbox	Partial B-Tree	status, created_at WHERE dead_letter	Monitoring — müdahale gerektiren event'ler

HNSW Nedir?

Hierarchical Navigable Small World — pgvector'ın approximate nearest neighbor index'i. Exact search yerine ~%99 doğrulukla 70x hızlı arama. m=16 her node 16 komşuya bağlı, ef_construction=64 build kalitesi.

Partial Index Nedir?

Sadece belirli koşulu sağlayan satırlar index'lenir. WHERE status = 'pending' → 1M outbox kaydından sadece ~100 pending olan index'te. Küçük, hızlı, az disk.

Implicit Index'ler

PRIMARY KEY ve UNIQUE constraint'ler otomatik index oluşturur. users.email, users.username, outbox.idempotency_key için ayrı index yazmadık — PG kendisi yapıyor.

CASCADE Silme Zinciri

Kullanıcıyı sil → tüm verisi otomatik temizlenir. Orphan kayıt riski yok.

👤

users

Kullanıcı kaydı siliniyor...

📖

stories

user_id FK CASCADE → tüm hikayeler siliniyor...

📝

story_chunks

story_id FK CASCADE → tüm chunk'lar siliniyor...

🎯

story_decisions

chunk_id FK CASCADE + story_id FK CASCADE → tüm kararlar siliniyor...

📤

outbox

story_id FK CASCADE → event'ler siliniyor...

⚠️ DBA Uyarısı: Büyük veri setlerinde CASCADE silme tablo kilitlemeye neden olabilir. Üretimde soft-delete (status='deleted') tercih edilebilir.

Code-First — Drizzle ORM Tanımları

SQL yazmak yerine TypeScript ile tanımlıyoruz. Drizzle Kit otomatik migration SQL'i üretir.

schema.ts

Trigger — updated_at Otomatik Güncelleme

1 tabloda (stories) UPDATE yapıldığında updated_at otomatik NOW() olur.

trigger.sql

-- Fonksiyon: updated_at kolonunu NOW() ile günceller
CREATE OR REPLACE FUNCTION set_updated_at()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- stories tablosuna bağla (BEFORE UPDATE)
CREATE TRIGGER trg_stories_updated_at
    BEFORE UPDATE ON stories
    FOR EACH ROW EXECUTE FUNCTION set_updated_at();

-- ❌ users'ta YOK → updated_at kolonu kaldırıldı (Q16)
-- ❌ sessions tablosu kaldırıldı (Q16)
-- ❌ story_chunks ve story_decisions'ta YOK
--    → Bu tablolar immutable (yazıldıktan sonra değişmez)
-- ❌ outbox'ta YOK
--    → status değişiyor ama "ne zaman güncellendi" önemli değil, sent_at var
            

Neden BEFORE UPDATE? AFTER UPDATE'ten farklı olarak, BEFORE trigger satır yazılmadan önce değişiklik yapabilir. Performans farkı yok ama mantıksal olarak daha doğru — updated_at değerini "yazılacak verinin" parçası yapıyoruz.