Drizzle ORM ve NestJS ile API'ler Oluşturma: Tam Kılavuz

Drizzle ORM, tam tür güvenliği ve sıfır çalışma süresi ek yükü ile SQL benzeri sözdizimi sunan, en hızlı büyüyen TypeScript ORM olarak ortaya çıktı. NestJS ile birleştirildiğinde, hem geliştirici dostu hem de performanslı üretim API'leri oluşturmak için güçlü bir yığın oluşturur.

Önemli Çıkarımlar

• Drizzle, tam TypeScript çıkarımıyla SQL benzeri sorgular sağlar - kod oluşturma adımı yoktur
• NestJS bağımlılık enjeksiyonu, Drizzle veritabanı bağlantılarıyla temiz bir şekilde bütünleşir
• Şema odaklı geliştirme, veritabanı ve TypeScript türlerinin senkronize kalmasını sağlar
• Drizzle push ve geçiş komutları şema gelişimini kesinti olmadan yönetir

---

Proje Kurulumu

Kurulum

Bir NestJS projesiyle başlayın ve Drizzle bağımlılıklarını ekleyin:

npm install drizzle-orm postgres
npm install -D drizzle-kit @types/pg

Performansı açısından postgres.js sürücüsünü öneriyoruz. Üretimde bağlantı havuzu oluşturmak için PgBouncer'ı veya sunucusuz olarak optimize edilmiş sürücüleri düşünün.

Veritabanı Bağlantı Modülü

Bağımlılık ekleme yoluyla Drizzle örneğini sağlayan genel bir veritabanı modülü oluşturun. DATABASE_URL'den bir postgres istemcisi oluşturan ve drizzle(client, \\\\\\\\{ schema \\\\\\\\}) döndüren useFactory'yi kullanarak bir DB_TOKEN sağlayıcısı tanımlayın. Herhangi bir hizmetin @Inject("DRIZZLE_DB") ile enjekte edebilmesi için belirteci dışa aktarın.

---

Şema Tanımı

Drizzle tablo oluşturucularını kullanarak veritabanı tablolarını tanımlayın. Her tablo, uuid, varchar, timestamp, boolean ve diğer sütun türlerini kullanan sütun tanımlarını içeren pgTable() ile oluşturulan bir const'ı dışa aktarır. Sütunlar varsayılanları (defaultRandom, defaultNow), kısıtlamaları (notNull, benzersiz) ve ilişkileri destekler.

İlişkileri Tanımlama

Çiseleme ilişkileri tip açısından güvenli istekli yükleme sağlar. İlişkileri, many() ile birden çoğa ve one() ile çoktan bire belirterek, ilişkiler() işlevini kullanarak tanımlayın. Referans sütunları yabancı anahtarları üst tablo birincil anahtarlarıyla eşler.

---

Sorgu Oluşturma

Sorguları Seçin

Tam tip çıkarım sağlarken sorguları SQL gibi okuyun:

• Basit seçim: db.select().from(users)
• Filtrelendi: db.select().from(users).where(and(eq(users.role, "admin"), eq(users.isActive, true)))
• Birleştirmelerle: db.select().from(users).leftJoin(orders, eq(users.id, siparişler.userId))
• İlişki yükleme: db.query.users.findMany(\\\\\\\\{ with: { siparişler: doğru \\\\\\\\}, limit: 20 })

Ekle, Güncelle, Sil

// Insert with returning
const [newUser] = await this.db
  .insert(users)
  .values({ email: "user@example.com", name: "New User" })
  .returning();

// Update
await this.db
  .update(users)
  .set({ role: "admin", updatedAt: new Date() })
  .where(eq(users.id, userId));

// Delete
await this.db.delete(users).where(eq(users.id, userId));

---

İşlemler

Drizzle işlemleri atomik işlemleri sağlar. Bir işlem nesnesini (tx) alan eşzamansız geri çağırma ile db.transaction() öğesini çağırın. Geri aramadaki tüm sorgular atomik olarak yürütülür; herhangi biri başarısız olursa işlemin tamamı geri alınır.

Yaygın kullanım örnekleri arasında ana ve alt kayıtların birlikte oluşturulması, siparişleri işlerken envanterin güncellenmesi ve hesaplar arasında fon aktarımı yer alır.

---

Göçler

Şema Aktarımı (Geliştirme)

Geliştirme sırasında, push şeması doğrudan drizzle kit push ile değişir. Bu, şema dosyalarınızı veritabanıyla karşılaştırır ve değişiklikleri uygular. Geliştirme için hızlı ancak üretim için uygun değil.

Taşıma Dosyaları (Üretim)

Üretim için, drizzle-kit created ile sürümlendirilmiş SQL geçiş dosyaları oluşturun ve ardından bunları drizzle-kit geçiş ile uygulayın. Geçiş dosyaları hazırlamada incelenebilir, test edilebilir ve CI/CD işlem hatlarında uygulanabilir.

---

NestJS Entegrasyon Modelleri

Hizmet Modeli

Hizmetler Drizzle veritabanını enjekte eder ve dinamik filtrelerle sorgular oluşturur:

@Injectable()
export class ProductsService {
  constructor(@Inject("DRIZZLE_DB") private db: DrizzleDB) {}

  async findAll(filters: ProductFilters) {
    const conditions = [];
    if (filters.category)
      conditions.push(eq(products.category, filters.category));
    if (filters.minPrice)
      conditions.push(gte(products.price, filters.minPrice));

    return this.db
      .select()
      .from(products)
      .where(conditions.length ? and(...conditions) : undefined)
      .orderBy(desc(products.createdAt))
      .limit(filters.limit || 20)
      .offset(filters.offset || 0);
  }
}

Çoklu Kiracılık

SaaS uygulamaları için her sorgunun kuruluş kimliğine göre filtrelenmesi gerekir. Tüm veritabanı işlemlerinde kiracı izolasyonunu sağlayan bir temel hizmet veya ara yazılım oluşturun. İstemci tarafından sağlanan kuruluş kimliklerine asla güvenmeyin; kimliği doğrulanmış oturuma göre doğrulayın.

Parametreli Sorgular

Drizzle varsayılan olarak parametreli sorgular kullanarak SQL enjeksiyonunu engeller. Hiçbir zaman kullanıcı girişiyle sql.raw() işlevini kullanmayın. Bunun yerine, enterpolasyonlu değerleri otomatik olarak parametreleştiren sql şablon değişmezini kullanın.

---

En İyi Performans Uygulamaları

1. Yalnızca gerekli sütunları seçin: Tüm sütunları seçmek yerine .select(\\\\{ id: kullanıcılar.id, ad: kullanıcılar.adı \\\\}) kullanın
2. Dizinleri kullanın: Sık sık filtrelenen sütunların veritabanı dizinlerine sahip olduğundan emin olun
3. Sonuçları sınırlayın: Liste sorgularında her zaman .limit() yöntemini kullanın
4. Toplu eklemeler: Toplu eklemeler için döngüler yerine .values([...array]) kullanın
5. Bağlantı havuzu oluşturma: İş yükünüze uygun havuz boyutlarını yapılandırın
6. Tembel bağlantılar: Bağlantıyı ilk sorguya kadar ertelemek için Proxy modelini kullanın

---

Sıkça Sorulan Sorular

S: Drizzle, NestJS için Prisma ile karşılaştırıldığında nasıldır?

Drizzle daha SQL odaklıdır ve sıfır çalışma süresi yüküne sahiptir (sorgu motoru yoktur). Prisma kendi sorgulama dilini kullanır ve oluşturulmuş bir istemciye ihtiyaç duyar. Drizzle daha küçük paket boyutuna ve daha hızlı soğuk başlatmaya sahipken, Prisma daha büyük bir ekosisteme ve daha fazla alete sahiptir.

S: Drizzle karmaşık ham SQL'i işleyebilir mi?

Evet. Sql şablon değişmezi, parametreli güvenliği korurken ham sorguları destekler. Drizzle, sorgular için hiçbir zaman dize birleştirmeyi kullanmaz ve SQL enjeksiyonunu engeller.

S: Üretimde bağlantı havuzu oluşturmaya ne dersiniz?

PgBouncer'ı uygulamanın dışında kullanın veya postgres.js sürücüsünü maksimum bağlantı limitleriyle yapılandırın. Sunucusuz ortamlar için, yerleşik havuzlama özelliğine sahip, sunucusuz olarak optimize edilmiş sürücüleri kullanın.

S: Şema değişikliklerini kesinti olmadan nasıl halledebiliriz?

Geçiş dosyaları oluşturun, SQL'i inceleyin, aşamalandırmada test edin ve ardından üretimde uygulayın. PostgreSQL'deki çoğu ALTER TABLE ifadesi özel kilitler olmadan yürütülür. Yoğun saatlerde tablonun yeniden yazılmasını gerektiren işlemlerden kaçının.

---

Sırada Ne Var

NestJS ile Drizzle ORM, üretim API'leri oluşturmak için tür açısından güvenli, performanslı bir temel sağlar. SQL benzeri API soyutlama boşluğunu en aza indirirken TypeScript çıkarımı çalışma zamanı türü hatalarını ortadan kaldırır.

API geliştirme yardımı için ECOSIRE ile iletişime geçin veya özel API'leri ERP'nize bağlamak için Odoo entegrasyon hizmetlerimizi inceleyin.

---

ECOSIRE tarafından yayınlandı - işletmelerin kurumsal yazılım çözümleriyle ölçeklenmesine yardımcı oluyor.