Belajar Quarkus - Database & Persistence

#Pendahuluan

REST API tanpa penyimpanan data hanya mainan. Episode 6 membawa aplikasi kalian ke level berikutnya: menyimpan dan membaca data dari database. Quarkus mengintegrasikan Hibernate ORM — standar JPA (Jakarta Persistence) — dengan Panache untuk menghilangkan boilerplate.

Panache memberi dua pola populer: active record dan repository. Kalian juga akan belajar konfigurasi datasource, connection pooling, dan penggunaan H2 sebagai database in-memory untuk development tanpa perlu menginstall server database.

#Hibernate ORM dan Panache

#Apa itu Panache

Panache adalah layer di atas Hibernate ORM yang membuat entity dan query sangat ringkas. Tiga fitur utamanya:

• Entity tanpa getter/setter yang membosankan — field publik langsung dipakai.
• Method statis CRUD langsung di entity (pola active record).
• PanacheRepository untuk pola repository terpisah.

Tambahkan extension terlebih dahulu:

./mvnw quarkus:add-extension \
    -Dextensions=hibernate-orm-panache,jdbc-h2

Perintah ./mvnw quarkus:add-extension -Dextensions=hibernate-orm-panache,jdbc-h2 menambahkan Hibernate ORM dengan Panache dan driver JDBC untuk H2 sekaligus.

#Entity dengan Panache

Entity active record memperluas PanacheEntity yang sudah menyediakan field id bertipe Long:

Entity dengan active record

import jakarta.persistence.Entity;
import jakarta.persistence.Table;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
 
@Entity
@Table(name = "items")
public class Item extends PanacheEntity {
    public String nama;
    public String deskripsi;
    public double harga;
}

Tanpa getter dan setter, kalian membaca dan menulis field langsung: item.nama = "Laptop". Ini pola yang jauh lebih ringkas daripada JPA klasik.

#Entity Mapping dan Repository Pattern

#Mapping Dasar

Kadang kalian perlu mapping eksplisit untuk tabel dengan nama kolom berbeda atau relasi:

Entity dengan mapping eksplisit

import jakarta.persistence.*;
 
@Entity
@Table(name = "items")
public class Item {
 
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    public Long id;
 
    @Column(name = "nama_item", nullable = false, length = 100)
    public String nama;
 
    @Column(name = "harga", precision = 12, scale = 2)
    public double harga;
}

Catatan: class ini tidak memperluas PanacheEntity, sehingga kalian mengelola @Id sendiri. Pemakaian @Column memberikan kontrol penuh atas nama dan constraint kolom.

#Repository Pattern

Untuk memisahkan logic akses data dari entity, gunakan PanacheRepository:

Repository Panache

import io.quarkus.hibernate.orm.panache.PanacheRepository;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;
 
@ApplicationScoped
public class ItemRepository implements PanacheRepository<Item> {
 
    public List<Item> cariBerdasarkanNama(String keyword) {
        return list("nama like ?1", "%" + keyword + "%");
    }
}

Method list("nama like ?1", ...) memakai PanacheQL — dialek JP-QL yang lebih sederhana. Repository di-inject ke resource dengan @Inject.

#Memakai Repository di Resource

Repository di-inject ke resource dengan @Inject, lalu memakai method bawaan PanacheRepository: itemRepository.persist(item) untuk menyimpan entity baru dan listAll() untuk mengambil seluruh data. Method custom seperti cariBerdasarkanNama dipanggil dengan cara yang sama.

#Konfigurasi Datasource dan Connection Pooling

#Konfigurasi di application.properties

Quarkus memakai Agroal sebagai connection pool bawaan. Konfigurasi datasource H2 untuk development:

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:belajar
quarkus.datasource.username=sa
quarkus.datasource.password=
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.log.sql=true

• db-kind=h2 memberi tahu Quarkus tipe database.
• database.generation=drop-and-create membuat skema otomatis saat start (khusus development).
• log.sql=true menampilkan query SQL di konsol — sangat membantu debugging.

#Connection Pooling

Pool dikelola otomatis oleh Agroal. Konfigurasi umum:

quarkus.datasource.jdbc.min-size=1
quarkus.datasource.jdbc.max-size=20
quarkus.datasource.jdbc.acquisition-timeout=10S

Untuk produksi, perhatikan max-size dan acquisition-timeout agar aplikasi tidak kehabisan koneksi saat lonjakan traffic.

#Basis Data In-Memory H2 dan Dev Services

#Keuntungan H2

H2 berjalan dalam memori, tanpa instalasi server. Ideal untuk development dan test karena setiap restart aplikasi memberi database bersih. Quarkus juga menawarkan Dev Services: setel quarkus.datasource.db-kind=postgresql tanpa URL, dan dengan Docker berjalan, Quarkus otomatis memulai PostgreSQL dalam container saat mode dev — database nyata tanpa setup manual.

#Uji Coba End-to-End

Jalankan ./mvnw quarkus:dev lalu uji API dengan curl:

• curl -X POST http://localhost:8080/api/items -H "Content-Type: application/json" -d '{"nama":"Laptop","deskripsi":"Laptop developer","harga":15000000}' mengirim item baru.
• curl http://localhost:8080/api/items membaca daftar item yang sudah tersimpan.

Kalian juga bisa melihat query SQL yang dijalankan Hibernate di konsol dev mode.

#Penutup

Episode 6 menghubungkan aplikasi Quarkus dengan database: memahami Hibernate ORM dan Panache dengan pola active record dan repository, mapping entity dan kolom, konfigurasi datasource dan connection pool Agroal, serta penggunaan H2 dan Dev Services untuk development.

Inti yang harus dibawa pulang:

• Panache menghilangkan boilerplate JPA dengan dua pola: active record dan repository.
• PanacheEntity menyediakan field id otomatis.
• PanacheRepository memberi method CRUD bawaan seperti persist dan listAll.
• quarkus.datasource.db-kind menentukan tipe database.
• H2 in-memory cocok untuk development; drop-and-create untuk skema cepat.
• Dev Services menjalankan database nyata dalam container tanpa setup manual.
• Connection pool Agroal dikelola otomatis dan bisa disetel di properties.

Di episode 7 selanjutnya kita akan membahas validasi dan request handling — Jakarta Bean Validation dengan @Valid dan constraint annotations, request serta response filter, interceptor, dan exception translation untuk error yang lebih rapi.