Setup PostgreSQL + Spring Data JPA

Fase 1 kita tutup dengan Order Service yang sudah bisa menerima request, memvalidasi input, dan mengembalikan response error yang konsisten — tapi semua datanya masih hidup di memory, hilang setiap kali aplikasi restart. Mulai bab ini kita masuk Fase 2: menyambungkan Order Service ke database sungguhan, PostgreSQL, lewat Spring Data JPA.

Apa itu Spring Data JPA?

JPA (Jakarta Persistence API) adalah spesifikasi standar Java untuk memetakan object ke baris tabel database — dikenal sebagai ORM (Object-Relational Mapping). Hibernate adalah implementasi JPA yang paling umum dipakai, dan Spring Boot memakainya secara default lewat starter spring-boot-starter-data-jpa.

Spring Data JPA menambahkan satu lapis lagi di atas JPA/Hibernate: kamu cukup mendeklarasikan sebuah interface yang mewarisi JpaRepository, dan Spring akan otomatis membuatkan implementasinya saat aplikasi jalan — lengkap dengan method save, findById, findAll, sampai method query custom yang disusun dari nama method itu sendiri. Kita akan bahas detailnya di bab berikutnya; bab ini fokus dulu ke fondasi: bagaimana Order Service terhubung ke PostgreSQL.

Menjalankan PostgreSQL lewat Docker Compose

Supaya tidak perlu install PostgreSQL manual di komputer masing-masing, project ini menyediakan docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: order_service_dev
      POSTGRES_USER: order_service
      POSTGRES_PASSWORD: order_service
    ports:
      - "5432:5432"
    volumes:
      - order_service_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U order_service -d order_service_dev"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  order_service_pgdata:

Beberapa hal yang layak diperhatikan:

• postgres:16-alpine — image resmi PostgreSQL versi 16, varian alpine yang ukurannya jauh lebih kecil dibanding image default.
• POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD — environment variable bawaan image resmi Postgres, dipakai untuk membuat database dan user secara otomatis saat container pertama kali start.
• volumes: order_service_pgdata — named volume yang menyimpan data Postgres di luar container. Tanpa ini, setiap kali container dihapus (docker compose down), seluruh data ikut hilang.
• healthcheck — bagian yang sering dilewatkan tapi penting. pg_isready adalah utilitas bawaan Postgres yang mengecek apakah database sudah benar-benar siap menerima koneksi, bukan cuma "container sudah nyala". Perbedaan ini penting: container Postgres bisa saja sudah berstatus "running" padahal proses inisialisasi database di dalamnya belum selesai. Kalau service lain (atau langkah setup lain) bergantung pada Postgres ini lewat depends_on: condition: service_healthy, Docker akan menunggu healthcheck ini benar-benar lolos dulu, bukan asal container jalan.

Menjalankannya cukup dengan:

docker compose up -d

Konfigurasi datasource di application-dev.yml

Base config application.yml menetapkan spring.profiles.active: dev, jadi saat aplikasi jalan tanpa override, Spring Boot otomatis melayer konfigurasi dari application-dev.yml di atas application.yml. Isinya:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/order_service_dev
    username: order_service
    password: order_service
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        format_sql: true
  flyway:
    enabled: true

logging:
  level:
    com.indokoding.orderservice: DEBUG

spring.datasource.url/username/password inilah yang menyambungkan Spring Boot ke container Postgres yang baru saja kita jalankan — perhatikan nilainya cocok persis dengan POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD di docker-compose.yml. show-sql: true dan format_sql: true berguna khusus untuk development: setiap query yang dijalankan Hibernate akan tercetak di log dalam bentuk SQL yang rapi, jadi kamu bisa mengecek langsung query apa yang sebenarnya dikirim ke database — sangat membantu saat debug query yang lambat atau tidak sesuai ekspektasi.

Kenapa ddl-auto: validate, bukan update?

Ini keputusan paling penting di file ini. Properti hibernate.ddl-auto menentukan apa yang Hibernate lakukan terhadap skema database saat aplikasi start, dan ada beberapa pilihan:

• create — hapus semua tabel, lalu buat ulang dari nol berdasarkan entity Kotlin. Cocok untuk eksperimen sekali pakai, berbahaya untuk apa pun yang datanya ingin dipertahankan.
• update — Hibernate membandingkan entity dengan skema yang ada, lalu menambahkan kolom/tabel yang "kurang" secara otomatis. Kelihatan praktis, tapi menyimpan bahaya tersembunyi: perubahan skema tidak pernah direview, tidak tercatat riwayatnya, dan bisa berbeda hasil antar environment tergantung urutan Hibernate memindai entity.
• validate — Hibernate tidak mengubah apa pun. Ia hanya membandingkan entity Kotlin dengan struktur tabel yang sudah ada, dan melempar error saat aplikasi start kalau ada ketidaksesuaian (misalnya entity punya kolom yang tidak ada di tabel).

Order Service memakai validate di ketiga environment — dev, test, maupun prod. Alasannya: skema database seharusnya berubah lewat satu jalur yang eksplisit dan bisa direview, bukan disimpulkan otomatis oleh ORM setiap kali aplikasi start. Kalau ddl-auto dibiarkan update, dua orang developer bisa punya struktur tabel yang sedikit berbeda di komputernya masing-masing tanpa sadar, dan kesalahan struktur baru ketahuan saat sudah di production. Dengan validate, begitu ada mismatch antara kode dan skema, aplikasi langsung gagal start dengan pesan error yang jelas — jauh lebih aman daripada gagal diam-diam.

Lalu kalau Hibernate tidak boleh mengubah skema, siapa yang bertugas membuat tabel orders di awal? Jawabannya Flyway — flyway.enabled: true di atas mengaktifkannya, dan itu topik utama bab berikutnya.