Drizzle Kit ile SQL-First Migration: TypeScript ORM Pratik 2026

Drizzle migration akışı, klasik ORM araçlarının “magic” davranışını terk edip SQL şemasını birinci sınıf tutan bir yaklaşım sunar. Drizzle Kit; TypeScript şemasından deterministik SQL üretir, diff’i geliştiriciye gösterir ve sürüm kontrolünü Prisma veya TypeORM’a göre çok daha şeffaf yapar. 2026 itibarıyla Drizzle ORM, GitHub’da yaklaşık 23.000 yıldıza ulaşmış ve haftalık ortalama 950.000 npm indirme bandında stabilize olmuştur; bu da SQL-first paradigmaya geçişin niş olmaktan çıktığını gösteriyor.

Bu yazı, Drizzle Kit’in generate, push, migrate ve studio komutlarını üretim senaryolarında nasıl konumlandıracağınızı, Postgres-MySQL-SQLite arasındaki dialect farklarını, CI/CD entegrasyonunu, schema drift problemini ve büyük tablolarda zero-downtime migration desenlerini ele alır. Hedef: takımının ORM seçimine bilinçli karar verebilmesi, ekibinin migration dosyalarını korkmadan merge edebilmesi.

Drizzle Kit Nedir, Neden SQL-First Önemli

Drizzle ORM, Hono ve Drizzle Team ekibinin 2022 sonunda yayınladığı, sıfır runtime bağımlılığa sahip bir TypeScript ORM’dir. Drizzle Kit ise şema-to-SQL üretimi, migration yönetimi ve introspection için ayrı bir CLI paketidir (drizzle-kit). 0.30+ sürümleriyle birlikte komut yüzeyi sadeleşmiş, drizzle-kit generate tek komutla dialect’i otomatik algılar hale gelmiştir.

SQL-first yaklaşımının pratik anlamı şudur: schema.ts dosyanız değişti diyelim. Drizzle Kit, mevcut snapshot ile yeni şemayı karşılaştırır, diff’i hesaplar ve sonucunu bir .sql dosyası olarak diske yazar. Bu dosya artık sizin için açık — gözden geçirip, gerekirse elle düzenleyip git’e commit edebilirsiniz. Prisma’da migration SQL’i genellikle “shadow database” üzerinden üretilir ve düzenleme deneyimi pek davet edici değildir; Drizzle’da SQL ilk sınıf vatandaştır.

Özellik	Drizzle Kit (0.31+)	Prisma Migrate (5.x)	TypeORM (0.3+)	Knex (3.x)
SQL görünürlüğü	Tam — dosya elle düzenlenebilir	Kısmi — shadow DB ile üretilir	Decorator’dan üretilir, opak	Tam — el yazımı
Type-safety	Schema → tip otomatik	generate sonrası tip üretilir	Decorator-tabanlı, runtime cost	Yok (es-Knex benzeri ekler)
Bundle size (zero-dep)	~7 KB gzip runtime	~2 MB + query engine binary	~1.4 MB	~600 KB
Cold start (serverless)	40-80 ms tipik	250-600 ms (engine init)	180-300 ms	90-150 ms
Edge runtime (Cloudflare Workers, Vercel Edge)	Native destek	Driver adapters ile sınırlı	Desteklenmez	Kısmi
Migration rollback	Manuel SQL (down dosyası yazılır)	Otomatik değil — reset/rebase	Down method’u zorunlu	down() fonksiyonu

Stack Overflow Developer Survey 2024 verilerine göre TypeScript geliştiricilerin yaklaşık %72’si bir ORM kullanıyor; bu kitle içinde Drizzle’ın “most admired” oranı 2023’teki %4 seviyesinden 2024’te %19’a sıçradı. Performans, bundle boyutu ve serverless cold-start metrikleri bu artışı tetikleyen başlıca faktörler.

Ne zaman SQL-first seç:

• Avantaj: Migration dosyalarını PR review sürecinde inceleyebilen ekipler; veritabanı yöneticisi (DBA) ile çalışan kurumsal ortamlar.
• Avantaj: Cloudflare Workers, Vercel Edge, Deno Deploy gibi V8 isolate runtime’larında 50 ms altı soğuk başlatma hedefleyen takımlar.
• Dezavantaj: SQL bilgisi düşük junior’ların ağırlıkta olduğu ve ORM’in “auto-magic” üretmesini bekleyen ekipler için öğrenme eğrisi yüksektir.
• Ne zaman vazgeç: Karmaşık nested write (Prisma’nın create: { nested: { ... } } sözdizimi) ihtiyacı baskınsa Prisma daha rahat olabilir.

Şema Tanımlama: Tablolar, İlişkiler, Index Stratejisi

Drizzle şemasını TypeScript ile yazıyorsunuz ama bu, framework’ün size SQL anlamını gizlediği anlamına gelmiyor. Tam tersine, her tablo tanımı pgTable, mysqlTable ya da sqliteTable fonksiyonuyla başlar ve column tipleri (örn. varchar('email', { length: 255 })) doğrudan ilgili dialect’in SQL tipine 1-1 eşlenir. Bu sayede oluşturulan migration SQL’ini okuduğunuzda sürpriz yoktur.

import { pgTable, serial, varchar, timestamp, index, uniqueIndex } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: varchar('email', { length: 255 }).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
}, (t) => ({
  emailIdx: uniqueIndex('users_email_idx').on(t.email),
  createdIdx: index('users_created_idx').on(t.createdAt),
}));

İlişkiler iki katmanda tanımlanır: foreign key DDL’i için references() kullanılır; sorgu tarafında relations() helper’ı ile join bilgisi ORM’e bildirilir. Bu ayrım, Drizzle’ın db.query.users.findMany({ with: { posts: true } }) gibi declarative query’leri tip-güvenli üretebilmesini sağlar. Prisma’da ilişki tek noktada tanımlandığı için daha kompakt görünebilir, ancak Drizzle’ın iki katmanı, SQL JOIN’ini eylemli kontrol etmek isteyenler için netlik sunar.

Index stratejisi konusunda kritik nokta: Drizzle Kit, schema.ts içine eklediğiniz her index() ve uniqueIndex() tanımını migration SQL’ine ekler ama varsayılan olarak CONCURRENTLY kullanmaz. 5 milyon satırlık bir Postgres tablosuna online index eklemek istiyorsanız üretilen SQL’i elle CREATE INDEX CONCURRENTLY olarak güncellemeniz gerekir. Production’da bu adımı atlamak, migration’ın tabloyu birkaç dakika kilitlemesi anlamına gelir.

Dialect	Drizzle paketi	Tipik driver	Migration SQL üretimi	JSON tipi desteği
PostgreSQL 14-17	drizzle-orm/pg-core	postgres-js, node-postgres, neon-http	Tam	jsonb (native)
MySQL 8 / MariaDB 11	drizzle-orm/mysql-core	mysql2, planetscale	Tam (ALTER kısıtları var)	json (native, 8.0+)
SQLite / Turso	drizzle-orm/sqlite-core	better-sqlite3, libsql	Sınırlı (ALTER COLUMN yok, rebuild gerek)	text + JSON1 extension
Cloudflare D1	drizzle-orm/d1	D1 binding	Wrangler ile entegrasyon	text + JSON1
Bun SQLite	drizzle-orm/bun-sqlite	bun:sqlite	SQLite ile aynı kısıtlar	text + JSON1

SQLite ailesindeki temel zorluk şudur: SQLite, ALTER TABLE ile sütun tipini değiştirmeye veya NOT NULL kısıtı eklemeye izin vermez. Drizzle Kit bu durumda “tablo yeniden oluştur, veriyi kopyala, eskiyi sil, yenisini yeniden adlandır” desenini SQL olarak üretir. Bu desen güvenli ama veri büyükse maliyetlidir.

Drizzle Kit Komut Yüzeyi: generate, push, migrate

Drizzle Kit’in en sık karıştırılan yönü push ve generate + migrate ayrımıdır. İkisi aynı işi yapmaz; biri development hızı için, diğeri production güvenliği için tasarlanmıştır.

Komut	Ne yapar	Önerilen ortam	Migration dosyası üretir mi?
drizzle-kit generate	Şema diff’inden .sql migration dosyası oluşturur	Dev + CI	Evet (./drizzle/0001_xxx.sql)
drizzle-kit migrate	Üretilen migration’ları sırayla DB’ye uygular	Tüm ortamlar (production dahil)	Hayır (uygular)
drizzle-kit push	Şemayı doğrudan DB’ye uygular, dosya bırakmaz	Yalnızca local dev / prototip	Hayır
drizzle-kit pull	Mevcut DB’den şema introspect eder	Mevcut DB’ye Drizzle entegrasyonu	Hayır (schema.ts üretir)
drizzle-kit studio	Lokal browser tabanlı tablo görüntüleyici başlatır	Dev	Hayır
drizzle-kit check	Migration dosyalarının integrity’sini doğrular	CI pre-merge	Hayır

1. Dev döngüsü: Şemayı düzenle → drizzle-kit generate → üretilen .sql dosyasını oku → gerekirse manuel düzelt → drizzle-kit migrate ile local DB’ye uygula → uygulamayı test et.
2. PR aşaması: Yeni migration dosyası git’e commit edilir. Reviewer SQL’i okur. CI drizzle-kit check ile snapshot bütünlüğünü doğrular.
3. Production: Deploy adımında drizzle-kit migrate çalıştırılır. Drizzle, __drizzle_migrations tablosunda hash’leri kontrol eder; tekrar uygulanmaz.
4. Acil prototip: Şemayı bilerek geçici tutuyorsan drizzle-kit push ile dosya üretmeden DB’yi günceller. Production’da kesinlikle kullanma.

Kişisel olarak ekiplere her zaman önerdiğim akış: push’u yalnızca solo prototip evresinde kullan, ekip büyüdüğü an generate+migrate’e geç. Bu, yazılım danışmanlığı görüşmelerinde tekrarladığım nadir kesin kuraldan biri çünkü push üzerinde tutulan bir şema, drift’in tespit edilemediği bir kara kutuya dönüşür.

drizzle.config.ts ve Ortam Yönetimi

Drizzle Kit, kök dizinde drizzle.config.ts dosyası bekler. Bu dosya hem CLI komutlarının davranışını hem de hangi şema dosyasının okunacağını belirler. Kritik alanlar şunlar:

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema/*.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

strict: true ayarı, geri dönüşü olmayan değişikliklerde (sütun düşürme, tablo silme) Drizzle’ın açık onay istemesini sağlar. Production CI/CD pipeline’larında bu bayrak hayat kurtarır; veri kaybına neden olabilecek SQL’in sessizce üretilmesini engeller.

• schema: Tek dosya veya glob pattern olabilir (./src/db/schema/*.ts). Çoklu dosyalar büyük projelerde tablo bazlı dosyalama yapmanıza izin verir.
• out: Migration dosyalarının yazılacağı klasör. Genellikle ./drizzle veya ./migrations.
• dialect: postgresql | mysql | sqlite | turso | singlestore. 0.27 öncesi driver alanı kullanılıyordu; eski projelerde bu alanı güncellemek gerekir.
• migrations.prefix: Dosya adı önekini özelleştirir (örn. timestamp). Takım pratiği açısından timestamp ileride çakışmaları azaltır.
• breakpoints: Migration içinde --> statement-breakpoint yorumları üretir; bazı driver’lar tek transaction içinde DDL+DML karışımını sevmediği için bu ayrım gerekir.

Çoklu ortam yönetimi için Drizzle’ın yerleşik bir “environment” konsepti yok; pratik çözüm, ortam değişkenine göre dbCredentials.url‘ü değiştirmektir. Dev, staging, prod için ayrı .env dosyaları tutup deploy sırasında doğru DATABASE_URL enjekte edilir. Vercel, Railway, Fly.io gibi platformlarda bu pattern doğal şekilde çalışır.

Migration Üretimi ve Manuel Düzenleme

Drizzle Kit’in generate komutu çalıştığında üç dosya türü üretir: 0001_descriptive_name.sql (DDL), meta/0001_snapshot.json (snapshot) ve güncellenmiş meta/_journal.json (sıralama metadatası). Bu üç dosya birbirine bağımlıdır; birini elle silip diğerini bırakmak drizzle-kit check hatası verir.

Üretilen .sql dosyası tamamen sizindir. Tipik manuel düzenleme senaryoları:

• Online index: CREATE INDEX ... ifadesini CREATE INDEX CONCURRENTLY ... olarak değiştirip transaction wrapper’ını kaldırın (Postgres CONCURRENTLY transaction içinde çalışmaz).
• Veri taşıma (backfill): Yeni NOT NULL sütun eklerken önce nullable ekle, UPDATE ile doldur, sonra NOT NULL kısıtı ekle. Bu üç adımı genellikle Drizzle Kit otomatik üretmez; siz yazarsınız.
• Rename: Drizzle Kit, sütun rename’i otomatik algılamaz; drop + add olarak yorumlar. CLI’da prompt geldiğinde “is this rename?” seçeneğini onaylamanız gerekir. Aksi halde veri kaybı olur.
• Down migration: Drizzle çekirdeği down dosyası üretmez. Üretim ekipleri için pratik desen: her yukarı migration yanına manuel bir down.sql yazmak ve repo’da tutmak.

Senaryo	Otomatik Drizzle çıktısı	Önerilen manuel müdahale	Production etkisi
NOT NULL sütun ekle (1M+ satır)	Tek ALTER TABLE	3 aşama: nullable → backfill → NOT NULL	Tek ALTER table’ı 30-120 sn kilitleyebilir
Büyük index ekle	CREATE INDEX (blocking)	CREATE INDEX CONCURRENTLY	Blocking versiyon 10M satır için 5-15 dk kilit
Sütun adı değiştir	DROP + ADD (veri kaybı)	CLI prompt’unda rename onayla	Onaylanmazsa kalıcı veri kaybı
Sütun tipi değiştir	ALTER COLUMN TYPE	USING clause ekle, gerekirse görünmez kolon pattern	Cast başarısızsa migration durur
Tablo bölme (vertical split)	Üretmez — şema manuel	CTAS + foreign key + dual-write geçişi	Çift yazma penceresi planı gerek

Üretim ekiplerinin %40’tan fazlası “büyük tabloda alter” hatası yaşadığını raporlar (PlanetScale 2024 Schema Change Report). Bu hatadan kaçınmak için ekipler genelde “expand-contract” patern’ini benimser: önce yeni şemayı ekle (expand), uygulamayı her iki şemada da çalışır hale getir, eski şemayı kaldır (contract). Drizzle, bu pattern’i destekleyen aletler sunar ama akışı siz tasarlarsınız.

CI/CD Entegrasyonu ve Zero-Downtime Akış

Drizzle migration’larını CI/CD’ye sokmanın iki temel yolu var: build/deploy adımında drizzle-kit migrate komutunu çalıştırmak ya da uygulama bootstrap’ında programatik migrate() fonksiyonunu çağırmak. İkincisi import { migrate } from 'drizzle-orm/postgres-js/migrator' üzerinden çalışır ve özellikle Fly.io gibi region başına container deploy eden platformlarda kullanışlıdır.

1. Build aşaması: Repo clone → npm ci → drizzle-kit check (snapshot hash bütünlüğü).
2. Test aşaması: Test DB’sine drizzle-kit migrate → integration testleri.
3. Staging deploy: Staging DB’sine migrate → smoke test → 10-30 dakika bekleme penceresi.
4. Production deploy: İdeal akış: önce migrate (geriye uyumlu DDL), sonra uygulama deploy. Geriye uyumsuz DDL varsa expand-contract sırası.
5. Rollback: Drizzle otomatik rollback sunmaz. Hazırda tuttuğun down.sql‘i elle çalıştırırsın veya snapshot restore ederek geri dönersin.

GitHub Actions üzerinde tipik bir job:

- name: Apply Drizzle migrations
  run: npx drizzle-kit migrate
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

Bu yaklaşım çoğu küçük-orta proje için yeterlidir. Ancak veri tabanı boyutu 100 GB üzerine çıktığında ve migration süresi deploy timeout’una yaklaştığında, migration job’unu deploy’dan ayır. Üretim ekiplerinin önerdiği desen: migration’ı manuel tetiklenen ayrı bir GitHub Actions workflow olarak tut, uygulama deploy’unu yalnızca migration başarıyla bittikten sonra çalıştır. Bu, “deploy timeout sırasında migration yarıda kaldı” senaryosunu önler.

Stratejik karar	Küçük proje (<10 GB)	Orta (10-100 GB)	Büyük (100 GB+)
Migration runner	Deploy pipeline içinde	Deploy öncesi ayrı job	Manuel tetiklenen workflow
Expand-contract zorunlu mu?	Genelde hayır	Geriye uyumsuz değişiklikte evet	Her şemada zorunlu
Online DDL aracı	Standart ALTER	pg_repack / gh-ost benzeri	pg_repack, online schema change platform
Rollback stratejisi	down.sql yeter	down.sql + son snapshot	PITR (point-in-time recovery)
Tipik migration süresi	1-5 sn	30 sn – 5 dk	10 dk – 2 saat

Zero-downtime için kritik kural: her migration backward-compatible olacak şekilde tasarlan. Yani uygulamanın v1 sürümü, yeni şemada da çalışabilmeli; v2 sürümü, eski şemada da çalışabilmeli. Bu kural, blue-green ve canary deploy stratejilerinin doğal gereksinimidir.

Drift Tespiti ve Schema Synchronization

Schema drift, takımın migration sistemiyle yönetmediği şema değişikliklerinin DB’de oluşması durumudur. Bir DBA elle index ekler, bir geliştirici prod konsoluna girip ALTER yapar — sonuç: schema.ts ile gerçek DB arasında uyumsuzluk. Drizzle Kit, drizzle-kit pull ile mevcut DB şemasını TypeScript’e çevirir; bu çıktıyı mevcut schema.ts ile diff’leyerek drift’i tespit edebilirsiniz.

Pratik drift kontrol script’i şöyle çalışır: CI’da haftalık çalışan bir job drizzle-kit pull --out=./drift-check ile prod şemasını çeker, git diff ile mevcut schema dosyaları arasındaki farkı raporlar. Sıfır olmayan diff, ekibe Slack üzerinden alert gönderir. Bu basit pattern, 2025’te birkaç müşteri projesinde “neden bu sütun production’da var ama bizim schema.ts’de yok?” sorularını ortadan kaldırdı.

SQL-first paradigmaya geçişin, takımın test-driven development pratikleriyle de iyi örtüştüğünü gözlemledim. TDD Pratik akışında migration dosyalarını da kapsayan integration testleri (geçici DB üzerinde migrate + assertion) yazmak, schema değişikliklerini güvenli hale getirir.

Drift kaynağı	Tespit aracı	Önleme stratejisi	Tipik sıklık
DBA manuel ALTER	drizzle-kit pull + diff	Audit log + change management policy	Aylık
Hotfix sırasında prod konsol	Aynı	Read-only prod erişimi default	Quarter başına 1-2
Failed migration yarım kaldı	__drizzle_migrations tablosu	Transactional migration; PITR backup	Nadir ama yıkıcı
Üçüncü parti araç (Hasura, Supabase Studio)	drizzle-kit pull	Tek otorite kuralı: schema.ts	Sıklıkla, dikkatsiz ekipte
Replication lag farklılığı	Replica vs primary diff	Read-only replica’lara write engelle	Sürekli izleme

Geniş ölçek backend mimarisi tasarlarken Drizzle Kit’in bu drift kontrol kapasitesi, Python Backend FastAPI Django ile karşılaştırıldığında Alembic’e benzer ama daha şeffaf bir deneyim sunar. Alembic autogenerate de SQL üretir ama dialect başına farklı davranır; Drizzle Kit dialect tutarlılığını sıkı tutar.

Performans, Bundle Boyutu ve Edge Runtime

Drizzle’ın “zero-dependency runtime” iddiası gerçektir: kütüphanenin kendisi sıfır npm bağımlılığıyla gelir; sadece kullandığınız driver’ı (postgres-js, mysql2, vb.) siz eklersiniz. Bu, bundle boyutunu özellikle serverless/edge ortamlarda kayda değer şekilde azaltır.

ORM	Min bundle (gzip)	Cold start (median, AWS Lambda 1024 MB)	p99 query latency (1k row select)	Memory footprint (idle)
Drizzle + postgres-js	~85 KB	~120 ms	~6 ms	~35 MB
Prisma 5.x	~1.8 MB + engine	~480 ms	~9 ms	~110 MB
TypeORM 0.3.x	~1.4 MB	~310 ms	~8 ms	~80 MB
Knex 3.x	~620 KB	~180 ms	~7 ms	~55 MB
Sequelize 6.x	~1.1 MB	~270 ms	~9 ms	~75 MB

Yukarıdaki sayılar farklı vendor benchmark raporları ve topluluk testlerinden derlenmiş tahmini ortalamalardır; tam rakamlar driver, query karmaşıklığı ve donanıma göre farklılaşır. Yine de büyüklük sırası gerçekçidir: Drizzle, Prisma’ya göre cold start’ta yaklaşık 3-4x daha hızlıdır ve bu fark serverless ortamlarda kullanıcıya doğrudan yansır.

Cloudflare Workers, Vercel Edge ve Deno Deploy gibi V8 isolate tabanlı platformlarda Drizzle native çalışır. Prisma için @prisma/adapter-neon veya @prisma/adapter-planetscale driver adapter’ları gerekir; bu adapters 2024 sonu itibarıyla stable hale geldi ama Drizzle’a göre konfigürasyon yükü daha yüksektir.

Performans tablosu, ORM seçimi yapan ekipler için tek başına karar belirleyici değildir. Go Backend veya Java 21 Virtual Threads gibi alternatif dillerin avantaj sağladığı yüksek-yük senaryolarında Drizzle’ın TypeScript özelliği primerdir; Node.js / Bun ekosistemine bağlı kalan ekipler için ise Drizzle bugün en performant ORM seçeneklerinden biridir. Ayrıca Bun Deno Node.js 22 karşılaştırmasında görülen runtime farklılıkları, Drizzle’ın her üçünde de native desteklenmesi sayesinde sorunsuz çalışır.

SSS — Sık Sorulan Sorular

Sonuç

Drizzle Kit, TypeScript ekosisteminde SQL’i ikinci sınıf vatandaş olmaktan çıkaran ilk ORM ailesidir. generate + migrate akışı, küçük takımlardan kurumsal ortamlara kadar şeffaf bir migration kültürünü mümkün kılar; bundle boyutu ve cold-start avantajları serverless/edge stratejilerinde elle tutulur fark üretir. SQL bilen geliştiricilerden oluşan ekipler için 2026 itibarıyla Drizzle, Prisma’nın geleneksel hâkimiyetine karşı en ciddi alternatif konumunda.

Karar çerçevesi şudur: ekibinizde SQL okuma rahatlığı var ve serverless/edge runtime hedefi başlıca tercihinizse Drizzle yüksek getiri sağlar. Yoğun nested-write ihtiyacı ve düşük SQL seviyesi olan junior ağırlıklı takımlar Prisma’yı tercih etmeye devam edebilir. TypeORM gibi decorator-tabanlı çözümler ise yeni projelerde nadiren mantıklıdır; mevcut TypeORM kod tabanlarını ise risk analiziyle aşamalı migrate etmek doğru yaklaşımdır.

Drizzle’ı production’a alırken ekibinizin migration politikası ve CI/CD entegrasyonu konularında bir gözden geçirme isterseniz iletişim sayfasından ulaşabilirsiniz. SQL-first paradigmaya sağlıklı geçiş için ekip değerlendirme, schema audit ve migration kültürü kurulumu kapsamında destek sunuyorum.

Ek okumalar için Drizzle resmi dokümantasyonu, GitHub repo’su, PostgreSQL ALTER TABLE referansı, PlanetScale online DDL karşılaştırması, Stack Overflow Developer Survey 2024, Cloudflare D1 dokümantasyonu ve drizzle-kit npm sayfası bakılabilir.