DEV Community: Arief Pasa Ibrahim

Belajar Flyway Episode 2: Cara Kerja Flyway dan Versioned Migrations

Arief Pasa Ibrahim — Sat, 19 Apr 2025 09:22:22 +0000

Halo! Selamat datang di Episode 2 dari seri belajar Flyway. Di episode sebelumnya kita sudah berkenalan dengan Flyway secara umum, yang teman-teman bisa baca ulang disini, ya (Belajar Flyway Episode 1: Pengenalan dan Migrasi Pertama). Nah, pada episode kali ini kita akan membahas lebih dalam tentang cara kerja Flyway, terutama mengenai versioned migrations (migrasi berversi). Kita juga akan melihat bagaimana Flyway mengeksekusi file migrasi berprefix V__, bagaimana Flyway menyimpan histori migrasi di database, serta sekilas perbedaan antara versioned vs. repeatable migrations. Gaya pembahasannya akan santai dan seperti ngobrol langsung, supaya mudah diikuti. Yuk, kita mulai!

Cara Kerja Flyway Secara Umum

Flyway adalah sebuah tool open-source untuk mengelola migrasi database dengan konsep versioning. Cara kerjanya cukup straight-forward: Flyway akan memindai (scan) lokasi file migrasi yang sudah kita tentukan (misalnya folder classpath:db/migration di proyek Java kita) dan membandingkan dengan catatan migrasi yang sudah diterapkan di database. Jika ditemukan perbedaan (ada migrasi baru yang belum pernah dijalankan), Flyway akan menjalankan skrip migrasi tersebut untuk “menutup gap” perbedaan versi antara struktur database dan kode aplikasi. Proses menjalankan perintah migrasi (flyway migrate) ini bersifat idempotent, artinya aman dijalankan berulang kali; jika tidak ada migrasi baru, Flyway tidak akan mengubah apa-apa.

Sebagai contoh, misalkan saat ini database kita ada di versi 5 (artinya migrasi terakhir yang terpasang bernomor 5), dan di folder migrasi tersedia file hingga V9. Ketika Flyway dijalankan, ia akan menerapkan migrasi versi 6, 7, 8, dan 9 secara berurutan ke database. Sebaliknya, jika database sudah up-to-date (sudah di versi 9 dan tidak ada file migrasi baru), Flyway tidak akan melakukan apa-apa. Dengan mekanisme ini, Flyway memastikan skema database selalu sync dengan ekspektasi aplikasi di manapun kita menjalankannya (development, staging, produksi, dll).

Tip: Biasanya Flyway dijalankan otomatis saat startup aplikasi (misalnya di aplikasi Spring Boot dengan PostgreSQL, migrasi akan berjalan ketika aplikasi dijalankan). Hal ini memastikan setiap instance aplikasi berjalan dengan skema database yang sesuai dengan versi kodenya, jadi tidak ada error karena perbedaan struktur. Tentu, Flyway juga bisa dijalankan manual via command line atau plugin build (Maven/Gradle) tergantung kebutuhan.

Konsep Versioned Migration (Migrasi Berversi)

Salah satu konsep inti Flyway adalah versioned migrations. Ini adalah skrip migrasi yang memiliki nomor versi unik di namanya, dieksekusi sekali saja dan secara berurutan sesuai urutan versinya. Begitu migrasi dengan versi tertentu dijalankan dan dicatat, Flyway tidak akan menjalankannya lagi di masa mendatang (kecuali kita mengubah versinya atau menghapus catatan historinya secara manual).

Penamaan file migrasi berversi biasanya mengikuti format:

V<versi>__<Deskripsi>.sql

Contoh nama file: V1__Initial_setup.sql, V2__Add_users_table.sql, V2.1__Update_user_role.sql dll.

Prefix V menandakan versioned migration.
Setelah itu diikuti nomor versi (boleh berupa integer berurutan atau format penomoran berjenjang dengan titik).
Lalu dua garis bawah __ sebagai pemisah, diikuti deskripsi singkat mengenai migrasinya.

Flyway akan mengurutkan file-file migrasi tersebut berdasarkan nomornya secara numerik dan menjalankannya sesuai urutan tersebut. Penting bahwa setiap file migrasi memiliki versi yang unik; Flyway akan mendeteksi jika ada duplikat versi dan akan menolak menjalankan migrasi yang konflik. Versi bisa berbentuk angka sederhana (1, 2, 3, ...) atau format bertitik (1.1, 1.2, 2.0, dst) sesuai kebutuhan, asalkan urut secara logis. Deskripsi setelah __ tidak berpengaruh ke proses (hanya untuk membantu kita mengingat tujuan migrasi), sedangkan ekstensi file biasanya .sql untuk migrasi SQL (Flyway juga mendukung migrasi berbasis Java, tapi umumnya kita pakai SQL saja).

Setelah skrip versioned migration diterapkan di satu lingkungan (terutama lingkungan production atau staging yang sifatnya permanen), best practice-nya adalah tidak mengubah isi skrip tersebut lagi. Kenapa? Karena Flyway menyimpan checksum (hash) dari file migrasi yang sudah dijalankan. Jika kita mengedit file yang sudah terekap di history, Flyway akan mendeteksi checksum-nya tidak cocok saat berikutnya dijalankan dan menandainya sebagai konflik. Solusinya, apabila perlu perubahan skema lagi, cukup buat file migrasi baru dengan nomor versi berikutnya untuk melakukan perubahan tersebut (strategi roll-forward daripada mengubah yang sudah ada). Dengan demikian, riwayat migrasi tetap konsisten dan mudah di-trace kapan perubahan tertentu diperkenalkan.

Versioned migration umumnya dipakai untuk perubahan yang incremental, misalnya: membuat/ mengubah/ menghapus tabel, menambah kolom baru, membuat index, mengubah data referensi, atau koreksi data spesifik. Intinya, semua perubahan yang ingin kita terapkan sekali saja dan versi selanjutnya akan bertumpu di atas perubahan tersebut, sebaiknya diformat sebagai versioned migration.

Alur Eksekusi File Versi (V__*) oleh Flyway

Sekarang kita bahas bagaimana Flyway mengeksekusi file-file migrasi berprefix V tersebut. Berikut adalah alur umum setiap kali kita menjalankan perintah migrasi Flyway (misal dengan menjalankan Flyway.migrate() di kode Java atau perintah flyway migrate di CLI):

Scanning/Pencarian Skrip: Flyway akan mencari semua file migrasi di lokasi yang sudah dikonfigurasi. Secara default, Flyway mencari di folder filesystem:src/main/resources/db/migration (jika menggunakan integrasi Spring Boot, cukup letakkan file di resources/db/migration). Flyway memuat semua file yang nama depannya sesuai konvensi (misal dia akan pilih semua file yang diawali V untuk versioned dan R untuk repeatable sesuai aturan nama).
Membandingkan dengan History: Setelah daftar file migrasi didapat, Flyway akan membaca tabel histori migrasi di database (nanti kita bahas detail tabel ini). Dari situ, Flyway tahu versi terakhir yang sudah diterapkan di database serta daftar semua migrasi (beserta checksum-nya) yang pernah dijalankan. File migrasi yang belum ada catatannya di history berarti dianggap pending (belum pernah dijalankan). Sebagai contoh, jika di history terakhir adalah versi 5, maka file V6__...sql ke atas akan dianggap pending. Flyway juga akan mendeteksi kalau ada file baru dengan versi lebih rendah dari versi terakhir (misal mendadak ada V4__...sql padahal DB sudah versi 5) – kasus seperti ini umumnya dianggap error karena versinya out-of-order.
Menjalankan Migrasi Pending: Flyway kemudian mengeksekusi semua versioned migration yang pending tersebut secara berurutan menurut urutan versinya. Eksekusi ini biasanya dilakukan dalam transaksi. Misalnya, pertama dijalankan skrip V6__...sql, selesai sukses, lanjut V7__...sql, dan seterusnya. Jika ada satu skrip gagal di tengah jalan (contoh: perintah SQL di dalamnya error), Flyway akan menghentikan proses migrasi dan (jika database mendukung) melakukan rollback transaksi migrasi yang gagal tersebut, sehingga database tidak setengah-setengah ke-update. Kita harus memperbaiki error tersebut dahulu sebelum menjalankan migrate lagi.
Mencatat Hasil ke Tabel History: Setiap kali satu file migrasi berhasil dijalankan, Flyway akan menyisipkan sebuah record ke tabel histori migrasi di database. Record ini mencatat versi berapa yang dijalankan, nama file apa, checksum file, waktu eksekusi, siapa yang menjalankan, durasi, dan status sukses. Dengan pencatatan ini, Flyway mengingat bahwa versi tersebut sudah ter-install. Jika nanti kita menjalankan migrasi lagi, versi ini tidak akan dieksekusi ulang (kecuali dihapus dari tabel history secara manual atau dilakukan repair khusus).
Repeatable Migrations (Opsional): Setelah semua migrasi versi (V) yang pending selesai, Flyway akan melanjutkan menjalankan repeatable migrations (file R__...sql) jika ada. Repeatable migration yang dijalankan hanyalah yang belum pernah dicatat di history atau yang isi file-nya berubah (checksum-nya berbeda dari catatan sebelumnya). Semua repeatable migration dijalankan paling akhir dalam satu batch migrasi, urut berdasarkan nama/deskripsi file (secara alfabetis). (Kita akan bahas repeatable migration sebentar lagi di bagian berikutnya.)
Selesai: Pada titik ini, Flyway telah menerapkan semua perubahan yang diperlukan. Database kini berada di versi terbaru sesuai skrip-skrip migrasi yang ada. Jika kita tambahkan skrip migrasi baru di kemudian hari, proses di atas akan berulang: Flyway akan mendeteksi ada versi baru yang pending, lalu menjalankannya.

Langkah-langkah di atas terjadi di balik layar setiap kali kita melakukan migrasi. Sebagai pengguna, kita biasanya cukup menulis skrip SQL migrasi sesuai aturan penamaan, menaruhnya di folder yang tepat, lalu memicu Flyway (baik dengan menjalankan aplikasi Java, melalui Maven/Gradle plugin, atau perintah CLI). Flyway yang akan mengurus sisanya secara otomatis.

Flyway Schema History: Menyimpan Riwayat Migrasi di Database

Untuk melacak migrasi apa saja yang sudah dijalankan, Flyway menggunakan sebuah tabel khusus di database. Secara default nama tabelnya adalah flyway_schema_history (dulunya pada Flyway versi lama disebut schema_version). Tabel ini akan otomatis dibuat di schema database yang kita migrasi ketika Flyway pertama kali menjalankan migrasi ke database tersebut.

Gambar di atas menunjukkan contoh isi tabel history setelah menjalankan dua migrasi versioned (versi 1 dan 2). Terlihat ada beberapa kolom penting: installed_rank (nomor urut instalasi migrasi), version (versi migrasi yang dijalankan), description (deskripsi migrasi sesuai nama file), type (tipe migrasi, misal SQL), script (nama file skrip migrasi yang dijalankan), checksum (angka hash untuk mendeteksi perubahan file), installed_by (user yang menjalankan migrasi, di sini user DB postgres), installed_on (timestamp kapan migrasi dijalankan), execution_time (waktu eksekusi dalam milidetik), dan success (status berhasil atau tidaknya migrasi tersebut).

Setiap kali Flyway menjalankan migrasi baru, ia akan menambahkan baris baru ke tabel ini. Dengan adanya flyway_schema_history, Flyway dapat mengetahui versi terakhir dari database serta memastikan skrip yang sama tidak dijalankan dua kali. Misalnya, jika kita sudah punya entri untuk version = 2 di tabel history, lalu kita jalankan Flyway lagi, ia tahu versi 2 sudah ada dan tidak perlu menjalankan ulang V2__...sql. Selain itu, Flyway juga menyimpan checksum dari file pada saat migrasi dijalankan. Jika file migrasi diubah setelah penerapan, checksum-nya akan berbeda dengan catatan di history dan Flyway akan menganggap itu masalah (terdeteksi sebagai perubahan tak diinginkan). Hal ini berguna untuk mencegah seseorang mengedit migrasi yang sudah berjalan di production secara diam-diam – integritas migrasi terjaga.

Catatan: Jika kita terpaksa mengubah skrip migrasi yang sudah telanjur berjalan (misal ada koreksi minor di lingkungan development), Flyway menyediakan perintah repair untuk menyesuaikan kembali catatan di tabel history (misalnya memperbarui checksum). Namun, hal ini sebaiknya dihindari di environment production; lebih baik buat migrasi baru untuk perubahan apapun daripada mengedit sejarah.

Perbedaan Versioned vs. Repeatable Migrations

Terakhir, mari bahas singkat perbedaan antara versioned dan repeatable migrations di Flyway. Sejauh ini kita fokus di migrasi berversi (V__). Flyway juga mendukung migrasi repeatable (R__). Berikut perbedaan utamanya:

Versioned Migration (V): Memiliki nomor versi unik di nama filenya. Migrasi ini dijalankan sekali saja per database. Setelah dijalankan, dianggap final dan tidak akan dijalankan lagi di run berikutnya (Flyway tahu sudah done lewat tabel history). Jika ada perubahan skema baru, kita membuat file migrasi versioned baru dengan versi berikutnya. Versioned migration digunakan untuk perubahan yang sifatnya increment (naik versi terus-menerus).
Repeatable Migration (R): Tidak memiliki nomor versi, hanya prefix R dan deskripsi. Migrasi ini bisa dijalankan berulang kali apabila ada perubahan isinya. Flyway menentukan perlu tidaknya menjalankan repeatable migration dengan cara memeriksa checksum: setiap kali perintah migrate dijalankan, Flyway akan menjalankan ulang file R__...sql jika dan hanya jika checksum file tersebut berubah dibanding catatan terakhir di history, atau jika file tersebut belum pernah dijalankan sebelumnya. Repeatable migration selalu dijalankan setelah semua versioned migration selesai dalam satu batch migrasi, dan jika ada beberapa repeatable, urutannya berdasarkan alfabet (berdasarkan nama/deskripsi file). Jenis migrasi ini berguna untuk hal-hal yang mungkin perlu diperbarui secara teratur atau di-recreate, misalnya definisi view, stored procedure, function, atau seeding ulang data referensi. Kita bisa menulis script repeatable misalnya R__Refresh_all_views.sql yang berisi perintah CREATE OR REPLACE VIEW ... sehingga aman dijalankan berulang kali. Setiap kali file ini berubah (misal view diubah), Flyway akan re-run script ini di semua environment yang menjalankan migrate.

Singkatnya, versioned migration itu seperti langkah versi yang linier dan hanya sekali jalan, sedangkan repeatable migration itu seperti skrip yang bisa dijalankan berulang jika diperlukan. Keduanya dicatat di tabel history (repeatable punya entri version kosong tapi ada checksum). Dalam praktiknya, sebagian besar migrasi schema akan kita tulis sebagai versioned migration. Repeatable migration dipakai saat diperlukan saja.

(Contoh situasi penggunaan repeatable: Kita punya beberapa SQL untuk membuat laporan (view) yang kompleks. Daripada membuat version baru tiap kali view diubah, kita bisa simpan sebagai R__ script. Setiap ada perubahan, cukup ubah file itu, lalu Flyway akan mendeteksi perubahan dan menerapkannya.)

Demikianlah pembahasan kita di Episode 2 tentang cara kerja Flyway, versioned migrations, alur eksekusi migrasi oleh Flyway, penyimpanan histori migrasi, dan perbedaan versioned vs repeatable migration. Semoga penjelasannya mudah dimengerti. Dengan pemahaman ini, kita jadi tahu apa yang terjadi di balik layar saat Flyway melakukan migrasi database. Di episode berikutnya, kemungkinan kita akan coba contoh implementasi Flyway dalam proyek Java dengan PostgreSQL, jadi pastikan untuk tetap mengikuti seri ini. Terima kasih sudah menyimak, dan sampai jumpa!

Belajar Flyway Episode 1: Pengenalan dan Migrasi Pertama

Arief Pasa Ibrahim — Sun, 13 Apr 2025 14:49:46 +0000

Pendahuluan

Halo teman-teman! Selamat datang di seri Belajar Flyway. 🎉 Di episode pertama ini, kita akan berkenalan dengan Flyway, sebuah tool untuk mengelola migrasi database, dan langsung mencoba membuat migrasi pertama kita. Sebagai contoh, kita akan menggunakan PostgreSQL sebagai database-nya.

Sebagai developer, kamu pasti pernah menghadapi situasi di mana perlu mengubah struktur database seiring perkembangan aplikasi. Misalnya menambahkan kolom baru, membuat tabel tambahan, atau mengubah tipe data kolom. Kalau perubahan skema database ini dilakukan manual, bisa jadi sumber error dan kebingungan. Bayangkan kalau ada beberapa environment (development, testing, production) atau tim yang berbeda; memastikan semua database punya skema yang sama itu rumit. Nah, di sinilah Flyway bisa membantu kita mengelola perubahan-perubahan itu dengan rapi dan otomatis.

Apa itu Flyway?

Flyway adalah open-source database migration tool yang berfungsi layaknya version control untuk skema database. Dengan Flyway, setiap perubahan pada struktur database kita simpan dalam file SQL terpisah yang diberi nomor versi. Ketika dijalankan, Flyway akan membaca urutan file-file migrasi tersebut dan menerapkannya ke database secara berurutan. Idenya mirip seperti Git untuk kode, tapi ini untuk database: jadi kita bisa melacak perubahan skema dari waktu ke waktu.

Beberapa hal keren tentang Flyway:

Mudah digunakan: Kita cukup menulis skrip SQL untuk perubahan (misalnya CREATE TABLE atau ALTER TABLE), lalu Flyway yang akan menjalankan skrip tersebut ke database. Tidak perlu nulis kode Java/Python khusus untuk migrasi (meskipun Flyway mendukung migrasi berbasis code juga, tapi yang umum ya pakai SQL biasa).
Versioning: Setiap skrip migrasi dikasih versi (misal V1, V2, dst). Flyway memastikan migrasi dijalankan sesuai urutan versinya. Ia juga mencegah skrip yang sama dijalankan dua kali di database yang sama.
Konsisten di berbagai environment: Mau di laptop developer, server staging, atau production, skema database bisa dibuat konsisten cukup dengan menjalankan migrasi via Flyway. Jadi "apa yang sudah di-dev akan sama dengan yang di-prod" selama semua pakai migrasi yang sama.
Mendukung banyak database: Flyway bisa dipakai dengan PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, bahkan SQLite dan database lainnya. Jadi skill yang kita pelajari di sini bisa diterapkan ke DB lain juga.
Mudah diintegrasikan: Flyway CLI bisa dijalankan via command line, dan juga ada plugin untuk Maven/Gradle, bahkan integrasi di Spring Boot otomatis. Di episode ini kita fokus dulu ke penggunaan via CLI biar konsep dasarnya jelas.

Intinya, Flyway membantu kita mengelola perubahan database secara terstruktur, otomatis, dan aman. Daripada ingat-ingat "udah bikin tabel X belum ya di server si A?", kita tinggal cek catatan migrasi Flyway. 👍

Alur Kerja Dasar Flyway

Gambar ilustrasi: Alur kerja dasar Flyway.

Pada ilustrasi di atas, kita bisa melihat alur sederhana cara Flyway bekerja. Developer menyimpan file-file SQL migrasi di folder khusus (misalnya folder migrations di proyek). Kemudian saat dijalankan, Flyway CLI akan membaca file-file tersebut dan menerapkan perubahan skema yang tertulis ke database target. Setiap kali sebuah migrasi diterapkan, Flyway akan menambahkan entri ke tabel history di database. Dengan mekanisme ini, Flyway selalu tahu migrasi mana saja yang sudah atau belum dijalankan pada suatu database, mirip seperti catatan versi. Hasilnya, kondisi skema database dapat dijaga konsisten di berbagai environment secara otomatis dan terkontrol.

Manfaat utama menggunakan Flyway antara lain:

Versi Terpusat: Perubahan skema tersimpan dalam skrip versi yang terorganisir. Tidak ada lagi skrip SQL tercecer di chat atau email.
Konsistensi Antar Environment: Setiap environment bisa dijaga agar memiliki struktur database yang sama. Flyway memastikan migrasi diterapkan urut sesuai versi di dev, test, hingga production.
Otomatis & Mudah Dilacak: Cukup jalankan satu perintah untuk apply semua perubahan yang belum ada. Riwayat migrasi terekam, sehingga mudah dilihat dengan perintah info. Ini memberikan kepercayaan diri untuk deploy DB changes.
Kolaborasi Tim: Mirip Git, tim bisa bekerja paralel mengedit database lewat migrasi. Konflik terdeteksi jika dua orang buat versi sama, dan bisa diselesaikan dengan menaikkan versi salah satu. Semua anggota tim dapat melihat daftar perubahan yang dilakukan rekan mereka (melalui repository kode migrasi).
Dukungan Banyak Database: Flyway mendukung hampir semua database relasional populer: dari MySQL, PostgreSQL, Oracle, SQL Server, hingga database embedded seperti H2 dan SQLite. Jadi kemungkinan besar apapun database yang kamu pakai, Flyway sudah kompatibel.

Dengan sederet manfaat di atas, Flyway menjadi salah satu tool migration paling populer saat ini. Prinsipnya sederhana tapi powerful: reliable schema evolution – evolusi skema yang andal dan otomatis di semua environment kita.

Contoh Kasus

Biar lebih kebayang, mari kita ambil contoh kasus sederhana. Misalkan kita ingin membuat aplikasi To-Do List. Pada versi pertama aplikasi, kita mau menyimpan daftar tugas (tasks) dalam database. Kebutuhannya sederhana: kita butuh sebuah tabel tasks dengan kolom-kolom dasar seperti id dan title (judul tugas). Mungkin juga kolom completed untuk menandai apakah tugas sudah selesai atau belum.

Awalnya, tanpa tool migrasi, mungkin kita akan langsung buat database dan jalankan perintah SQL CREATE TABLE tasks ... secara manual. Oke, anggaplah di laptop kita sudah dibuat tabelnya. Lalu proyek berjalan, kamu menambahkan fitur baru yang butuh perubahan skema, misalnya kolom due_date (tenggat waktu) di tabel tasks atau membuat tabel baru untuk menyimpan kategori tugas. Kamu pun menjalankan ALTER TABLE atau CREATE TABLE baru di lokal.

Masalah mulai muncul ketika tim lain atau environment lain butuh perubahan yang sama. Misal, si Budi yang kerja bareng kamu perlu database yang up-to-date dengan perubahan terbaru. Atau ketika mau deploy ke server, ternyata struktur database di server masih yang lama karena lupa menjalankan script SQL perubahan tadi. Akibatnya? Aplikasi error karena tabel/kolom yang dibutuhkan nggak ada di database server. 😵‍💫

Dengan Flyway, alur kerja jadi lebih rapi. Setiap kali ada perubahan skema, kita buat file migrasi baru. File ini (berupa SQL) disimpan di repository proyek (bersama kode aplikasi). Ketika tim lain menarik kode terbaru, mereka cukup menjalankan Flyway migrate, dan Flyway akan otomatis mendeteksi migrasi mana yang belum ada di database mereka, lalu menjalankannya. Begitu pula saat deploy ke server: cukup jalankan migrasi, semua perubahan terapkan urut. Tidak ada lagi cerita "eh tabel X di DB staging belom dibuat ya?" karena semua tercatat.

Jadi, Flyway sangat membantu untuk menjaga sinkronisasi skema DB antara developer satu dengan yang lain, maupun antara environment. Kita akan langsung coba praktik membuat migrasi pertama untuk kasus To-Do List tadi: membuat tabel tasks di PostgreSQL.

Instalasi Flyway

Sebelum membuat migrasi, kita perlu menyiapkan Flyway dan database PostgreSQL-nya. Berikut langkah-langkahnya:

Install Flyway CLI: Download Flyway Community edition dari situs resmi Flyway (flywaydb.org). Flyway tersedia untuk Windows, Mac, dan Linux. Untuk Windows, kalian akan mendapat zip berisi flyway.cmd; untuk Mac/Linux ada script flyway. Silakan ekstrak file zip tersebut ke folder pilihanmu (misal: C:\tools\flyway atau ~/flyway). Setelah ekstrak, di dalam folder Flyway seharusnya ada struktur seperti: folder conf, drivers, sql, dan file executable flyway. Agar gampang dipanggil, tambahkan folder tersebut ke PATH, atau pindah direktori ke situ saat mau menjalankan perintah.
- Petunjuk dan langkah untuk instalasi pada Linux (Ubuntu):
```
# Ekstrak file yang diunduh dari website resmi.
sudo tar -xzf ~/Downloads/FlywayDesktopLinuxX64_7.8.7.0.tar.gz

# Pindahkan folder hasil ekstaksi ke folder opt
sudo cp ~/Downloads/flyway /opt

# Buat symlink untuk memudahkan penggunaan di terminal
sudo ln -s /opt/flyway/flyway /usr/local/bin/flyway

# Beri akses dan izin untuk flyway
sudo chmod +x /opt/flyway/flyway

# Cek apakah instalasi berhasil
flyway -v
```
  Contoh hasil dari perintah flyway -v:
Siapkan database PostgreSQL: Pastikan kalian punya akses ke server PostgreSQL. Kamu bisa pakai PostgreSQL yang terinstall lokal di komputer, atau paling gampang gunakan Docker untuk menjalankan Postgres sementara. Misalnya, kalau pakai Docker bisa dengan perintah:
```
# Buat container untuk postgresql
docker run -d --name postgres-belajar-flyway -p 5432:5432 \
    -e POSTGRES_PASSWORD=postgres \
    -e POSTGRES_DB=belajar_flyway \
    postgres:16
```
Perintah di atas akan menjalankan container PostgreSQL latest di port 5432, dengan password user postgres diset ke "postgres", dan otomatis membuat database baru bernama belajar_flyway. Optional: Jika kamu sudah punya Postgres terinstall, kamu bisa bikin database baru manual (misal via createdb belajar_flyway atau pakai tool GUI) untuk percobaan ini. Tujuannya hanya agar kita punya database kosong tempat menjalankan migrasi, terpisah dari database lain.
Konfigurasi koneksi Flyway: Sekarang, beri tahu Flyway bagaimana menghubungkan ke database PostgreSQL tersebut. Buka file konfigurasi Flyway flyway.conf yang ada di dalam folder conf (bisa dibuka dengan text editor). Di dalamnya, cari dan edit bagian berikut:
```
flyway.url=jdbc:postgresql://localhost:5432/belajar_flyway
flyway.user=postgres
flyway.password=postgres
flyway.defaultSchema=flyway #skema yang digunakan flyway untuk track perubahan
flyway.createSchemas=true
flyway.locations=filesystem:/opt/flyway/sql #buat folder ini jika belum ada
```
Penjelasan:
- flyway.url: URL JDBC untuk konek ke database. Sesuaikan nama host/port/database dengan environment kamu. Contoh di atas mengasumsikan Postgres jalan di lokal (localhost) port default 5432, dan nama database-nya belajar_flyway.
- flyway.user dan flyway.password: kredensial login ke database. Contoh di atas pakai user default postgres dan password postgres (sesuai yang kita set di langkah Docker tadi). Ubah jika kamu pakai user atau password lain.
- flyway.locations: lokasi folder tempat menyimpan file-file migrasi. Secara default, Flyway pakai folder filesystem:sql, yang artinya folder sql di dalam direktori Flyway. Kita bisa pakai default ini untuk mempermudah (nanti kita simpan file migrasi di folder sql tersebut).
Simpan perubahan di file config. Sekarang Flyway siap terhubung ke database Postgres kita. Catatan: Menyimpan password DB di file konfigurasi kadang kurang aman. Alternatifnya, kamu bisa menghapus baris password dari config dan sebagai gantinya ekspor ENV FLYWAY_PASSWORD saat mau menjalankan (atau gunakan parameter -password= di CLI). Tapi untuk simplicity dalam belajar, kita taruh saja di file config lokal (jangan commit file ini ke repo publik ya, kalau ada password asli 😁).

Sampai langkah ini, kita sudah menginstall Flyway dan mengkonfigurasi koneksi ke PostgreSQL. Waktunya membuat migrasi pertama!

Migrasi Pertama

Sekarang kita akan membuat migrasi pertama: membuat tabel tasks di database. Ini sesuai contoh kasus To-Do List kita. Berikut langkah-langkahnya:

Buat file migrasi pertama: Masuk ke folder sql di direktori Flyway, lalu buat file baru untuk migrasi. Flyway memakai konvensi penamaan file migrasi dengan awalan V diikuti nomor versi, dua underscore __, lalu nama deskriptif. Karena ini migrasi pertama kita, beri nama filenya: V1__create_tasks_table.sql. (Gunakan underscore untuk spasi di nama file, dan hindari karakter aneh supaya Flyway bisa baca dengan benar.)

Isi file V1__create_tasks_table.sql dengan perintah SQL untuk membuat tabel tasks. Misalnya seperti ini:
```
CREATE TABLE tasks (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    completed BOOLEAN NOT NULL DEFAULT FALSE
);
```
Kita membuat tabel tasks dengan kolom:
- id – sebagai primary key, tipe SERIAL (integer auto-increment di Postgres).
- title – judul tugas, tipe VARCHAR(255) dan tidak boleh null (wajib diisi).
- completed – status apakah tugas sudah selesai, tipe BOOLEAN dengan default FALSE (belum selesai).
Silakan simpan file tersebut. Inilah "skrip migrasi" pertama kita, versi V1. Karena baru pertama, isinya hanya create table. Kalau nanti ada perubahan lagi, kita akan buat V2, V3, dan seterusnya di file terpisah.
Jalankan perintah migrasi dengan Flyway: Sekarang saatnya menerapkan perubahan ke database. Buka terminal/command prompt, lalu navigasi ke direktori instalasi Flyway (tempat file flyway berada). Pastikan file config sudah di-edit sesuai langkah sebelumnya. Kemudian jalankan perintah berikut:
```
flyway migrate
```
Perintah di atas akan memerintahkan Flyway untuk menjalankan migrasi. Flyway akan membaca konfigurasi (URL, user, dll), mencari file-file migrasi di folder sql, lalu mengeksekusi migrasi yang belum pernah dijalankan. Karena ini pertama kali, Flyway akan menjalankan file V1__create_tasks_table.sql. Kamu akan melihat output di console yang kira-kira seperti berikut:
```
Flyway Community Edition 9.x.x by Redgate
Database: jdbc:postgresql://localhost:5432/belajar_flyway (PostgreSQL 16)
Successfully validated 1 migration (execution time 00:00.012s)
Creating Schema History table "flyway"."flyway_schema_history" ...
Current version of schema "flyway": << Empty Schema >>
Migrating schema "flyway" to version 1 - Create tasks table
Successfully applied 1 migration to schema "flyway" (execution time 00:00.045s)
```
Penjelasan output di atas:
- Flyway terkoneksi ke database belajar_flyway (PostgreSQL) kita.
- Flyway mem-validasi ada 1 file migrasi yang belum diterapkan.
- Karena pada setting sebelumnya kita sudah menentukan skema mana yang akan digunakan oleh Flyway, maka Flyway akan membuat tabel khusus bernama flyway_schema_history di schema flyway. Tabel ini dipakai Flyway untuk mencatat migrasi apa saja yang sudah dijalankan di database tersebut.
- Sebelumnya schema database kosong (Empty Schema), sekarang Flyway menjalankan migrasi versi 1 dengan deskripsi "Create tasks table".
- Setelah sukses, tertulis Successfully applied 1 migration. Artinya, migrasi V1 kita berhasil diterapkan. 🎉
Jika muncul output serupa tanpa error, selamat! Kamu sudah berhasil melakukan migrasi pertama dengan Flyway. Flyway telah membuat tabel tasks sesuai SQL yang kita tulis, dan mencatatnya di tabel flyway_schema_history.

Tips: Kalau kamu menjalankan flyway migrate lagi sekarang, Flyway tidak akan mengulang migrasi V1 karena versi tersebut sudah ada di catatan flyway_schema_history. Flyway akan mengecek dan memberi tahu bahwa database sudah up-to-date (tidak ada migrasi baru yang perlu dijalankan). Ini penting supaya setiap migrasi hanya dieksekusi sekali saja di satu database.

Verifikasi

Setelah menjalankan migrasi, kita perlu memverifikasi bahwa perubahan memang sudah masuk ke database. Ada beberapa cara untuk mengecek hasil migrasi:

Menggunakan Flyway Info: Flyway menyediakan perintah flyway info yang menampilkan status migrasi di database. Coba jalankan flyway info di terminal. Output-nya akan menampilkan tabel yang berisi daftar migrasi beserta statusnya (Applied/Pending). Kamu seharusnya melihat entry untuk Version 1 - Create tasks table dengan status Success/Installed. Di bagian "Current version of schema" kemungkinan tertera 1 yang menandakan database sekarang di versi migrasi 1. Ini menegaskan bahwa skrip migrasi kita sudah tercatat dan diterapkan.
Cek langsung ke database: Kamu bisa memastikan tabel tasks benar-benar sudah dibuat di PostgreSQL. Jika kamu punya client psql (Postgres CLI) atau GUI database tool (misal PgAdmin, DBeaver, dll), coba konek ke database belajar_flyway dan lihat daftar tabelnya. Contoh pakai psql di terminal:
```
psql -h localhost -U postgres -d belajar_flyway -c "\dt"
```
Perintah di atas akan menampilkan list tabel di schema public. Harusnya sekarang terlihat ada tabel tasks dan tabel flyway_schema_history. Kamu juga bisa cek struktur tabel tasks dengan query \d tasks (kalau di psql) atau dengan perintah SQL SELECT * FROM tasks; (harusnya kosong karena kita baru buat tabelnya). Selain itu, coba lihat isi tabel flyway_schema_history untuk memastikan ada record migrasi V1 di sana: SELECT version, description, success FROM flyway_schema_history; akan menampilkan versi 1, deskripsi "Create tasks table", dan status sukses.

Jika kedua cara di atas menunjukkan migrasi versi 1 sudah terpasang, berarti proses migrasi pertama kita berhasil. 🎊 Sekarang database belajar_flyway memiliki tabel tasks sesuai yang kita inginkan, dan Flyway tahu bahwa migrasi V1 sudah diaplikasikan (sehingga tidak akan mengulangnya).

Sampai di sini, kita telah menyelesaikan migrasi pertama kita menggunakan Flyway dengan PostgreSQL. Dari tidak ada tabel tasks, sekarang tabel tersebut sudah ada berkat satu file migrasi dan satu perintah flyway migrate. Gaya migrasi database seperti ini skalanya bisa berkembang seiring proyek berjalan: setiap ada perubahan baru, tinggal buat file migrasi baru (V2, V3, dst) dan jalankan Flyway lagi. Flyway akan menerapkan perubahan baru tersebut tanpa mengganggu yang sudah-sudah.

Di episode selanjutnya, kita akan melanjutkan petualangan dengan Flyway: Belajar Flyway Episode 2: Cara Kerja Flyway dan Versioned Migrations. Tetap semangat belajar, dan happy coding! 🚀