logo

quickActions

Fitur

Sumber Daya

Komunitas

Harga

Migrasi dari Supabase ke Insforge: Panduan Langkah-demi-Langkah

Toolkit open-source untuk memindahkan seluruh proyek Supabase Anda—pengguna, database, dan file—tanpa kehilangan data.

Kyle ChungKyle Chung

Migrasi dari Supabase ke Insforge dalam Hitungan Menit: Panduan Lengkap yang Teruji di Produksi

Halo! Jika Anda memutuskan untuk memindahkan proyek Anda dari Supabase ke Insforge, panduan ini cocok untuk Anda. Proses migrasi bisa jadi menakutkan. Anda mungkin bertanya-tanya, bagaimana cara memindahkan semua pengguna tanpa memaksa reset kata sandi? Bagaimana cara mentransfer setiap file dan memperbarui semua tautannya? Bagaimana dengan skema basis data dan semua data berharga lainnya?

Jangan khawatir. Kami siap membantu Anda.

Panduan ini memperkenalkan toolkit migrasi lengkap yang telah teruji di lingkungan produksi, dirancang untuk memindahkan seluruh proyek Supabase Anda ke instance Insforge yang di-hosting sendiri dengan lancar. Ini bukan sekadar dump data sebagian; ini adalah migrasi penuh yang menjaga:

  • ✅ Autentikasi Pengguna (termasuk kata sandi!)
  • ✅ Basis Data Lengkap (skema dan data)
  • ✅ Semua File Penyimpanan (dengan path yang sama persis)
  • ✅ Hubungan Foreign Key (dengan mempertahankan ID Pengguna)

Toolkit ini telah teruji dalam lingkungan produksi nyata, berhasil memigrasikan 39 pengguna, 985 baris basis data, dan lebih dari 1.500 file penyimpanan tanpa kehilangan data. Untuk informasi lebih lanjut tentang self-hosting, kunjungi repositori GitHub Insforge.

Mari kita mulai.

Memulai: Daftar Periksa Pra-Migrasi Anda

Sebelum kita mulai, mari siapkan lingkungan Anda untuk migrasi yang lancar.

1. Prasyarat

Pertama, pastikan Anda memiliki alat dan akses yang diperlukan:

  • Perangkat Lunak:
    • Node.js (v20+)
    • Klien PostgreSQL (psql)
  • Akses:
    • Kredensial proyek Supabase Anda (kunci API, URL basis data).
    • Instance Insforge yang aktif dengan kunci API admin.

2. Pengaturan Lingkungan

Sekarang, mari konfigurasikan alat migrasi itu sendiri.

Pertama, clone repositori toolkit (atau unduh source code-nya) dan instal dependensinya.

# Clone repositori (jika ada)
# git clone <https://github.com/InsForge/supabase-to-insforge>

# Instal dependensi
npm install

Selanjutnya, buat file konfigurasi lingkungan Anda. Salin file contoh untuk membuat file .env Anda sendiri.

cp .env.example .env

Sekarang, buka file .env yang baru dibuat dan isi kredensial untuk proyek Supabase yang akan dimigrasikan dan proyek Insforge yang baru.

Menemukan Kredensial Supabase Anda

Untuk mengisi file .env, Anda memerlukan tiga informasi penting dari dasbor proyek Supabase Anda.

  1. SUPABASE_URL & SUPABASE_SERVICE_ROLE_KEY:
    • Buka Proyek Supabase Anda.
    • Masuk ke Project Settings (ikon roda gigi).
    • Klik API.
    • Di sini Anda akan menemukan URL Proyek dan kunci rahasia service_role Anda.
  2. SUPABASE_DB_URL (Connection String Anda):
    • Di dasbor proyek Supabase Anda, klik tombol Connect di bagian atas halaman.
    • Sebuah panel akan terbuka dengan detail koneksi basis data Anda.
    • Salin URI dari bagian Direct connection.
    • Penting: Anda harus mengganti placeholder [YOUR-PASSWORD] di string dengan kata sandi basis data Anda yang sebenarnya. Jika Anda lupa, Anda dapat meresetnya di Project Settings > Database.

PSQL String

# ============================================
# Konfigurasi Supabase
# ============================================
# Temukan kredensial ini di pengaturan Supabase
SUPABASE_URL=https://PROYEK_ANDA.supabase.co
SUPABASE_SERVICE_ROLE_KEY=kunci_service_role_supabase_anda
SUPABASE_DB_URL=postgresql://postgres.xxx:[KATA-SANDI-ANDA]@...

# ============================================
# Konfigurasi Insforge
# ============================================
# Detail instance Insforge Anda
INSFORGE_API_URL=http://localhost:7130 # Atau URL remote Anda
INSFORGE_API_KEY=kunci_api_insforge_anda

3. Verifikasi Koneksi Anda

Sebelum menjalankan migrasi, pastikan alat ini dapat terhubung ke kedua basis data. Jalankan perintah ini untuk menguji koneksi Anda:

# Uji koneksi Supabase
psql "$SUPABASE_DB_URL" -c "SELECT version();"

# Uji koneksi Insforge (sesuaikan dengan pengaturan lokal/remote Anda)
psql postgresql://postgres:postgres@localhost:5432/insforge -c "SELECT version();"

# Keluar
\\q

Jika kedua perintah berjalan tanpa kesalahan, Anda siap untuk tahap utama!

Migrasi Besar: Panduan Langkah-demi-Langkah

Migrasi dibagi menjadi tiga fase logis. Ikuti urutannya untuk hasil terbaik.

Fase 1: Migrasi Pengguna Anda (Tanpa Reset Kata Sandi!)

Ini seringkali menjadi bagian tersulit dari setiap migrasi, tetapi toolkit ini membuatnya sederhana. Kami akan memigrasikan semua akun pengguna sambil mempertahankan kata sandi asli mereka.

Langkah 1.1: Ekspor Pengguna dari Supabase

Perintah ini terhubung ke proyek Supabase Anda dan mengekspor semua pengguna dari tabel auth.users ke file JSON lokal.

npm run export:auth

Output yang Diharapkan:

✅ Terhubung ke Supabase PostgreSQL
✅ Mengekspor 39 pengguna ke auth-export.json

Ini membuat file bernama auth-export.json yang berisi detail pengguna, termasuk ID dan kata sandi terenkripsi mereka.

Langkah 1.2: Impor Pengguna ke Insforge

Sekarang, kita akan mengimpor pengguna dari file auth-export.json ke instance Insforge Anda. Skrip ini mempertahankan ID pengguna asli (penting untuk foreign key) dan kata sandi mereka yang di-hash dengan bcrypt.

npm run import:auth

Output yang Diharapkan:

✅ Terhubung ke API Insforge
   URL: <https://instance-insforge-anda.insforge.app>

📦 Memuat data ekspor...
⬆️  Mengimpor pengguna...
   ✅ Mengimpor 41/41 akun
✅ Impor selesai!

Tips Pro: Skrip ini idempoten, artinya Anda dapat menjalankannya beberapa kali tanpa membuat pengguna duplikat. Skrip ini hanya akan memperbarui catatan yang ada jika ditemukan.

Fase 2: Migrasi Basis Data Anda

Selanjutnya, kita akan memindahkan seluruh basis data PostgreSQL Anda, termasuk skema, data, dan bahkan kebijakan Row Level Security (RLS) Anda.

Langkah 2.1: Ekspor Skema & Data Basis Data

Perintah ini menggunakan pg_dump untuk membuat cadangan SQL lengkap dari skema publik Anda dari Supabase.

npm run export:db

Output yang Diharapkan:

✅ Basis data berhasil diekspor
   File: database-export.sql (245 KB)

Ini akan menghasilkan file database-export.sql.

Langkah 2.2: Transformasi SQL untuk Insforge

Supabase menggunakan beberapa fungsi dan ekstensi khusus. Skrip ini membersihkan file SQL yang diekspor, menghapus kode khusus Supabase, memperbarui kebijakan RLS (misalnya, auth.uid() menjadi uid()), dan membuatnya kompatibel dengan Insforge.

npm run transform:db

Output yang Diharapkan:

✅ SQL ditransformasikan untuk Insforge
   Output: database-export.insforge.sql

Ini membuat file baru yang siap untuk Insforge: database-export.insforge.sql.

Langkah 2.3: Impor Basis Data ke Insforge

Terakhir, mari impor file SQL yang telah ditransformasi ke proyek Insforge Anda.

npm run import:db

Output yang Diharapkan:

🗄️  Mengimpor basis data ke Insforge...
✅ Impor basis data selesai!
Tabel yang terpengaruh: 12
Baris yang diimpor: 985

Skema dan data basis data Anda sekarang berhasil dimigrasikan!

Fase 3: Migrasi Penyimpanan File Anda

Fase terakhir adalah memindahkan semua file Anda dari Supabase Storage ke Insforge Storage. Proses ini mempertahankan path file yang sama persis, yang sangat penting untuk mencegah tautan rusak.

Langkah 3.1: Buat Ulang Bucket Penyimpanan

Pertama, skrip akan membaca daftar bucket dari proyek Supabase Anda dan membuat yang identik di Insforge, dengan mempertahankan pengaturan publik atau privatnya.

npm run create:buckets

Output yang Diharapkan:

✅ Terhubung ke Supabase PostgreSQL
📦 Menemukan 4 bucket di Supabase:
📋 Membuat bucket: generated-images (public)... ✅ Berhasil dibuat
📋 Membuat bucket: raw-product-images (public)... ✅ Berhasil dibuat
...
✅ Pembuatan bucket selesai!

Langkah 3.2: Unduh Semua File dari Supabase

Perintah ini mengunduh setiap file dari semua bucket Supabase Anda, dengan mempertahankan struktur direktori asli.

npm run export:storage

Output yang Diharapkan:

📦 Memulai ekspor penyimpanan dari Supabase...
⬇️  Mengunduh file...
   [1/1572] generated-images/user123/image.jpg ✅
   ...
   [1572/1572] reference-images/ref5.jpg ✅

✅ Ekspor selesai! Diunduh: 1.572 file

Semua file akan disimpan secara lokal di direktori storage-downloads/.

Langkah 3.3: Unggah Semua File ke Insforge

Sekarang, kita akan mengunggah semua file yang diunduh ke bucket yang sesuai di Insforge.

npm run import:storage

Output yang Diharapkan:

📦 Ditemukan 1572 file untuk diimpor
⬆️  [1/1572] generated-images/user123/scene/image.jpg... ✅ Terunggah
...
✅ Impor selesai! Berhasil: 1569/1572

Langkah 3.4: Sentuhan Akhir - Perbarui Semua URL Penyimpanan

Ini adalah tongkat ajaibnya. Basis data Anda kemungkinan berisi ribuan URL yang mengarah ke Supabase Storage. Skrip ini terhubung ke basis data Insforge Anda dan melakukan pencarian-dan-penggantian universal di semua tabel. Skrip ini secara cerdas memperbarui setiap URL penyimpanan Supabase ke URL Insforge yang baru, bahkan di dalam bidang JSONB yang kompleks.

npm run update:storage-urls

Output yang Diharapkan:

✅ Terhubung ke API Insforge
🔄 Penggantian URL Universal...
📊 Ditemukan:
   - 997 generasi dengan URL Supabase di input
   - 1023 generasi dengan URL Supabase di output
⏳ Memperbarui SEMUA URL secara universal...
✅ Semua URL penyimpanan Supabase telah diperbarui!

Dan selesai! Seluruh proyek Anda sekarang telah dimigrasikan.

Langkah Selanjutnya? Pasca-Migrasi

Data Anda telah dimigrasikan, tetapi Anda belum selesai. Berikut adalah langkah-langkah terakhir untuk menjalankan aplikasi Anda di Insforge.

  1. Perbarui Kode Aplikasi: Ubah konfigurasi klien aplikasi Anda untuk menunjuk ke instance Insforge Anda, bukan Supabase. Untuk panduan terperinci tentang mengonfigurasi ulang SDK menggunakan MCP, lihat postingan blog pendamping kami.

    // Sebelum (Supabase)
const supabase = createClient('URL_SUPABASE', 'KUNCI_ANON_SUPABASE');

// Sesudah (Insforge)
const insforge = createClient('URL_API_INSFORGE_ANDA', 'KUNCI_API_INSFORGE_ANDA');

  2. Pengujian End-to-End: Uji aplikasi Anda secara menyeluruh.

    • Bisakah pengguna masuk dengan kata sandi lama mereka?
    • Apakah gambar dan file dimuat dengan benar?
    • Apakah semua fitur yang terkait dengan data berfungsi seperti yang diharapkan?

  3. Pembersihan: Setelah Anda mengonfirmasi semuanya berfungsi, Anda dapat menghapus file migrasi sementara (storage-downloads/, .sql, .json).

Mengatasi Masalah Umum

  • Kesalahan File too large saat impor penyimpanan: File Anda melebihi batas unggah instance Insforge. Anda mungkin perlu meningkatkan batas atau memigrasikan file secara manual.
  • Login dengan kata sandi gagal: Periksa kembali apakah skrip import:auth berjalan dengan sukses. Hash kata sandi bcrypt seharusnya dipertahankan apa adanya.
  • Koneksi timeout: Verifikasi bahwa IP Anda masuk daftar putih dalam pembatasan jaringan Supabase dan bahwa string koneksi .env Anda benar.

Selamat bermigrasi! 🚀

return Blogs