Panduan Aman Migrasi n8n: Cara Benar Export/Import Entities & Solusi Error di Versi 2.18.7
Memindahkan data dari satu instance n8n ke instance lainnya kadang bisa menjadi tantangan tersendiri. Jika Anda hanya ingin memindahkan satu atau dua workflow, fitur Download/Import dari UI mungkin sudah cukup. Namun, bagaimana jika Anda perlu memigrasikan seluruh ekosistem—termasuk Credentials, Users, Tags, hingga pengaturan Global Variables?
Untuk kebutuhan skala besar ini, n8n menyediakan perintah CLI (Command Line Interface) khusus: export:entities dan import:entities. Sayangnya, fitur ini masih berstatus Under Development (Beta) dan memiliki bug spesifik pada rilis seperti versi 2.18.7 yang bisa menyebabkan proses import gagal total.
Artikel ini akan membahas langkah demi langkah cara melakukan export dan import entitas n8n dengan benar, plus trik esensial untuk melewati error duplikat tag mapping.
Langkah 1: Melakukan Export Tanpa “Sampah” Riwayat Eksekusi
Kesalahan paling umum saat melakukan ekspor penuh adalah ikut terawanya tabel riwayat eksekusi (execution history). Jika n8n Anda memproses ribuan data per hari, menyertakan riwayat eksekusi akan membuat file backup bengkak hingga hitungan Gigabyte dan berisiko membuat server Anda kehabisan memori (OOM Killed) saat proses berjalan.
Pastikan Anda menggunakan parameter penonaktifan history saat mengekspor. Masuk ke VPS Anda dan jalankan perintah ini (sesuaikan <NAMA_CONTAINER> dengan nama container Docker n8n Anda):
docker exec -it <NAMA_CONTAINER> n8n export:entities --outputDir=/home/node/.n8n/backup_bersih --includeExecutionHistoryDataTables=false
Perintah ini akan membaca seluruh logika n8n Anda dan membungkusnya menjadi satu file bernama entities.zip di dalam folder tujuan.
Langkah 2: Operasi File Zip (Solusi Wajib untuk v2.18.7)
Di sinilah letak masalah utamanya. Pada n8n versi 2.18.7, proses export secara tidak sengaja menyedot dua tabel database yang fungsinya tumpang tindih terkait pelabelan (tags):
workflows_tags.jsonl(Format tabel baru)workflowtagmapping.jsonl(Format tabel lama / technical debt)
Jika Anda langsung mengimpor file entities.zip ini, n8n akan mencoba memasukkan kedua data tersebut ke tabel tujuan yang sama. Hasilnya? PostgreSQL akan menolak keras dan memunculkan pesan mematikan:
duplicate key value violates unique constraint "pk_workflows_tags"
Cara Mengatasinya:
Kita harus menghapus file workflowtagmapping.jsonl langsung dari dalam arsip zip sebelum diimpor. Jangan mengekstraknya, gunakan utilitas zip dari terminal untuk mencabut file tersebut secara instan.
Jalankan perintah ini di dalam direktori tempat file entities.zip Anda berada:
zip -d entities.zip workflowtagmapping.jsonl
Catatan Penting: Jika server baru Anda murni untuk instalasi baru dan tidak butuh riwayat sama sekali, namun Anda ragu apakah file eksekusi ikut terbawa atau tidak (karena bug parameter n8n), Anda bisa memastikannya bersih dengan perintah sapu jagat ini:
zip -d entities.zip workflowtagmapping.jsonl executiondata.jsonl executionentity.jsonl workflowhistory.jsonl
Langkah 3: Eksekusi Import ke Server Baru
Setelah file entities.zip Anda “disucikan” dari file duplikat, file backup tersebut kini 100% aman untuk diimpor ke server n8n tujuan.
Agar tidak terjadi bentrok dengan ID default yang mungkin sudah ada di database server baru (fresh install), sangat disarankan untuk menggunakan flag --truncateTables true. Flag ini bertugas mengosongkan seluruh tabel tujuan terlebih dahulu sebelum menyuntikkan data dari file zip Anda.
Jalankan perintah ini di container n8n server baru Anda:
docker exec -it <NAMA_CONTAINER_BARU> n8n import:entities --inputDir=/home/node/.n8n/backup_bersih --truncateTables true
Tunggu prosesnya berjalan. Jika langkah kedua tadi dilakukan dengan benar, terminal Anda akan dipenuhi dengan indikator centang hijau ✅ Completed hingga baris terakhir!
Kesimpulan
Fitur CLI export/import entities dari n8n adalah alat yang sangat bertenaga untuk migrasi server tingkat lanjut. Mengetahui kelemahan pada versi beta-nya—terutama konflik pada file workflowtagmapping.jsonl—akan menghemat waktu berjam-jam dari proses troubleshooting database.
Dengan membuang file bermasalah dari dalam arsip zip secara manual, Anda menjembatani kekurangan sistem dan memastikan server otomasi Anda kembali beroperasi tanpa hambatan di lingkungan yang baru. Selamat mencoba!