Insert, Update, Upsert, dan Delete: Jangan Salah Memilih Operasi Database

Empat operasi database dapat terlihat serupa karena semuanya mengubah data. Namun insert, update, upsert, dan delete membawa asumsi bisnis yang berbeda. Kesalahan memilih operasi dapat menghasilkan duplikasi, perubahan pada record yang salah, atau penghapusan yang terlalu luas.

Empat operasi, empat maksud

Insert membuat record baru dan seharusnya gagal bila kunci unik yang sama sudah ada. Update mengubah record yang cocok dengan kondisi, tanpa membuat record baru. Upsert memperbarui record yang cocok dengan conflict key atau membuatnya bila belum ada. Delete menghapus record yang cocok dan membutuhkan kehati-hatian paling tinggi terhadap kondisi.

Mulai dari peristiwa bisnis, bukan nama endpoint

Pesanan baru biasanya memerlukan insert karena duplikat perlu terlihat sebagai konflik. Sinkronisasi katalog produk dapat menggunakan upsert bila kode produk dari sistem pemilik benar-benar stabil. Perubahan alamat customer lebih tepat menggunakan update dengan identitas customer. Penghapusan data sebaiknya mempertimbangkan soft delete atau status nonaktif bila riwayat masih dibutuhkan.

Jangan otomatis memilih upsert untuk menghindari error duplicate key. Error tersebut kadang menunjukkan request yang dikirim dua kali atau identitas bisnis yang tidak konsisten. Upsert dapat menyembunyikan masalah itu dengan mengganti data lama tanpa keputusan yang disengaja.

Conflict key dan WHERE adalah pagar utama

Update dan delete harus memiliki kondisi yang spesifik. Pada NitroNet, operasi mutasi tanpa WHERE ditolak agar workflow tidak mengubah seluruh tabel secara tidak sengaja. Hasil nol baris juga dialirkan sebagai kondisi tidak ditemukan, sehingga workflow dapat memilih respons atau proses lanjutan yang sesuai.

Upsert membutuhkan conflict key yang mewakili identitas domain, misalnya external_product_id yang unik per sumber. Kunci teknis yang dibuat ulang pada setiap request tidak cocok untuk mendeteksi record lama. Sebelum memilihnya, periksa constraint database dan sepakati sistem mana yang menjadi pemilik identitas.

Contoh: sinkronisasi customer dari CRM

1. Validasi kontrak masuk.

   Pastikan external ID, nama, dan field wajib memiliki tipe yang benar.

2. Normalisasi nilai.

   Bersihkan spasi, format telepon, atau kapitalisasi tanpa mengubah nilai identitas.

3. Pilih conflict key.

   Gunakan ID milik CRM beserta identitas tenant bila data bersifat multi-organisasi.

4. Jalankan upsert.

   Petakan hanya kolom yang memang dikuasai CRM agar field lokal tidak tertimpa.

5. Tangani hasil.

   Bedakan sukses, tidak ditemukan untuk operasi lain, duplicate, dan gagal sebagai jalur eksplisit.

Untuk pencatatan invoice, pola berbeda: insert dengan idempotency key atau kunci bisnis biasanya lebih aman daripada upsert buta, karena nilai transaksi yang berubah diam-diam dapat menimbulkan masalah rekonsiliasi.

Guardrail sebelum workflow diaktifkan

• Preview mapping sumber dan kolom tujuan, termasuk kompatibilitas tipe.
• Uji record ada, tidak ada, duplicate, null, dan nilai di luar constraint.
• Pastikan WHERE atau conflict key berasal dari field yang tervalidasi.
• Gunakan transaksi satu koneksi ketika beberapa penulisan harus berhasil bersama.
• Aktifkan workflow melalui Sandbox sebelum Production dan gunakan data uji yang mudah dikenali.

Buat matriks kepemilikan field ketika dua sistem dapat mengubah entitas yang sama. Misalnya CRM memiliki nama dan email customer, sedangkan ERP memiliki credit limit. Upsert dari CRM hanya boleh memperbarui kolom miliknya. Tanpa aturan ini, sinkronisasi yang tampak berhasil dapat menimpa keputusan sistem lain. Sertakan sumber perubahan, timestamp, dan versi bila konflik bersamaan mungkin terjadi.

Operasi delete memerlukan pemeriksaan tambahan terhadap foreign key, audit, retensi, serta efek downstream. Banyak domain lebih aman memakai status nonaktif dan proses purge terpisah yang berwenang. Bila hard delete memang dibutuhkan, tampilkan preview kriteria dan uji kondisi nol, satu, serta banyak record. Setelah deployment, pantau rows affected; perubahan mendadak dapat menandakan filter rusak atau sumber mengirim identitas yang tidak sesuai.

Catat alasan operasi pada dokumentasi workflow: siapa pemilik record, identitas apa yang dipakai, dan mengapa operasi aman diulang. Review ini membantu programmer berikutnya membedakan pilihan sadar dari default editor.

Batasan yang perlu dinyatakan terang

NitroNet memisahkan node Tulis DB, Update DB, Upsert DB, dan Delete DB agar maksud operasi terlihat di workflow. Guardrail membantu mencegah kesalahan dasar, tetapi keputusan kepemilikan data tetap berada pada tim bisnis dan database. Lihat arsitektur agent-centric dan cara kerja workflow NitroNet untuk memahami jalur eksekusinya.