"jOOQ mu, JPA mı?" sorusunu Sigorta Satış Yönetimi'nde hiç tek cevaplı sormadım. Kararı mimari kayıtlarıma (ADR-053, 27 Nisan 2026) şöyle yazmışım: "jOOQ, JPA'yı değiştirmez — tamamlar." Basit CRUD JPA'da kalacak; arama, dinamik filtre, sayfalama, sayım ve raporlama jOOQ'ya gidecekti. Kâğıt üzerinde temiz bir ayrım. Bu yazıda kodun bugün gerçekte neye benzediğini, sayılarıyla anlatıyorum. Kısa versiyonu şu: JPA projeyi taşıyor, jOOQ bir kenarda duruyor ve tip güvenliği hâlâ "gelecek sprint"te.
Sayılarla durum
Proje Spring Boot 4.0.6 ve Java 25 üzerinde çalışan modüler bir monolit: 8 modül, tek PostgreSQL veritabanı, acente başına ayrı şema. Paket sürümlerini çalışan jar'dan okudum, kullanımları da grep ile saydım:
| Sayı | |
|---|---|
| jOOQ sürümü (Boot yönetiyor) | 3.19.32 |
| Hibernate sürümü | 7.2.12 |
@Entity sınıfı |
44 |
JpaRepository arayüzü |
41 |
@Query (JPQL + native) |
56, bunların 8'i nativeQuery = true |
jOOQ *QueryAdapter sınıfı |
9 (toplam 1163 satır) |
| Bu adapter'lardan gerçekten inject edilen | 4 (customer, policy, quote, inbox) |
| Flyway migration dosyası | 48 (21 public, 27 tenant) |
| Quartz/ShedLock hariç tablo | 51 |
| jOOQ'ya dokunan test dosyası | 0 |
Tablo hikâyenin yarısını anlatıyor. Yazma yolunun tamamı ve okuma yolunun büyük kısmı JPA'da. jOOQ'nun 9 adapter'ından 5'i (workflow, notification'da iki tane, reminder'da iki tane) hiçbir sınıfa inject edilmiyor. ADR'de "Tamamlandı" diye işaretli olmalarına rağmen ölü kod durumundalar.
Kod üretimi yok, tipler string
Başlıktaki "tip güvenli SQL" iddiası bu projede henüz doğru değil. pom.xml içinde jooq-codegen-maven eklentisi yok. Flyway migration'larından, Testcontainers'tan ya da DDLDatabase üzerinden üretilmiş tek bir sınıf da yok. Bütün sorgular table("policies"), field("created_at") ve condition("tenant_id = ?", ...) ile yazılmış:
private PagedData<Policy> fetchPaged(Condition cond, Pageable pageable) {
long total = dsl.selectCount()
.from(table("policies"))
.where(cond)
.fetchOne(0, Long.class);
List<Policy> policies = dsl.select(asterisk())
.from(table("policies"))
.where(cond)
.orderBy(field("created_at").desc())
.limit(pageable.getPageSize())
.offset(pageable.getOffset())
.fetch().stream().map(this::mapToPolicy).toList();
...
}
Bu kod @Query(nativeQuery = true) ile yazılmış SQL'den daha güvenli değil. Kolon adını yanlış yazarsam hatayı yine çalışma anında görürüm. jOOQ burada yalnızca bir SQL string oluşturucu işi görüyor. Parametre bağlama ve koşulları koda göre birleştirme konusunda da yardımcı oluyor.
Codegen'in ertelendiği kodda da yazıyor. CustomerQueryAdapter içindeki not "Sprint 15'te Flyway migration'larından jOOQ codegen aktif edilecek" diyor. ADR-053 aynı işi "Sprint 16 hedefi" olarak listeliyor ve tenant_template şemasına bağlanan, PostgresDatabase kullanan bir plugin örneği veriyor. İki tarih birbirini tutmuyor ve ikisi de gerçekleşmedi.
Kayıttan entity'ye elle eşleme
Codegen olmayınca her adapter'da mapToX(Record r) metodu var ve sonuç bir JPA entity'sine elle dolduruluyor. Para alanları sorunsuz geçiyor. premium_tl kolonu NUMERIC(15,2) ve hem entity'de hem jOOQ tarafında BigDecimal olarak okunuyor. Migration'larda 18 tane NUMERIC(15,2) var ve projede hiçbir yerde double ile para tutulmuyor. Enum'lar @Enumerated(EnumType.STRING) (37 kullanım) ile yazılıyor, veritabanında CHECK (status IN (...)) ile korunuyor. jOOQ tarafında ise PolicyStatus.valueOf(r.get("status", String.class)) ile geri çevriliyor. Veritabanında enum'da olmayan bir değer varsa liste sorgusu IllegalArgumentException ile düşer. Bunu da derleyici değil, veri yakalar.
Elle eşlemenin asıl bedeli JPA yaşam döngüsünü atlamak. CustomerQueryAdapter içindeki şu yorum durumu iyi özetliyor:
// V6 (identity_number_migration): tc_no/vkn/foreign_id → identity_type + identifier_no.
// jOOQ @PostLoad tetiklemez, bu yüzden typed field'ı burada elle yeniden kuruyoruz.
switch (idType) {
case TCKN -> c.setTcNo(tryTcNo(identifierNo));
case VKN -> { /* @PostLoad'da kurulur; liste görünümü için gerek yok */ }
case YKN, PASSPORT -> { /* benzer şekilde */ }
}
Böylece aynı Customer nesnesi JPA'dan gelince tam, jOOQ'dan gelince eksik doluyor. InboxMessageQueryAdapter daha da açık. @Embedded olan AiAnalysis alanını hiç doldurmuyor ama sıralamayı ai_urgency_score üzerinden yapıyor.
JSONB'ye jOOQ hiç dokunmuyor
Migration'larda 7 JSONB kolonu var: audit kayıtlarında old_value/new_value, teklif tablolarında input_params, company_results, installment_options, features ve inbox durum geçmişinde metadata. Bunların JPA tarafında eşlenenleri @JdbcTypeCode(SqlTypes.JSON) ile eşlenmiş. Hiçbir jOOQ sorgusu JSONB okumuyor ya da filtrelemiyor. jOOQ'nun JSONB tipi ve jsonbValue gibi operatörleri projede kullanılmıyor. JSONB'nin jOOQ'yu haklı çıkarabileceği yerlerden biri olduğunu düşünüyorum ama burada o ihtiyaç henüz doğmadı.
Acente başına şema: iki bağlantı sağlayıcı
Her acentenin kendi şeması var (ör. tenant_mza) ve tablolar şemasız adlandırılıyor. Yönlendirme iki ayrı yerde, iki kez yazılmış:
- JPA için
TenantSchemaConnectionProvider, Hibernate'inMultiTenantConnectionProviderarayüzünü uyguluyor. - jOOQ için
TenantAwareConnectionProvider, jOOQ'nunConnectionProviderarayüzünü uyguluyor veDSLContextrenderSchema(false)ile kuruluyor.
RenderMapping ya da şema eşleme kullanmıyorum. İkisi de bağlantıyı aldıktan sonra search_path ayarlıyor:
Connection conn = dataSource.getConnection();
String schema = TenantContext.getDbSchema();
if (schema != null && !schema.isBlank()) {
stmt.execute("SET search_path TO " + sanitizeSchema(schema) + ", public");
}
return conn;
Bu yazıyı hazırlarken ikisi arasında önemli bir fark buldum. Hibernate tarafındaki sağlayıcı bağlantıyı havuza geri verirken SET search_path TO public çalıştırıyordu. jOOQ tarafındaki release() ise bağlantıyı doğrudan kapatıyordu. Tenant bağlamı yoksa search_path hiç ayarlanmıyor, log'a yalnızca "public kullanılıyor" yazılıyordu. Oysa havuzdaki bağlantı close() ile kapanmıyor, havuza dönüyor. Bir sonraki istek, en son hangi acentenin şemasında kaldıysa onu orada buluyordu. Tenant bağlamı olmadan çalışan bir jOOQ sorgusu, kimin olduğunu bilmediği bir acentenin tablolarını görebilirdi. Örneğin KVKK anonimleştirme sorgusu tenant bağlamı olmayan bir zamanlanmış işten çağrılıyor.
Düzeltme iki katmanlı oldu:
String searchPath = (schema != null && !schema.isBlank())
? sanitizeSchema(schema) + ", public"
: "public"; // tenant yoksa da açıkça sıfırla
Connection conn = dataSource.getConnection();
try (Statement stmt = conn.createStatement()) {
stmt.execute("SET search_path TO " + searchPath);
} catch (SQLException e) {
conn.close(); // ayarlanamayan bağlantı dışarı verilmez
throw e;
}
release() de artık Hibernate tarafı gibi kapatmadan önce search_path'i public'e çekiyor. İkisinden biri tek başına yeterdi. Ama havuz paylaşılan bir kaynak ve bağlantıyı kirleten başka bir kod yolu da çıkabilir; o yüzden her edinmede açıkça ayarlamak asıl koruma, iadede sıfırlamak ise ikinci kat. Şema adının doğrulanması da bağlantı alınmadan önceye taşındı, geçersiz bir adda havuzdan bağlantı sızmıyor. Beş birim testi ekledim ve gerçekten yakaladıklarını görmek için düzeltmeyi geçici olarak geri aldım: beşten dördü düştü. Geçen tek test, zaten doğru çalışan tenant'lı senaryoydu.
Açığın canlıda bir veri sızıntısına yol açıp açmadığını bilmiyorum. Bildiğim şu: kodu okuyan biri bunu görebiliyordu ve hiçbir test bunu sınamıyordu.
Transaction sınırı
JooqAutoConfiguration içindeki DSLContext, Spring'in DataSource nesnesini doğrudan alıyor. Ne TransactionAwareDataSourceProxy ile sarmalanmış ne de Spring'in jOOQ transaction entegrasyonunu kullanıyor. Entegrasyon testinin log'unda "[jOOQ] TenantAware DSLContext başlatılıyor" satırı görünüyor, yani devrede olan bean bu. Sonuç olarak jOOQ sorguları JPA'nın açtığı transaction'a katılmıyor, havuzdan ayrı bir bağlantı alıyor. Aynı @Transactional metot içinde JPA ile yazıp jOOQ ile okursam henüz commit edilmemiş satırı göremem. Bugünkü kullanımda jOOQ yalnızca liste ve sayım yaptığı için bu sorun çıkarmıyor. Yine de "JPA yazar, jOOQ okur" desenini kuran birinin bilmesi gereken bir şey.
JPA'nın gerçekten ağrıttığı yer
Genel JPA eleştirilerinin bu projede somut karşılıkları var:
- Lazy loading:
open-in-view: trueaçık bırakılmış.application.ymliçindeki yorum nedenini söylüyor: controller'lar response yazarken lazy ilişkileri yüklüyor,falseolursaLazyInitializationExceptionalınıyor. - Embedded + JPQL:
InboxServiceiçindeki yorum, Hibernate 6'da@Embeddedalt alanına JPQL ileWHERE/ORDER BYyapınca kök entity'nin embedded alanının null geldiğini anlatıyor. Çözüm olarak sayfa önce filtrelenip sıralanıyor, sonra her satırfindByIdile yeniden yükleniyor:
return messageRepository
.findFiltered(tenantId, status, insuranceType, isProspect, pageable)
.map(m -> InboxMessageResponse.from(
messageRepository.findById(m.getId()).orElse(m)));
İşin ilginç yanı, findFiltered bugün jOOQ adapter'ına gidiyor. Yorum JPQL zamanından kalmış, geçici çözüm de yerinde bırakılmış. Ortaya bir sayım sorgusu, bir sayfa sorgusu ve satır başına bir findById çıkıyor, yani düpedüz N+1. jOOQ eşleyicisi AiAnalysis alanını doldurmadığı için bu yeniden yükleme şu an gerçekten gerekli de.
- Soft delete: 5 entity'de
@SQLRestriction("deleted_at IS NULL")var. Silinmişleri okumak gerektiğinde native query'ye kaçılmış (CustomerRepository.findExpiredForAnonymization). jOOQ tarafında bu filtre otomatik değil, her sorguyacondition("deleted_at IS NULL")elle ekleniyor. ADR bu riski açıkça yazmış.
Raporlama ve dinamik filtre
jOOQ'nun en çok parladığı yer, koşulları koda göre birleştirmek oldu. QueryAdapter'larda Condition nesnesine if (status != null) cond = cond.and(...) şeklinde ekleme yapılıyor. JPQL tarafındaki (:status IS NULL OR m.status = :status) kalıbından daha okunaklı. Sayfalama ise ilkel: OFFSET/LIMIT ve ayrı bir selectCount(). Pageable içindeki sıralama yok sayılıyor, PolicyQueryAdapter içinde bunu itiraf eden bir yorum duruyor.
GROUP BY yazılmış tek yer WorkflowCardQueryAdapter (aşama bazında kart sayısı, atanan kişi bazında dağılım) ve o sınıf hiçbir yerde kullanılmıyor. ClickHouse için ayrı bir clickhouseDsl bean'i de hazır (ADR-054), ama crm.reporting.enabled varsayılanı false. Prod ayarlarının bulunduğu management-prod.yml hiçbir yerden import edilmiyor ve jar'da ClickHouse JDBC sürücüsü yok. Pratikte raporlama için jOOQ'nun pencere fonksiyonu ya da CTE gücüne bugüne kadar hiç ihtiyacım olmadı.
Öğrendiklerim ve tuzaklar
- Codegen olmadan jOOQ yarım bir karar. String tabanlı jOOQ, native SQL'e göre biraz daha düzenli ama derleme zamanı garantisi vermiyor. Bir sonraki adım Flyway migration'larını Testcontainers'taki bir PostgreSQL'e uygulayıp kodu oradan üretmek olmalı. Kod üretimi ancak her derlemede çalışırsa işe yarar.
- İki ORM, iki bağlantı sağlayıcı demek. Tenant yönlendirmesini iki yerde yazınca biri
search_path'i sıfırladı, öbürü sıfırlamadı. Açığı kapattım ama kök neden duruyor: iki sağlayıcının tek bir yardımcıyı paylaşması gerekiyor. - jOOQ sonucunu JPA entity'sine dökmek kırılgan.
@PostLoad, embedded alanlar ve value object'ler sessizce eksik kalıyor. jOOQ okumalarının ayrı ve dar bir okuma modeline (record/DTO) dönmesi daha dürüst olur. - Transaction'a katılmayan
DSLContextsürpriz yaratır. YaTransactionAwareDataSourceProxyile sarmalanmalı ya da Boot'un kendi jOOQ yapılandırmasına bırakılmalı. - "Tamamlandı" yazan ADR, inject edilmeyen sınıfı gizler. 9 adapter'dan 5'i ölü. Hiçbir testin jOOQ'ya dokunmaması bu durumu görünmez kıldı.
- Eski geçici çözümleri temizlemek gerekiyor. JPQL hatası için konan
findByIddöngüsü, jOOQ'ya geçince N+1 olarak kaldı.
Bugünkü cevabım şu: bu ölçekte bir CRM için JPA yeterli. jOOQ'yu ancak codegen'i açıp okuma modellerini ayırdığımda gerçekten "tip güvenli SQL" olarak kullanmış olacağım.
Kod üretimi olmayan jOOQ, daha düzgün yazılmış string SQL'den fazlası değil.