Add Turkish (tr) docs and update README (#744)

* Add Turkish (tr) docs and update README Add a full set of Turkish documentation under docs/tr (agents, changelog, CLAUDE guide, contributing, code of conduct, and many agents/commands/skills/rules files). Update README to include a link to the Turkish docs and increment the supported language count from 5 to 6. This commit adds localized guidance and references to help Turkish-speaking contributors and users. * Update docs/tr/TROUBLESHOOTING.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update docs/tr/README.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * docs(tr): fix license link and update readmes Update Turkish docs: change license badge link to point to repository root (../../LICENSE), increment displayed language count from 5 to 6, and remove two outdated related links from docs/tr/examples/README.md to keep references accurate. * Update docs/tr/commands/instinct-import.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update docs/tr/commands/checkpoint.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> --------- Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
2026-04-10 03:13:29 +08:00 · 2026-03-23 01:37:04 +03:00
parent bb1efad7c7
commit fd2a8edb53
139 changed files with 26670 additions and 2 deletions
--- a/docs/tr/skills/database-migrations/SKILL.md
+++ b/docs/tr/skills/database-migrations/SKILL.md
@@ -0,0 +1,319 @@
+---
+name: database-migrations
+description: Şema değişiklikleri, veri migration'ları, rollback'ler ve PostgreSQL, MySQL ve yaygın ORM'ler (Prisma, Drizzle, Django, TypeORM, golang-migrate) arasında sıfır kesinti deployment'ları için veritabanı migration en iyi uygulamaları.
+origin: ECC
+---
+
+# Veritabanı Migration Kalıpları
+
+Üretim sistemleri için güvenli, geri alınabilir veritabanı şema değişiklikleri.
+
+## Ne Zaman Aktifleştirmeli
+
+- Veritabanı tabloları oluştururken veya değiştirirken
+- Sütun veya indeks eklerken/kaldırırken
+- Veri migration'ları çalıştırırken (backfill, dönüştürme)
+- Sıfır kesinti şema değişiklikleri planlarken
+- Yeni bir proje için migration araçları kurarken
+
+## Temel İlkeler
+
+1. **Her değişiklik bir migration'dır** — üretim veritabanlarını asla manuel olarak değiştirmeyin
+2. **Migration'lar üretimde sadece ileri** — rollback'ler yeni forward migration'lar kullanır
+3. **Şema ve veri migration'ları ayrıdır** — tek migration'da DDL ve DML'yi asla karıştırmayın
+4. **Migration'ları üretim boyutundaki veriye karşı test edin** — 100 satırda çalışan migration 10M'de kilitlenebilir
+5. **Migration'lar üretimde çalıştıktan sonra değişmezdir** — üretimde çalışan migration'ı asla düzenlemeyin
+
+## Migration Güvenlik Kontrol Listesi
+
+Herhangi bir migration uygulamadan önce:
+
+- [ ] Migration UP ve DOWN'a sahip (veya açıkça geri alınamaz olarak işaretlenmiş)
+- [ ] Büyük tablolarda tam tablo kilitleri yok (concurrent operasyonlar kullan)
+- [ ] Yeni sütunlar varsayılanlara sahip veya nullable (varsayılan olmadan NOT NULL asla ekleme)
+- [ ] İndeksler concurrent oluşturuluyor (mevcut tablolar için CREATE TABLE ile inline değil)
+- [ ] Veri backfill şema değişikliğinden ayrı bir migration
+- [ ] Üretim verisinin kopyasına karşı test edilmiş
+- [ ] Rollback planı dokümante edilmiş
+
+## PostgreSQL Kalıpları
+
+### Güvenli Sütun Ekleme
+
+```sql
+-- İYİ: Nullable sütun, kilit yok
+ALTER TABLE users ADD COLUMN avatar_url TEXT;
+
+-- İYİ: Varsayılanlı sütun (Postgres 11+ anlık, yeniden yazma yok)
+ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;
+
+-- KÖTÜ: Mevcut tabloda varsayılansız NOT NULL (tam yeniden yazma gerektirir)
+ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
+-- Bu tabloyu kilitler ve her satırı yeniden yazar
+```
+
+### Kesinti Olmadan İndeks Ekleme
+
+```sql
+-- KÖTÜ: Büyük tablolarda yazmaları engeller
+CREATE INDEX idx_users_email ON users (email);
+
+-- İYİ: Engellemez, concurrent yazmalara izin verir
+CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
+
+-- Not: CONCURRENTLY transaction bloğu içinde çalıştırılamaz
+-- Çoğu migration aracı bunun için özel işleme ihtiyaç duyar
+```
+
+### Sütun Yeniden Adlandırma (Sıfır Kesinti)
+
+Üretimde asla doğrudan yeniden adlandırmayın. Expand-contract kalıbını kullanın:
+
+```sql
+-- Adım 1: Yeni sütun ekle (migration 001)
+ALTER TABLE users ADD COLUMN display_name TEXT;
+
+-- Adım 2: Veriyi backfill et (migration 002, veri migration'ı)
+UPDATE users SET display_name = username WHERE display_name IS NULL;
+
+-- Adım 3: Uygulama kodunu her iki sütunu okuma/yazma için güncelle
+-- Uygulama değişikliklerini deploy et
+
+-- Adım 4: Eski sütuna yazmayı durdur, kaldır (migration 003)
+ALTER TABLE users DROP COLUMN username;
+```
+
+### Güvenli Sütun Kaldırma
+
+```sql
+-- Adım 1: Sütuna tüm uygulama referanslarını kaldır
+-- Adım 2: Sütun referansı olmadan uygulamayı deploy et
+-- Adım 3: Sonraki migration'da sütunu kaldır
+ALTER TABLE orders DROP COLUMN legacy_status;
+
+-- Django için: SeparateDatabaseAndState kullanarak modelden kaldır
+-- DROP COLUMN oluşturmadan (sonra sonraki migration'da kaldır)
+```
+
+### Büyük Veri Migration'ları
+
+```sql
+-- KÖTÜ: Tüm satırları tek transaction'da günceller (tabloyu kilitler)
+UPDATE users SET normalized_email = LOWER(email);
+
+-- İYİ: İlerleme ile batch güncelleme
+DO $$
+DECLARE
+  batch_size INT := 10000;
+  rows_updated INT;
+BEGIN
+  LOOP
+    UPDATE users
+    SET normalized_email = LOWER(email)
+    WHERE id IN (
+      SELECT id FROM users
+      WHERE normalized_email IS NULL
+      LIMIT batch_size
+      FOR UPDATE SKIP LOCKED
+    );
+    GET DIAGNOSTICS rows_updated = ROW_COUNT;
+    RAISE NOTICE 'Updated % rows', rows_updated;
+    EXIT WHEN rows_updated = 0;
+    COMMIT;
+  END LOOP;
+END $$;
+```
+
+## Prisma (TypeScript/Node.js)
+
+### İş Akışı
+
+```bash
+# Şema değişikliklerinden migration oluştur
+npx prisma migrate dev --name add_user_avatar
+
+# Üretimde bekleyen migration'ları uygula
+npx prisma migrate deploy
+
+# Veritabanını sıfırla (sadece dev)
+npx prisma migrate reset
+
+# Şema değişikliklerinden sonra client oluştur
+npx prisma generate
+```
+
+### Şema Örneği
+
+```prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  avatarUrl String?  @map("avatar_url")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+  orders    Order[]
+
+  @@map("users")
+  @@index([email])
+}
+```
+
+### Özel SQL Migration
+
+Prisma'nın ifade edemediği operasyonlar için (concurrent indeksler, veri backfill'leri):
+
+```bash
+# Boş migration oluştur, sonra SQL'i manuel düzenle
+npx prisma migrate dev --create-only --name add_email_index
+```
+
+```sql
+-- migrations/20240115_add_email_index/migration.sql
+-- Prisma CONCURRENTLY oluşturamaz, bu yüzden manuel yazıyoruz
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);
+```
+
+## Drizzle (TypeScript/Node.js)
+
+### İş Akışı
+
+```bash
+# Şema değişikliklerinden migration oluştur
+npx drizzle-kit generate
+
+# Migration'ları uygula
+npx drizzle-kit migrate
+
+# Şemayı doğrudan push et (sadece dev, migration dosyası yok)
+npx drizzle-kit push
+```
+
+### Şema Örneği
+
+```typescript
+import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";
+
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  email: text("email").notNull().unique(),
+  name: text("name"),
+  isActive: boolean("is_active").notNull().default(true),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+```
+
+## Django (Python)
+
+### İş Akışı
+
+```bash
+# Model değişikliklerinden migration oluştur
+python manage.py makemigrations
+
+# Migration'ları uygula
+python manage.py migrate
+
+# Migration durumunu göster
+python manage.py showmigrations
+
+# Özel SQL için boş migration oluştur
+python manage.py makemigrations --empty app_name -n description
+```
+
+### Veri Migration
+
+```python
+from django.db import migrations
+
+def backfill_display_names(apps, schema_editor):
+    User = apps.get_model("accounts", "User")
+    batch_size = 5000
+    users = User.objects.filter(display_name="")
+    while users.exists():
+        batch = list(users[:batch_size])
+        for user in batch:
+            user.display_name = user.username
+        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)
+
+def reverse_backfill(apps, schema_editor):
+    pass  # Veri migration'ı, geri alma gerekmez
+
+class Migration(migrations.Migration):
+    dependencies = [("accounts", "0015_add_display_name")]
+
+    operations = [
+        migrations.RunPython(backfill_display_names, reverse_backfill),
+    ]
+```
+
+## golang-migrate (Go)
+
+### İş Akışı
+
+```bash
+# Migration çifti oluştur
+migrate create -ext sql -dir migrations -seq add_user_avatar
+
+# Tüm bekleyen migration'ları uygula
+migrate -path migrations -database "$DATABASE_URL" up
+
+# Son migration'ı rollback et
+migrate -path migrations -database "$DATABASE_URL" down 1
+
+# Versiyonu zorla (dirty durumu düzelt)
+migrate -path migrations -database "$DATABASE_URL" force VERSION
+```
+
+### Migration Dosyaları
+
+```sql
+-- migrations/000003_add_user_avatar.up.sql
+ALTER TABLE users ADD COLUMN avatar_url TEXT;
+CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;
+
+-- migrations/000003_add_user_avatar.down.sql
+DROP INDEX IF EXISTS idx_users_avatar;
+ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;
+```
+
+## Sıfır Kesinti Migration Stratejisi
+
+Kritik üretim değişiklikleri için expand-contract kalıbını takip edin:
+
+```
+Faz 1: EXPAND
+  - Yeni sütun/tablo ekle (nullable veya varsayılanlı)
+  - Deploy: uygulama hem ESKİ hem YENİ'ye yazar
+  - Mevcut veriyi backfill et
+
+Faz 2: MIGRATE
+  - Deploy: uygulama YENİ'den okur, her İKİSİNE yazar
+  - Veri tutarlılığını doğrula
+
+Faz 3: CONTRACT
+  - Deploy: uygulama sadece YENİ'yi kullanır
+  - Eski sütun/tabloyu ayrı migration'da kaldır
+```
+
+### Zaman Çizelgesi Örneği
+
+```
+Gün 1: Migration new_status sütunu ekler (nullable)
+Gün 1: App v2 deploy et — hem status hem new_status'a yaz
+Gün 2: Mevcut satırlar için backfill migration'ı çalıştır
+Gün 3: App v3 deploy et — sadece new_status'tan okur
+Gün 7: Migration eski status sütununu kaldırır
+```
+
+## Anti-Kalıplar
+
+| Anti-Kalıp | Neden Başarısız Olur | Daha İyi Yaklaşım |
+|-------------|-------------|-----------------|
+| Üretimde manuel SQL | Denetim izi yok, tekrarlanamaz | Her zaman migration dosyaları kullan |
+| Deploy edilmiş migration'ları düzenleme | Ortamlar arası sapma yaratır | Bunun yerine yeni migration oluştur |
+| Varsayılansız NOT NULL | Tabloyu kilitler, tüm satırları yeniden yazar | Nullable ekle, backfill et, sonra kısıt ekle |
+| Büyük tabloda inline indeks | Build sırasında yazmaları engeller | CREATE INDEX CONCURRENTLY |
+| Tek migration'da şema + veri | Rollback zor, uzun transaction'lar | Ayrı migration'lar |
+| Kodu kaldırmadan önce sütun kaldırma | Eksik sütunda uygulama hataları | Önce kodu kaldır, sonra sütunu sonraki deploy'da kaldır |