Veritabanı modülü

Kurulum ve yapılandırma

Herhangi bir adımdan önce, Başlamadan önce ve Terminal temelleri bölümlerini okuyun. Bu talimatlar, supastack monorepo'nun tamamını VS Kodunda açtığınızı varsayar; kök package.json dosyası depo kökünü işaretler. pnpm komutlarında çalışma alanı paketi bir uygulama veya paylaşılan kod klasörüdür; Üründe çalışma alanı, ekibin veri taşıyıcısı ve güvenlik sınırıdır. corepack pnpm --filter ... komutlar kökünden çalıştırılırken monorepodan bir paket seçer. Yalnızca senkronize edilmiş bir mobil veya masaüstü klasörü açtıysanız, Web arka ucunu, Docker kurulumunu veya kök komut dosyalarını içermez: arka ucu bu monorepodan veya erişilebilir bir barındırılan sunucudan çalıştırın ve platform klasörünün kendi komut dosyalarını kullanın. Ortam değişkeni, yerel bir .env dosyasında veya barındırma kontrol panelinizde depolanan adlandırılmış bir ayardır; İlgili uygulamayı değiştirdikten sonra yeniden başlatın ve sunucu sırlarını NEXT_PUBLIC_ ve EXPO_PUBLIC_ değerlerinin dışında tutun.

1. Docker Desktop'yi kurun ve başlatın.

2. Geçiş araçları için .env.example dosyasını kökteki .env dosyasına ve Next.js için apps/web/.env.local dosyasına kopyalayın (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.örnek apps/web/.env.local). DATABASE_URL'yi her iki dosyada da aynı tutun; örnek zaten yerel Docker veritabanıyla eşleşiyor.

3. Depo kök dizininden docker compose up -d postgres ve docker compose ps; komutunu çalıştırın. postgres'in sağlıklı olduğunu bildirene kadar bekleyin.

4. Kitle birlikte gönderilen geçişleri uygulamak için corepack pnpm --filter @supastack/db db:migrate kökten çalıştırın. Yalnızca packages/db/src/schema.ts'yi düzenledikten sonra db:generate komutunu çalıştırın, oluşturulan SQL dosyasını inceleyin ve ardından db:migrate komutunu çalıştırın. Beklenen: Yerel Postgres kapsayıcısının sağlıklı olması ve Web uygulamasının geçirilen veritabanını kullanması. Bu ilk çalıştırmayı asla üretime yöneltmeyin.

Sunucu ortamında amaçlanan Postgres veritabanı için DATABASE_URL yapılandırın. Entegrasyon kabulü için ayrı, tek kullanımlık bir veritabanı kullanın. Test migrasyonlarını asla üretim veritabanına yöneltmeyin.

Veritabanı çalışma alanı, şema tanımlarını ve kalıcılık yardımcılarını dışa aktarır. Tablo ya da sütun eklemeden önce packages/db/src/schema.ts ve migrasyon dizinini inceleyin.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

Kopyalanacak komutlar

Bir komutun hangi klasörde çalıştığını görmek için yorumları takip edin. İki terminal etiketlenmişse, iki terminal penceresi açın ve ikincisini kullanırken ilk komutu çalışır durumda tutun.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Uygulama iş akışı

Şemayı düzenledikten sonra bir migrasyon üretin, oluşan SQL'i inceleyin ve şema değişikliğiyle birlikte commit edin. Zorunlu sütun eklemeden önce mevcut kayıtların değerleri nasıl alacağını planlayın.

Kullanıcıya ait her kayda workspaceId dahil edin ve bu kapsamı okuma ve yazmalara taşıyın. Mevcut kullanım kayıtlarının kullandığı fiyatları yeniden yazmak yerine YZ muhasebesi için değişmez model-fiyat geçmişi kullanın.

Doğrulama ve sorun giderme

Docker motoruna bağlanamadığını söylüyorsa Docker Desktop'yi başlatın ve yüklemenin bitmesini bekleyin. Postgres sağlıklı değilse kökten docker compose logs postgres'i çalıştırın ve taşımadan önce bu hatayı düzeltin. Web DATABASE_URL'nin eksik olduğunu söylüyorsa apps/web/.env.local'yi kontrol edin; db:migrate bağlanamıyorsa kök .env dosyasını kontrol edin. Veritabanlarını değiştirirseniz her iki dosyayı da güncelleyin. Yeniden denemeden önce ilk başarısız geçiş bildirimini okuyun; asla üretime karşı tekrarlamayın.

Migrasyonları yalıtılmış bir veritabanına uygulayın ve veritabanı kapılı testleri orada çalıştırın. Eksik kimlik bilgileri, kalıcılığın geçtiği yanılgısı yerine açık atlanmış bir kapı üretmelidir. Migrasyon başarısız olursa, yeniden denemeden önce hangi ifadenin başarısız olduğunu ve mevcut şemayı inceleyin.