Skip to main content

Mengatasi AR::UUID::MissingExtensionError saat db:migrate (PostgreSQL + Rails)

Penulis

Anggit Wirasto, S.Si., M.Eng.

Saat menjalankan migrasi produksi, Anda bisa menemui pesan seperti berikut:

bin/rails aborted!
AR::UUID::MissingExtensionError: Use either `enable_extension "uuid-ossp"` or
`enable_extension "pgcrypto"` (AR::UUID::MissingExtensionError)
.../db/cable_schema.rb:2:in 'block in <main>'
Tasks: TOP => db:migrate

Artinya ActiveRecord mengharapkan salah satu ekstensi PostgreSQL untuk pembuatan UUID di level basis data, tetapi ekstensi itu belum diaktifkan pada basis data yang dipakai aplikasi (sering muncul lewat db/cable_schema.rb bila skema Action Cable / Solid Cable memakai kolom UUID).

Peringatan Bundler tentang platform :mingw / :mswin tidak memicu kegagalan migrasi; fokus perbaikan ada di PostgreSQL dan ekstensi.

Penyebab singkat

PostgreSQL menyediakan UUID lewat modul:

  • uuid-ossp — fungsi klasik seperti uuid_generate_v4().
  • pgcrypto — antara lain gen_random_uuid() (umum dipakai Rails/AR versi baru).

Tanpa salah satunya, definisi skema yang memakai tipe UUID tidak dapat diterapkan dengan aman.

Solusi 1: Aktifkan ekstensi langsung di PostgreSQL (paling cepat di VPS)

Anda harus masuk ke konsol basis data yang sama dengan yang dipakai RAILS_ENV=production (lihat config/database.yml / DATABASE_URL). Dua cara umum:

A. psql sebagai superuser PostgreSQL

Masuk sebagai superuser (biasanya postgres) ke basis data aplikasi:

sudo -u postgres psql -d NAMA_DATABASE_APLIKASI

B. Konsol lewat Rails (dbconsole)

Dari direktori root aplikasi, Rails akan membuka psql ke basis data produksi sesuai konfigurasi (sesuaikan user / nama DB di database.yml bila perlu):

RAILS_ENV=production rails dbconsole

Di prompt psql (baik dari A maupun B), jalankan:

CREATE EXTENSION IF NOT EXISTS "pgcrypto";
-- alternatif jika kebijakan Anda mengutamakan uuid-ossp:
-- CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
\q

Lalu ulangi migrasi dari direktori aplikasi:

RAILS_ENV=production rails db:migrate

Pastikan basis data yang Anda buka (lewat A atau B) sama dengan yang dipakai primary migrasi (dan, bila terpisah, basis data untuk cable jika koneksinya beda — aktifkan ekstensi di setiap basis data yang akan menjalankan skema ber-UUID).

Hak akses: CREATE EXTENSION biasanya butuh peran superuser atau izin setara. Jika rails dbconsole memakai user aplikasi biasa dan muncul permission denied, gunakan cara A (postgres / administrator) atau minta DBA menjalankan CREATE EXTENSION sekali.

Solusi 2: Migrasi Rails enable_extension (disiplin jangka panjang)

Tambahkan migrasi awal (atau pastikan migrasi itu dijalankan sebelum skema cable / tabel UUID lain):

class EnableUuidExtension < ActiveRecord::Migration[7.2]
  def change
    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
    # atau: enable_extension "uuid-ossp" unless extension_enabled?("uuid-ossp")
  end
end

Nomor versi ActiveRecord::Migration[...] samakan dengan versi Rails proyek Anda.

Catatan urutan: jika db:migrate sudah gagal sebelum migrasi ekstensi pernah jalan, seringkali Anda tetap perlu Solusi 1 sekali di server, atau menjalankan migrasi minimal yang hanya mengaktifkan ekstensi lewat psql dulu, baru sisanya.

Paket OS (jika CREATE EXTENSION gagal “could not open extension file”)

Di Debian/Ubuntu, modul biasanya ada di paket postgresql-contrib (nama persis bisa mengikuti versi mayor PostgreSQL, misalnya postgresql-16). Pasang paket yang sesuai versi server Anda, lalu ulangi CREATE EXTENSION.

Hak akses dan hosting terkelola

  • Hanya peran dengan hak cukup (sering superuser atau pemilik basis data) yang boleh CREATE EXTENSION.
  • Di layanan DB terkelola (RDS, Cloud SQL, dsb.), ekstensi sering harus diizinkan di konsol atau oleh administrator; ikuti dokumentasi penyedia.

Ringkas

  1. Identifikasi basis data yang dipakai saat RAILS_ENV=production rails db:migrate.
  2. Aktifkan pgcrypto atau uuid-ossp di basis data itu (CREATE EXTENSION lewat psql / rails dbconsole, atau migrasi enable_extension).
  3. Jalankan ulang db:migrate.

Setelah ekstensi ada, error AR::UUID::MissingExtensionError dari cable_schema.rb biasanya hilang.