Veritabani ve Migrasyon

SQL veritabanları ve şema yaşam döngüsü

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Forge SQLAlchemy'nin asenkron engine katmanını kullanır. Veritabanı alias'ı fiziksel bağlantıyı, resource tablosu HTTP sözleşmesini belirler. Bir projede birden fazla alias olabilir; alias isimlerinin başka projelerde aynı olması aynı bağlantı anlamına gelmez.

Sistem	URL sürücüsü	Kullanım
SQLite	sqlite+aiosqlite:///./data/app.db	Yerel geliştirme ve uygun küçük kurulumlar
PostgreSQL	postgresql+asyncpg://…	Ana canlı entegrasyon hedefi
MySQL/MariaDB	mysql+asyncmy://…	Asyncmy bağlantısı
MongoDB	mongo_databases altında URI	Ayrı belge kaynağı modeli

Şifre ve kullanıcıyı belgede sabitlemek yerine tam URL'yi env değişkeninden alın:

{
  "databases": {
    "primary": {
      "url": "$env:APP_DATABASE_URL",
      "support_schema_mode": "validate",
      "pool_pre_ping": true,
      "pool_size": 10,
      "max_overflow": 20,
      "pool_timeout": 30,
      "pool_recycle": 1800
    }
  }
}

Bu örnek veritabanının önceden hazırlanmış olduğunu varsayar. URL içindeki özel karakterlerin ilgili sürücünün URL kurallarına uygun kodlanması gerekir. TLS ayarları, sağlayıcının bağlantı/pool sözleşmesine göre doğrulanmalıdır.

Üç ayrı şema sorumluluğu

Alan	İçerik	İşletme kuralı
İç metadata DB	API anahtarları, yönetim hesapları, ekip ve audit/medya metadata	INTERNAL_DATABASE_URL, INTERNAL_SCHEMA_MODE
Proje iş DB'si	Uygulama tabloları ve işlem destek yapıları	databases.<alias>
Üretim migration'ları	Yeni kolon/index, veri dönüşümü, geriye uyumluluk	Uygulamaya ait kontrollü migration süreci

SQL operation idempotency kaydı iş veritabanındadır; korunan yan etkiyle aynı transaction'a girer. Bunu ayrı metadata DB'ye taşıyıp aynı atomikliği beklemeyin.

Geliştirmeden üretime

1. Geliştirmede açık sütun tanımları ve auto_create: true ile başlayabilirsiniz.
2. Gerçek şemayı ve verileri yedekleyin; yedeğin geri yüklenmesini deneyin.
3. Değişiklikleri ayrı staging veritabanında uygulayın.
4. forge migrate ile Forge destek nesnelerini ve tanımlı auto-create tablolarını hazırlayın.
5. INTERNAL_SCHEMA_MODE=validate ve proje support_schema_mode=validate ayarlarını kullanın.
6. Uzun ömürlü iş şeması değişikliklerini Alembic veya ayrı SQL migration akışıyla sürümleyin. Runtime rolünün DDL yetkisini buna göre daraltın.

auto_create, mevcut tabloyu istediğiniz yeni sütun yapısına dönüştürmez. forge migrate de geçmiş migration'ları takip eden tam bir schema versioning sistemi değildir. Bir kod rollback'i değişen veriyi otomatik geri almaz.

Havuz ve kapasite

Worker sayısı ile her proje/alias havuzunun toplam bağlantı bütçesini birlikte hesaplayın. Birden fazla worker, her biri pool_size + max_overflow bağlantıya çıkabilen birden fazla engine yaratabilir. İç DB havuzu da ayrı bütçe kullanır. Bu değerler SQLite'a birebir taşınmaz. Yavaş sorguyu yalnız havuz büyüterek çözmeyin; query planı, index ve lock beklemelerini inceleyin.

Tüm alanlar: SQL ve Mongo modelleri.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/db.py
• main/framework/config.py
• main/framework/cli.py
• main/docs/30-Database-Schema-Lifecycle-and-Migrations.md

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım