Manajemen Versi Database Atlas

1. Pengenalan Atlas

Atlas adalah sebuah alat yang independen terhadap bahasa, dirancang khusus untuk mengelola dan memigrasikan skema basis data menggunakan prinsip-prinsip DevOps modern. Atlas menyediakan dua pilihan alur kerja:

• Deklaratif: Mirip dengan Terraform, Atlas membandingkan keadaan saat ini dari basis data dengan keadaan yang diinginkan yang didefinisikan menggunakan HCL, SQL, atau skema ORM. Berdasarkan perbandingan ini, Atlas menghasilkan dan menjalankan rencana migrasi untuk memindahkan basis data ke keadaan yang diinginkan.
• Versi: Berbeda dengan alat lain, Atlas secara otomatis merencanakan migrasi skema untuk Anda. Pengguna dapat mendeskripsikan skema basis data yang diinginkan menggunakan HCL, SQL, atau ORM pilihan mereka, lalu dengan Atlas, merencanakan, meninjau, dan menerapkan migrasi yang diperlukan ke basis data.

Salah satu keunggulan utama Atlas adalah penyederhanaannya terhadap kompleksitas pengelolaan basis data, menjadikannya mudah untuk kontrol versi, kolaborasi, dan implementasi.

2. Memasang Atlas

Sebelum menggunakan Atlas untuk mengelola versi basis data, kita perlu memasangnya. Berikut adalah langkah-langkah pemasangan untuk platform-platform berbeda.

2.1 Pemasangan pada macOS + Linux

Pada sistem macOS atau Linux, Anda dapat mengunduh dan memasang versi terbaru Atlas menggunakan baris perintah berikut:

curl -sSf https://atlasgo.sh | sh

Perintah ini akan secara otomatis mendeteksi versi sistem operasi, mengunduh versi build yang sesuai, dan menempatkan file biner Atlas di jalur eksekusi.

2.2 Memasang melalui Homebrew

Jika Anda menggunakan macOS dan sudah memasang manajer paket Homebrew, memasang Atlas sebegai berikut:

brew install ariga/tap/atlas

Ini akan mengambil versi terbaru Atlas dari repositori Homebrew dan memasangnya.

2.3 Pemasangan melalui Docker

Memasang dan menjalankan Atlas melalui Docker merupakan metode yang cepat dan nyaman, terutama untuk pengujian sementara atau untuk pengguna yang lebih suka tidak memasang perangkat lunak tambahan pada sistem host mereka.

Pertama, unduh gambar Docker Atlas:

docker pull arigaio/atlas

Kemudian, Anda dapat menjalankan perintah bantuan untuk memastikan pemasangan berhasil:

docker run --rm arigaio/atlas --help

Jika kontainer perlu mengakses jaringan host atau direktori lokal, gunakan flag --net=host dan pasang direktori yang diperlukan:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply \
  --url "mysql://root:pass@:3306/test"

2.4 Pemasangan pada Windows

Unduh file biner, https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe, dan tambahkan jalur pemasangan ke variabel lingkungan PATH sistem.

3. Mengekspor Struktur Tabel Database yang Ada Menggunakan Atlas

Atlas menyediakan perintah atlas schema inspect, yang dapat digunakan untuk mengekspor struktur database yang sudah ada. Perintah ini mendukung membaca deskripsi database dari URL database dan mengeluarkannya dalam tiga format berbeda: format Atlas HCL default, format SQL, dan format JSON. Dalam panduan ini, kami akan menunjukkan bagaimana menggunakan format Atlas HCL dan SQL, karena format JSON biasanya digunakan untuk memproses output dengan jq.

Untuk memeriksa instansi MySQL yang berjalan secara lokal dan menulis output ke file yang bernama schema.hcl, gunakan perintah berikut:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl

Buka file schema.hcl untuk melihat definisi struktur tabel Atlas yang menggambarkan database (HCL adalah format konfigurasi struktur tabel yang tidak tergantung pada database yang didefinisikan oleh Atlas). Sebagai contoh, file ini akan berisi konten berikut:

table "users" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "name" {
    null = true
    type = varchar(100)
  }
  primary_key {
    columns = [column.id]
  }
}

Kode ini mewakili struktur tabel dengan kolom id dan name. Bidang schema merujuk pada definisi model example yang ditentukan di bagian lain dalam dokumen ini. Selain itu, sub-blok primary_key menentukan kolom id sebagai kunci utama untuk tabel tersebut. Atlas berusaha meniru sintaks dari database yang sedang dioperasikan. Dalam contoh ini, kolom id memiliki tipe int, sementara kolom name memiliki tipe varchar(100).

Demikian pula, untuk mengekspor definisi model SQL dari database, Anda dapat menggunakan perintah berikut:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" --format '{{ sql . }}' > schema.sql

Buka file schema.sql untuk melihat deskripsi SQL dari database, yang biasanya berisi beberapa pernyataan CREATE TABLE.

Pendekatan ini memudahkan untuk memahami detail struktur tabel database yang sudah ada dan memberikan referensi yang akurat untuk migrasi berbasis versi selanjutnya.

4.1 Declarative Workflow

Declarative Workflow Atlas memungkinkan pengguna secara deklaratif menentukan keadaan akhir yang diinginkan dari database. Pengguna hanya perlu mendeskripsikan keadaan akhir skema database yang mereka inginkan, dan alat Atlas akan secara otomatis membuat dan menjalankan rencana migrasi untuk dengan aman beralih dari keadaan saat ini ke keadaan yang diharapkan ini.

Berikut adalah cara menggunakan Declarative Workflow untuk menentukan dan mencapai keadaan database yang diinginkan:

4.1.1 Mendefinisikan Struktur Tabel Target

Pertama, Anda perlu membuat file yang mendefinisikan struktur database yang diharapkan, yang dapat berupa format HCL, SQL, atau ORM (Object-Relational Mapping).

Mengambil format HCL sebagai contoh, tentukan tabel blog_posts baru:

table "blog_posts" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "title" {
    null = true
    type = varchar(100)
  }
  column "body" {
    null = true
    type = text
  }
  column "author_id" {
    null = true
    type = int
  }
  primary_key {
    columns = [column.id]
  }
  foreign_key "author_fk" {
    columns     = [column.author_id]
    ref_columns = [table.users.column.id]
  }
}

Tip: Format sintaks HCL akan dibahas dalam bagian selanjutnya.

4.1.2 Melakukan Migrasi Menggunakan Alat Atlas

Setelah definisi struktur tabel database selesai, Anda dapat menggunakan perintah schema apply dari Atlas untuk melakukan migrasi.

atlas schema apply \
  -u "mysql://root:pass@localhost:3306/example" \
  --to file://schema.hcl

Setelah menjalankan perintah di atas, Atlas akan membandingkan skema database yang sudah ada dengan skema yang didefinisikan di file, membuat rencana migrasi, dan meminta pengguna untuk konfirmasi untuk menjalankan. Setelah pengguna mengonfirmasi rencana eksekusi, Atlas akan melakukan migrasi pada database dan memperbarui ke keadaan yang diinginkan.

4.2 Versioned Workflow

Fluktuasi versi adalah mode penggunaan lain yang didukung oleh Atlas, kadang-kadang disebut sebagai "migrasi berbasis perubahan". Ini cocok untuk skenario di mana perubahan skema database perlu dikontrol versi dan ditinjau dalam proses peninjauan kode.

Langkah-langkah dari fluktuasi versi meliputi:

4.2.1 Hitung Perbedaan

Sebelum memulai migrasi, diperlukan untuk membandingkan struktur basis data saat ini dengan kondisi yang diinginkan dan menentukan perbedaan di antara keduanya. Hal ini dapat dilakukan dengan menjalankan perintah atlas migrate diff.

atlas migrate diff create_blog_posts \
  --dir "file://migrations" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/example"

Opsi --dir menentukan URL dari folder migrasi, defaultnya adalah file://migrations. Opsi --to menentukan URL dari kondisi yang diinginkan (misalnya, basis data lingkungan pengembangan Anda), dan --dev-url menyediakan URL untuk basis data pengembangan yang digunakan untuk menghitung perbedaan (perhatikan bahwa --dev-url ini perlu menentukan basis data kosong yang digunakan Atlas untuk menghitung perbedaan).

Tips: Jika Anda ingin membuat file SQL, lihat bagian sebelumnya untuk mengatur format menggunakan parameter --format.

4.2.2 Terapkan Perubahan Migrasi

Setelah perhitungan perbedaan selesai, Atlas akan menghasilkan dua file migrasi yang disimpan di folder migrations. Misalnya, jika format yang dipilih adalah SQL, file yang dihasilkan oleh perintah diff, seperti SQL file berikut, berisi perintah migrasi untuk membuat tabel baru:

-- create tabel "blog_posts"
CREATE TABLE `blog_posts` (
  `id` int NOT NULL,
  `title` varchar(100) DEFAULT NULL,
  `body` text DEFAULT NULL,
  `author_id` int NULL REFERENCES `users`(id),
  PRIMARY KEY (`id`)
);

Setelah file migrasi dihasilkan, Anda dapat menggunakan alat kontrol versi (misalnya, Git) untuk mengelola perubahan ini. Pendekatan ini memungkinkan untuk melakukan modifikasi struktur tabel basis data yang banyak di lingkungan pengembangan, dan saat waktunya untuk rilis, membandingkan lingkungan pengembangan dan lingkungan UAT menggunakan perintah Atlas untuk menghasilkan file migrasi struktur tabel basis data. File-file migrasi ini kemudian dapat diterapkan di lingkungan UAT dan produksi untuk melakukan upgrade basis data.

Kedua alur kerja ini, Deklaratif dan Versi, memberikan fleksibilitas bagi berbagai mode pengembangan dan implementasi, memungkinkan tim untuk memilih metode yang paling sesuai dengan kebutuhan proyek mereka untuk mengelola perubahan skema basis data.

5. Deskripsi Format HCL

5.1 Pengantar

HCL adalah bahasa deklaratif yang digunakan untuk menggambarkan definisi struktur tabel basis data. Atlas menggunakan format HCL untuk menulis skema basis data, menyediakan struktur yang kaya untuk menggambarkan berbagai aspek basis data. Keunggulan HCL terletak pada kemampuannya yang mudah dibaca, mudah dipelihara, dan mendukung fitur-fitur seperti penyisipan variabel dan anotasi tambahan.

Tips: Jika proyek Anda perlu beradaptasi dengan berbagai basis data, menggambarkan struktur tabel dengan cara yang tidak bergantung pada basis data menggunakan HCL bisa sangat nyaman.

5.2 Objek schema

Objek schema digunakan untuk menggambarkan skema basis data. Di MySQL dan SQLite, itu mewakili DATABASE, sementara di PostgreSQL, itu mewakili SCHEMA. Sebuah file HCL dapat berisi satu atau lebih objek schema.

schema "public" {
  comment = "Sebuah komentar skema"
}

schema "private" {}

5.3 Objek table

Objek table digunakan untuk menggambarkan sebuah tabel di basis data SQL, termasuk kolom, indeks, constraint, dan berbagai properti tambahan yang didukung oleh driver basis data yang berbeda.

table "users" {
  schema = schema.public
  column "id" {
    type = int
  }
  column "name" {
    type = varchar(255)
  }
  column "manager_id" {
    type = int
  }
  primary_key {
    columns = [
      column.id
    ]
  }
  index "idx_name" {
    columns = [
      column.name
    ]
    unique = true
  }
  foreign_key "manager_fk" {
    columns     = [column.manager_id]
    ref_columns = [table.users.column.id]
    on_delete   = CASCADE
    on_update   = NO_ACTION
  }
}

5.4 Objek column

Objek column adalah sub-sumber daya dari table yang digunakan untuk mendefinisikan kolom-kolom dalam tabel.

column "name" {
  type = text
  null = false
}

column "age" {
  type = integer
  default = 42
}

column "active" {
  type = tinyint(1)
  default = true
}

5.5 Objek primary_key

Objek primary_key adalah sub-sumber daya dari table yang mendefinisikan kunci utama dari tabel.

primary_key {
  columns = [column.id]
}

5.6 Objek foreign_key

Objek foreign_key adalah sub-sumber daya dari table yang mendefinisikan kolom-kolom yang merujuk ke kolom di tabel lain.

table "orders" {
  schema = schema.market
  // ...
  column "owner_id" {
    type = integer
  }
  foreign_key "owner_id" {
    columns     = [column.owner_id]
    ref_columns = [table.users.column.id]
    on_update   = NO_ACTION
    on_delete   = NO_ACTION
  }
}

5.7 Objek index

Objek index mewakili indeks pada tabel.

index "idx_name" {
  columns = [
    column.name
  ]
  unique = true
}