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.*

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:

  1. 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:

      Hasil dari flyway -v

  2. 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.

  3. 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:

  1. 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.

  2. 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! 🚀