SQLBraid 1.0, tipli bind'ler ve sonuç eşlemesiyle TypeScript'te ham SQL'yi koruyor

SQL-first bir TypeScript veri erişim araç seti olan SQLBraid, bu hafta GitHub deposuna bağlantı veren bir Show HN gönderisiyle Hacker News ana sayfasında yer aldı. Proje 1.0.0 sürümüne ulaştı; README bu sürümü kararlı bir public API olarak tanımlıyor. Öneri net: SQL'yi doğrudan yazın ve query-builder çeviri katmanını atlayın; sıradan SQL'yi görünür tutarken güvenli değer bind'leme, okunabilir dinamik SQL, açık sonuç sözleşmeleri ve Standard Schema sonuç eşlemesi ekleyin.

Sorgular nasıl yazılır

Geliştiriciler sorguları tagged template literal olarak yazar. UserRow tip parametresiyle yapılan bir sql.rows çağrısı, bir SELECT ifadesine satır tipini iliştirir ve enterpolasyona giren her değer ifadesi parametre bind'ine dönüşür — asla literal SQL metni olmaz. Identifier, fragment, liste ve ham SQL ise sql.ident, sql.fragment, sql.list, sql.join ve sql.raw gibi açık yardımcılardan geçer; README bu ayrımı veri ile yapı arasındaki temel sınır olarak adlandırıyor.

Dinamik SQL, @braid direktifleriyle — if, choose, when, otherwise, where, set ve trim — ifade içinde yorum olarak yazılıp SQLBraid'in derleyicisi tarafından derleniyor. Etkin olmayan dallar tembel kalır, böylece koşullu bir WHERE ifadesi, veritabanının alacağı nihai SQL'ye yakın okunur. Renderer, tek bir değişmez RenderedStatement üretir; burada render edilmiş bir parametre asla SQL, identifier, iç içe sorgu veya driver fragment'ı olamaz — bu da enjeksiyona karşı koruyan mekanizmadır. $1, ? veya :1 gibi placeholder sözdizimi seçilen adaptöre bırakılır ve mantıksal ifade biçimi taşıma katmanından bağımsız kalır.

Sonuç sözleşmeleri ve doğrulama

Sorgular açık bir sonuç türü taşır: satır döndüren ifadeler için sql.rows, güncellemeler için sql.command, tipli sonuç kümeleriyle stored procedure'ler için sql.call, ya da biçimi bilinmeyen driver'a özgü ifadeler için düz sql. Runtime metotları bu sözleşmelere eşlenir. README'ye göre db.all, db.one, db.maybeOne ve db.stream bir sql.rows sorgusu gerektirirken, db.execute satır, command veya bilinmeyen sorguları kabul eder ve gerçek sonuç türünü çalıştırmadan sonra kontrol eder. Bir uyuşmazlık BRAID_RESULT_KIND hatası olarak ortaya çıkar; bu hata, veritabanında uygulanmış bir yan etkiyi geri alamaz.

Satır doğrulaması Standard Schema kullanır: bir schema sorgunun kendisine eklenebilir ya da her çalıştırmada ayrıca geçirilebilir ve eşleme kesinlikle bir satırdan bir uygulama değerinedir. SQLBraid bilinçli olarak ilişkileri hydrate etmez, identity map tutmaz veya rastgele SELECT ve JOIN biçimlerinden tip çıkarmaz — bu, tam ORM'lerle bir karşıtlıktır.

Bağlantılar, oturumlar ve transaction'lar

Public runtime yüzeyi bilinçli olarak küçüktür: execute, all, one, maybeOne, call, batch, bulk, stream, session ve tx. Tüm çalıştırma metotları, bir AbortSignal dahil, sonda gelen option'ları kabul eder. İptal yetenek tabanlıdır; zaten iptal edilmiş bir sinyal gerekçesiyle reddedilir ve bir adaptörün iptal yeteneği yoksa işlem, iptalin çalıştığı gibi davranmak yerine UnsupportedFeatureError ile başarısız olur.

Pool'lu bir veritabanı, pool'un kendisini bir executor olarak modellemek yerine lease'leri dağıtan bir ConnectionProvider'ı sarar. Pool'lu her kök işlem bir lease edinir, fiziksel I/O'yu gerçekleştirir, lease'i serbest bırakır ve ancak sonra somutlaştırılmış sonuçları eşler; stream'ler driver kaynağı kapanana kadar lease'lerini tutar. db.session bir callback süresince tek bir fiziksel bağlantıyı sabitler ve iç içe işlemlerde onu yeniden kullanır; oturum içindeki db.tx ise yeniden edinmek yerine aynı lease'i kullanır. İç içe transaction'lar, executor bunları sunuyorsa savepoint'lere düşer; desteklenmeyen isolation veya read-only option'ları sessizce yok sayılmak yerine yetenek hatalarıyla açıkça başarısız olur.

Driver'lar ve sürüm durumu

Araç seti, PostgreSQL (pg), MySQL (mysql2), MariaDB, node:sqlite, better-sqlite3, libsql, sqlite-wasm, Cloudflare D1, oracledb ve SQL Server için tedious için birleşik driver ve dialect giriş noktalarıyla geliyor. Kök facade'de örtük bir varsayılan dialect yok. Yetenekler adaptöre göre değişir: README, SQLite adaptörlerinin db.call desteklemediğini, PostgreSQL refcursor'lerinin mevcut bir transaction gerektirdiğini ve desteklenmeyen routine kanallarının emüle edilmek yerine açıkça başarısız olduğunu belirtiyor. Sürümlü destek kayıtları her veritabanı, driver, profile ve runtime kümesini sertifikalandırır; değişen revizyonlar komşu sürümlerden sertifika devralmak yerine yeni runtime, dokümantasyon ve release kapıları gerektirir.

Neden önemli

TypeScript veri erişimi büyük ölçüde iki kampa ayrıldı: elle kurulan SQL dizeleriyle ham driver'lar ve SQL'yi bir DSL arkasına saklayan query builder veya ORM'ler. SQLBraid tam da bu boşluğu hedefliyor. Geliştiriciler zaten bildikleri SQL'yi yazmaya devam eder, bind'ler yapı gereği parametrelidir, sonuçlar schema'lara göre doğrulanır ve koşullu ifadeler dizgi birleştirme yerine yapılandırılmış bir direktif mekanizmasıyla ele alınır. Kararlı ilan edilen 1.0 API'si ve Node, serverless ve tarayıcı SQLite hedeflerini kapsayan geniş adaptör listesiyle, SQLBraid; query-builder sözlüğü benimsemeden tip güvenliği ve enjeksiyon direnci isteyen ekipler için ciddi bir seçenek.