Veritabanı göçleri

Cluster ERP'nin her iş tablosu migrations/ içindeki tek bir Alembic geçmişinden gelir. Aynı geçmiş yeni bir kiracı veritabanını kurar, var olan birini yükseltir ve sürekli tümleştirmede denetlenir. Bu sayfa onu kimin koştuğunu, paralel işçilerin nasıl ayrı tutulduğunu ve şemanın hangi parçalarının o geçmişte olmadığını açıklar. Onu çok sayıda kiracı için koşan operatör komutları kiracı yaşam döngüsü sayfasındadır.

Kısaca¶

• migrations/versions/ 218 revizyon dosyası içerir; o klasörün *.py dosyaları olarak sayıldı (ls migrations/versions/*.py).
• alembic.ini veritabanı adresi taşımaz; migrations/env.py adresi Settings üzerinden veya çağıranın verdiği bir adresten alır (migrations/env.py:42-73).
• Bütün koşular, yükseltme süresince bir PostgreSQL danışma kilidi tutan upgrade_database_to_head üzerinden geçer (src/cluster_erp/core/tenancy.py:665-720).
• Çok kiracılı bir işçi varsayılan veritabanını açılışta göç ettirir; tek kiracılı bir düğümü install.sh yeniden başlatmadan önce göç ettirir (src/cluster_erp/server/app.py:99-113, deploy/install.sh:221-226).
• Sürekli tümleştirme bütün geçmişi boş bir PostgreSQL 16 veritabanına uygular ve tam olarak bir baş ister (.github/workflows/ci.yml:110-117).

Nasıl çalışır¶

Adres nereden gelir¶

migrations/env.py hedef veritabanına şu sırayla karar verir (migrations/env.py:56-73):

1. Bir programın cfg.attributes["explicit_url"] içine koyduğu adres. upgrade_database_to_head bunu her zaman koyar; böylece kiracı hazırlama ve filo çalıştırıcısı amaçlanan veritabanına ulaşır (src/cluster_erp/core/tenancy.py:687-692).
2. Yoksa CLUSTER_ERP_DB_* değişkenlerinden kurulan Settings().database_url_sync.
3. Settings kurulamazsa koşu, bir veritabanı tahmin etmek yerine hatayla durur.

alembic.ini günlük bölümü yalnız henüz hiçbir günlük yapılandırılmamışsa uygulanır; böylece süreç içi bir koşu uygulama günlüğünü susturmaz (migrations/env.py:32-40). env.py, target_metadata değerini doldurmak için her modülün üst düzey models.py dosyasını içe aktarır (migrations/env.py:76-86).

Geçmişi kim koşar¶

Diyagram geçmişin her çağıranını gösterir.

flowchart LR
  ci["CI: alembic upgrade head"] --> alembic["Alembic command.upgrade"]
  inst["install.sh tek kiracılı"] --> alembic
  boot["işçi lifespan çok kiracılı"] --> uh["upgrade_database_to_head"]
  prov["provision_tenant"] --> uh
  upg["upgrade_tenants"] --> uh
  uh --> lock["migration_lock"]
  lock --> alembic

Düz yazıyla:

• Sürekli tümleştirme boş bir veritabanında python -m alembic upgrade head koşar (.github/workflows/ci.yml:113).
• Tek kiracılı bir düğümde install.sh yedek alır ve alembic upgrade head koşar (deploy/install.sh:221-226).
• Çok kiracılı kipte her işçi gerekirse varsayılan veritabanını oluşturur ve açılışta upgrade_database_to_head çağırır (src/cluster_erp/server/app.py:110-113).
• provision_tenant geçmişi yeni bir kiracı veritabanında yeniden oynatır (src/cluster_erp/server/provision_tenant.py:132-137).
• upgrade_tenants, revizyonu baştan farklı olan her kiracıyı yükseltir (src/cluster_erp/server/upgrade_tenants.py:83-100).

Açılış göç kilidi¶

upgrade_database_to_head, command.upgrade(cfg, "head") çağrısını migration_lock ile sarar. Kilit, hedef veritabanında alınan ve sonda bırakılan, sabit MIGRATION_LOCK_KEY anahtarlı pg_advisory_lock kilididir (src/cluster_erp/core/tenancy.py:693-720). İkinci bir işçi ilki bitene kadar bekler ve sonra başın zaten uygulanmış olduğunu görür (src/cluster_erp/core/tenancy.py:693-699). tests/test_boot_migration_lock.py testi ikinci tutucunun ilkini beklediğini denetler.

Neden böyle kurulmuştur¶

• Tek geçmiş, hazırlanan bir kiracıyı göç ettirilmiş bir dağıtımla aynı tutar (src/cluster_erp/core/tenancy.py:666-672).
• Veritabanı adresi alembic.ini içinde saklanmaz, çünkü "a tracked credential is a liability" (migrations/env.py:60-63).
• Kilit, iki işçinin bir kez aynı anda yeni bir revizyonu oynatması ve birinin açılamaması üzerine vardır (src/cluster_erp/core/tenancy.py:693-698).
• Projenin yazılı mühendislik kuralları bir modülün create_all çağırmadığını, şemanın Alembic göçleriyle geldiğini söyler.

Kurallar ve sınırlar¶

• Yayımlanmış göçler donmuştur: pyproject.toml onlara "frozen historical records (never edited after they ship)" der ve onları yalnız satır uzunluğu kuralından muaf tutar (pyproject.toml:134-136). tests/ içinde migrations/versions aranarak bu kuralı uygulayan bir test bulunmadı.
• alembic check henüz bir kapı değildir. İş akışı açıklaması, env.py yalnız üst düzey model dosyalarını içe aktardığı için karşılaştırmanın yanlış farklar bildirdiğini söyler (.github/workflows/ci.yml:118-123).
• Bir göç revizyonu yalnız hedef baştan gerideyse uygulanır; upgrade_tenants --dry-run her veritabanının güncel ve baş revizyonunu değişiklik yapmadan listeler (src/cluster_erp/server/upgrade_tenants.py:84-97).

Diğer parçalarla etkileşim¶

• Kontrol düzlemi veritabanının Alembic geçmişi yoktur. TenantRegistry.ensure_schema tablolarını create_all ile oluşturur ve sonradan gelen sütunları eş güçlü ALTER TABLE ... IF NOT EXISTS ifadeleriyle ekler (src/cluster_erp/core/tenancy.py:387-410).
• Her açılışta bir tarama, deleted_at sütunu olup deactivation_reason ve deactivation_note sütunları olmayan her tabloya bu sütunları kendi işlem danışma kilidi altında ekler (src/cluster_erp/server/app.py:1111-1166). Bkz. yumuşak silme ve devre dışı bırakma.
• Bir sürüm şema adımından sonra tohumları da yeniler; bkz. kiracı yaşam döngüsü.

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

• Bir sürümün geri alınması: Koddan belirlenemedi. src, deploy ve scripts içinde arandı; command.downgrade çağrısı bulunmadı.
• install.sh göçten önce tek kiracılı ve çok kiracılı kipte yedek alır (deploy/install.sh:214-226). Bkz. yedekler ve geri yükleme.

Tanıtılan terimler¶

İlgili sayfalar¶

• İşletim
• Servis ve süreç yöneticisi
• Kiracı yaşam döngüsü
• Lint ve tür denetimi

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