Veritabanı ve oturumlar

Bu sayfa Cluster ERP'nin veritabanı katmanını anlatır: core/database.py içindeki Database sınıfı, server/dependencies.py içindeki istek oturumu bağımlılığı, core/request_context.py içindeki istek bağlamı ve EventBus işleyicileri için core/handler_session.py içindeki oturum yardımcısı. Bir isteğin işleminin (transaction) ne zaman onaylandığını da anlatır. Kiracı yönlendirmesi mekanizma düzeyinde çok kiracılılık sayfasında belgelenir.

Kısaca¶

• Database, asyncpg üzerinde bir async SQLAlchemy motorunu ve expire_on_commit=False ile bir oturum fabrikasını sarar (src/cluster_erp/core/database.py:53-93).
• get_db_session her isteğe bir AsyncSession verir, onu bağlam değişkenlerinde yayınlar ve hata olursa geri alır (src/cluster_erp/server/dependencies.py:160-200).
• Onay, yanıtın ilk baytı gönderilmeden önce bir yanıt öncesi kanca ile çalışır (src/cluster_erp/server/dependencies.py:163-190, src/cluster_erp/server/middleware.py:25-57).
• İşlemi yapan kullanıcı, ilişki kimliği (correlation id) ve kullanımdan kaldırma nedeni işlev argümanlarıyla değil, bağlam değişkenleriyle taşınır (src/cluster_erp/core/request_context.py:16-61).
• Bir EventBus işleyicisi varsa isteğin oturumuna katılır, yoksa kendi oturumunu açar (src/cluster_erp/core/handler_session.py:25-37).

Nasıl çalışır¶

Database sınıfı¶

Database(settings, *, database_url=None, pool_size=None, max_overflow=None) motoru şu seçeneklerle oluşturur (src/cluster_erp/core/database.py:69-80):

Kiracılık katmanı her kiracı veritabanı için daha küçük havuzlu bir Database kurar (src/cluster_erp/core/database.py:62-68). Database.session(), başarıda onaylayan ve hatada geri alan bir async üreteçtir; açılış geçişleri onu kullanır (src/cluster_erp/core/database.py:95-102).

İstek oturumu¶

get_db_session, veriye dokunan her rotanın FastAPI bağımlılığıdır. Şunları yapar:

1. İsteğin Database nesnesini çözer: tek kiracılı kipte sürecin varsayılanı, çok kiracılı kipte kiracının veritabanı (src/cluster_erp/server/dependencies.py:104-157).
2. Bir oturum açar; oturumu, görevini ve veritabanını üç bağlam değişkeninde yayınlar (src/cluster_erp/server/dependencies.py:182-184, src/cluster_erp/core/database.py:21-37).
3. Bağlantıyı açar ve denetim bağlamını ekler (src/cluster_erp/server/dependencies.py:186-187). Bu, tek ifadede işleme yerel beş PostgreSQL ayarı kurar (app.actor_id, app.ip, app.user_agent, app.session_id, app.correlation_id) ve istek bağlam değişkenlerini ayarlar (src/cluster_erp/server/dependencies.py:34-72).
4. Ara katman kanca listesini oluşturmuşsa _commit_once işlevini yanıt öncesi kanca olarak kaydeder (src/cluster_erp/server/dependencies.py:188-190).
5. Oturumu rotaya verir, ardından ara katmanın olmadığı bağlamlar için yedek olarak _commit_once çağırır (src/cluster_erp/server/dependencies.py:191-192).
6. Herhangi bir istisnada kancayı tamamlandı olarak işaretler ve geri alır (src/cluster_erp/server/dependencies.py:193-196).
7. Bağlam değişkenlerini sıfırlar (src/cluster_erp/server/dependencies.py:197-200).

_commit_once onaylar, ardından onay sonrası için kuyruğa alınmış olayları yayınlar (src/cluster_erp/server/dependencies.py:171-176, src/cluster_erp/server/dependencies.py:203-222).

Onay zamanlaması¶

Sıra şeması onayın ne zaman gerçekleştiğini gösterir.

sequenceDiagram
 participant C as İstemci
 participant M as CommitBeforeResponseMiddleware
 participant R as Rota
 participant S as get_db_session
 participant DB as PostgreSQL
 C->>M: HTTP isteği
 M->>M: state.pre_response_hooks = []
 M->>R: uygulamayı çağır
 R->>S: Depends(get_db_session)
 S->>S: _commit_once kaydet
 S-->>R: oturum
 R->>DB: INSERT veya UPDATE (flush)
 R-->>M: http.response.start
 M->>S: _commit_once kancasını çalıştır
 S->>DB: COMMIT
 M-->>C: yanıt

Düz metinle: ara katman istek durumunda boş bir kanca listesi oluşturur. Oturum bağımlılığı listeye _commit_once ekler. Rotanın yanıtı başladığında ara katman ilk mesajı göndermeden önce kancaları çalıştırır (src/cluster_erp/server/middleware.py:41-57). Böylece istemci durum kodunu almadan önce onay tamamlanmış olur. Onay hatası bir hata yanıtına dönüşür.

İstek bağlam değişkenleri¶

EventBus işleyicilerinde oturumlar¶

handler_session(database_for), current_request_session ayarlıysa istek oturumunu verir, onu flush eder ve onaylamaz, çünkü onayı istek yapar. İstek dışında database_for() üzerinde bir oturum açar ve blok istisnasız bittiğinde onaylar (src/cluster_erp/core/handler_session.py:25-37). core/database.py içindeki bir yorum, bir oturumun tek bir göreve ait olduğunu belirtir; başka bir görevdeki kod kendi oturumunu açmalıdır (src/cluster_erp/core/database.py:34-36).

Bir isteğin başlattığı arka plan işi¶

get_session_factory, bir isteğin arka planda başlattığı iş için isteğin kiracı veritabanının, yoksa varsayılanın oturum fabrikasını döndürür (src/cluster_erp/server/dependencies.py:233-244).

Neden böyle kurulmuştur¶

• CommitBeforeResponseMiddleware belge dizgisi onay zamanlamasının nedenini belirtir: FastAPI yield bağımlılıklarını yanıt gönderildikten sonra sonlandırır; bu yüzden istemci, eklemesi onaylanmadan bir kaydı okuyabiliyordu (src/cluster_erp/server/middleware.py:26-36).
• request_context belge dizgisi işlemi yapanın neden bağlam değişkenlerinde taşındığını belirtir: flush olayları kullanıcının erişilemediği derin yazma yolunda çalışır ve bağlam modüller arası çağrıdan kaçınır (src/cluster_erp/core/request_context.py:1-9).
• Bir yorum plan_cache_mode ayarının neden zorlandığını belirtir: genel planlar bazı bağlantılarda trigram aramalarını sıralı taramaya çeviriyordu (src/cluster_erp/core/database.py:40-49).

Kurallar ve sınırlar¶

• Rotalar oturumlarını doğrudan Database.session_factory'den değil, get_db_session'dan alır. Her rotanın buna uyup uymadığı koddan belirlenemedi; bu sayfa için denetlenmedi.
• Başarısız bir istek kancadan asla onaylamaz: istisna yolu geri almadan önce done = True ayarlar (src/cluster_erp/server/dependencies.py:193-196).
• Projenin yazılı mühendislik kuralları asyncpg ile PostgreSQL ve Alembic göçlerini adlandırır. Motor URL'si postgresql+asyncpg kullanır (src/cluster_erp/config/settings.py:838-843).

Diğer parçalarla etkileşim¶

• Değişiklik geçmişi, flush anında işlemi yapanı ve kullanımdan kaldırma bağlamını okur.
• İstek hattı ve ara katmanlar, CommitBeforeResponseMiddleware ara katmanını yığına yerleştirir.
• Olay veri yolu işleyicileri handler_session ve request_database kullanır.
• Göçler veritabanı göçleri sayfasında belgelenir.

Sınırlar ve açık noktalar¶

• get_language, Accept-Language başlığının yalnızca ilk iki harfini okur ve varsayılan olarak en kullanır (src/cluster_erp/server/dependencies.py:247-249). Hangi rotaların onu kullandığı bu sayfa için listelenmedi.

Tanıtılan terimler¶

İlgili sayfalar¶

• Platform çekirdeği
• Değişiklik geçmişi
• İstek hattı ve ara katmanlar
• Çok kiracılılık
• Ayarlar başvurusu

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.