Database Eksternal
1. Ikhtisar & Nilai Bisnis
Integrasi Database Eksternal merupakan salah satu fitur sentral yang memungkinkan Anda untuk menghubungkan sumber kebenaran data (single source of truth) katalog produk, inventaris, atau warehouse bisnis Anda secara langsung ke ekosistem komputasi DAGANGBOT. Secara historis, staf admin toko selalu terbebani oleh proses pembaharuan data berulang; mengubah harga atau stok di sistem kasir, kemudian harus mengubahnya lagi satu per satu di sistem bot atau e-commerce. Dengan mengeliminasi proses unggah manual atau rutinitas pembaruan berkas CSV yang rentan tertinggal, DAGANGBOT secara otomatis bertindak sebagai pembaca pasif. Platform akan mengambil baris data (sebagai entitas produk dan varian) melalui kueri jaringan read-only secara berkala.
Fitur ini dirancang khusus bagi merchant skala menengah hingga besar, franchise, atau distributor yang secara de facto sudah mengelola persediaan barang di dalam infrastruktur tabel MySQL atau PostgreSQL (misalnya sebagai backbone dari aplikasi Enterprise Resource Planning / ERP internal, Point of Sales (POS) kustom, atau aplikasi manajemen gudang terpadu milik perusahaan).
Melalui pengaktifan gerbang integrasi ini, Anda akan memperoleh kepastian presisi data yang selaras antara sistem internal pergudangan Anda dan kecerdasan asisten virtual DAGANGBOT. Segala wujud dinamika operasional—seperti fluktuasi harga karena promo akhir pekan, penambahan koleksi warna baru, atau pengurangan stok karena barang terjual di toko fisik (offline)—akan tercermin secara presisi dalam kerangka pemahaman bot. Jawaban bot otomatis menyeimbangkan pengetahuan linguistik RAG (Retrieval-Augmented Generation) dari pembacaan pangkalan data ini pada siklus atau jendela sinkronisasi berikutnya, menjauhkan Anda dari komplain pelanggan atas "stok hantu" (barang disebut ada oleh bot, padahal fisik kosong).
2. Alur Visual & Antarmuka
Konfigurasi integrasi infrastruktur tidak seharusnya menjadi labirin teknis yang membingungkan. DAGANGBOT mendesain proses penyiapan melalui formulir antar-muka tunggal (Single-Pane-of-Glass) yang berorientasi pada kepastian keamanan.
Pada saat Anda mengakses layar "Integrasi Database Eksternal" di dasbor DAGANGBOT, Anda akan disuguhi kolom formulir koneksi esensial: Driver, Alamat Host/IP, Port, Skema, serta Username dan Password. Formulir ini mengkapsulasi kerumitan koneksi TCP ke dalam masukan yang mudah diisi oleh staf IT Anda.

Prosedur antarmuka menerapkan prinsip Validasi Mendahului Pemilihan (Validate-First). Platform tidak akan membiarkan Anda mengetik nama tabel secara manual (yang rawan memicu galat pengetikan kapitalisasi / typo). Sebaliknya, setelah kredensial berhasil menembus lapisan peladen database Anda melalui ping jabat tangan, sistem akan menggelar (render) antarmuka modal konfigurasi koneksi dan pelacak skema tabel (Table Picker):

Lebih jauh, antarmuka ini memberikan kontrol visibilitas status instan. Jika firewall Anda menolak akses masuk DAGANGBOT, layar akan langsung mencetak banner kesalahan jaringan (kode batas waktu TIMEOUT) alih-alih memutar ikon loading tanpa ujung. Hal ini secara drastis memangkas waktu diagnosis.
3. Panduan Langkah-demi-Langkah
Untuk memastikan aliran data katalog Anda masuk dengan lancar tanpa terblokir oleh lapisan keamanan jaringan, ikuti langkah-langkah presisi di bawah ini:
Tahap 1: Persiapan Jaringan & Egress IP
Sistem DAGANGBOT beroperasi di balik perlindungan jaringan cloud. Ketika Anda meminta platform menarik data, agen DAGANGBOT akan melakukan koneksi keluar (outbound) menuju alamat host database Anda.
- Dapatkan Egress IP DAGANGBOT: Buka antarmuka Integrasi Database pada dasbor, atau gunakan utilitas API
Belum ada endpoint terdaftar untuk tag Integrations.
GET /api/v1/integrations/egress-ip untuk menanyakan deretan alamat IP spesifik platform DAGANGBOT.
Tahap 2: Provisi Pengguna Basis Data (Read-Only)
Kami merancang modul ini secara zero destructive. Namun demikian, sebagai praktik kebersihan keamanan (security hygiene) yang mutlak:
- Buat Pengguna Baru:
Di dalam instans database Anda (MySQL atau PostgreSQL), buatlah satu user terdedikasi, misalnya bernama
dagangbot_ro. - Batasi Hak Akses Khusus:
Cabut semua hak bawaan dan berikan pendelegasian akses yang murni hanya untuk operasi
SELECT. DAGANGBOT akan menolak dan memutuskan koneksi jika sistem mendeteksi hak modifikasi tabel (INSERT,UPDATE,DELETE,DROP). Anda dapat melihat contoh kueri pemberian akses spesifik pada bagian Parameter & Spesifikasi Teknis di bawah.
Tahap 3: Pendaftaran Koneksi di Dasbor
- Pilih Dialek dan Isi Kredensial:
Buka dasbor Integrasi, buat modul "Database Eksternal". Tentukan driver (pilih
mysqlataupostgres). Isi kolom host dengan alamat domain publik kualifikasi penuh (Fully Qualified Domain Name) atau IPv4 Publik. Masukkan port, nama database katalog, serta username yang baru Anda buat. - Aktifkan Enkripsi Transport:
Nyalakan sakelar SSL/TLS. Jika instans PostgreSQL Anda mewajibkan koneksi aman (umumnya ditandai dengan opsi
sslmode=require), Anda wajib menghidupkan sakelar ini agar DAGANGBOT tidak ditolak akibat koneksi teks terang (plaintext). - Validasi Koneksi (Handshake): Klik tombol "Uji Koneksi". DAGANGBOT akan melemparkan ping koneksi dan mendaftar skema tabel publik.
Tahap 4: Pemetaan Kolom (Column Mapping) dan Pemilihan Tabel
Setelah sukses melakukan jabat tangan jaringan, antarmuka pemilih tabel (Table Picker) akan terbuka.
- Anda dapat memilih satu atau beberapa tabel maupun view yang menyajikan inventaris utuh. Praktik terbaik kami menyarankan Anda membangun sebuah SQL View terpadu di sistem Anda (misalnya
v_katalog_bot), sehingga DAGANGBOT tidak perlu menebak penggabungan kolom. - Petakan kolom (melalui struktur atribut
mapping) antara spesifikasi sistem asal dan DAGANGBOT. Misalnya kolom lokalnama_barangdipetakan ke field DAGANGBOTname. - Setelah disimpan, worker latar belakang akan melakukan bootstrap untuk mengindeks data produk ke dalam penyimpanan pencarian. Sistem secara otomatis menerapkan pembatasan aman (hard limit) sebanyak
5000baris pertama per tabel menggunakan pembatasan kueri (LIMIT) untuk mencegah kelebihan beban (out-of-memory) pada klaster pencarian.
4. Parameter & Spesifikasi Teknis
Arsitektur konektor basis data telah dibekali dengan berbagai penangkal untuk memastikan asisten virtual Anda tidak mendestabilisasi (membuat down) basis data utama Anda.
Keamanan Penolakan Modifikasi (Zero Destructive)
Selain kewajiban user read-only dari sisi Anda, DAGANGBOT memaksa lingkungan koneksi berstatus baca-saja dari sisi aplikasi (Application-Level Enforcement).
- PostgreSQL: Setiap kali sesi dibuka, DAGANGBOT menyuntikkan rentetan opsi:
-c default_transaction_read_only=ondan-c statement_timeout=15000. Ini menjamin query tidak bisa mengubah data dan kueri apa pun yang memakan waktu lebih dari 15 detik akan diinterupsi oleh engine Postgres untuk mencegah kebocoran koneksi. - MySQL: DAGANGBOT memuat setelan DSN yang merantai koneksi dengan
ReadTimeout=15sguna mencegah penguncian kueri pembacaan panjang yang berisiko menahan sesi.
Proteksi SSRF & SSRF-Netguard
Platform DAGANGBOT menyediakan proteksi Server-Side Request Forgery (SSRF) lapis baja bawaan dengan modul Netguard (netguard.SafeDialer). Upaya memasukkan Host yang merujuk pada alamat IP privat / internal di dalam subnet DAGANGBOT (seperti 192.168.x.x, 10.x.x.x, 127.0.0.1), metadata cloud (seperti AWS IMDS 169.254.169.254), atau
host dinamis yang secara senyap beresolusi ke IP privat (DNS rebinding pada saat resolusi nama) akan ditolak secara brutal di level layer TCP dengan pesan galat pencekalan SSRF sebelum driver database melakukan dialing. Modul perlindungan ini turut memblokir pemanfaatan eksploitasi perutean ulang (redirect) ke alamat terlarang. Anda
diwajibkan menggunakan ruang alamat publik internet yang sah.
Jejak Audit Kueri (Query Audit Trail)
Setiap eksekusi interaksi GetProducts maupun panggilan skema ke instans database Anda mewariskan jejak audit kueri tak termutasi pada penampung log terpusat platform. Metrik spesifik mencakup latensi durasi eksekusi, volume penarikan baris, dan kode resolusi operasional. Seluruh log bersifat informasional; mereka direkam sebagai bukti
read-only tanpa pernah mencatat rahasia sandi dan konten isi katalog.
Tabel Atribut Koneksi
Spesifikasi Penarikan Data (Query)
Untuk menghindari lonjakan memori tak terduga (Memory Leakage) pada klaster mesin RAG (PERF-3), DAGANGBOT membatasi volume baris per tabel.
Sebagai lapisan perlindungan performa memori pada infrastruktur RAG (Audit PERF-3), sistem secara permanen menyuntikkan limit maksimal pembacaan hingga 5000 baris pertama setiap kali iterasi tabel berlangsung. Pemotongan baris ini merupakan ambang batas sistem murni (defaultMaxRowsPerTable = 5000) dan tidak memerlukan injeksi parameter eksternal apapun dari sisi pengguna.
Kode Contoh - Skrip Persiapan Pengguna (PostgreSQL)
Berikut adalah contoh struktur SQL ideal bagi administrator basis data Anda untuk menyiapkan saluran khusus bagi DAGANGBOT sebelum form di dasbor diisi:
-- Contoh eksekusi di instance PostgreSQL
CREATE USER dagangbot_ro WITH PASSWORD 'GantiDenganKataSandiKuat';
GRANT CONNECT ON DATABASE katalog_db TO dagangbot_ro;
GRANT USAGE ON SCHEMA public TO dagangbot_ro;
-- Hanya mengizinkan baca, tanpa hapus/tulis
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dagangbot_ro;
-- Atur waktu batas kueri tambahan pada level role
ALTER ROLE dagangbot_ro SET statement_timeout = '15s';Kode Contoh - Skrip Persiapan Pengguna (MySQL)
Untuk pengguna dengan mesin MySQL:
CREATE USER 'dagangbot_ro'@'%' IDENTIFIED BY 'SandiSuperRahasia123';
GRANT SELECT ON katalog_db.* TO 'dagangbot_ro'@'%';
FLUSH PRIVILEGES;Kode Contoh - Menguji Konektivitas Mesin Target via cURL
Sebelum menyimpan integrasi selamanya, Anda dapat mengevaluasi konektivitas melalui panggilan POST ringan (pinging) ini untuk menyimulasikan jabat tangan TCP. Jika sukses, ia akan mengembalikan respons 200 OK.
curl -X POST "https://dagangbot.web.id/api/v1/integrations/test/database" \
-H "Authorization: Bearer <TOKEN_ANDA_ATAU_SESSION>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"driver": "postgres",
"host": "db.tokosaya.com",
"port": 5432,
"database": "katalog_db",
"user": "dagangbot_ro",
"password": "secure_password",
"ssl": true,
"tables": ["products"]
}
}'Kode Contoh - Mengambil Entitas Skema Tabel Publik
DAGANGBOT memiliki kecerdasan otomatis dalam menginterogasi information_schema (baik untuk Postgres maupun fungsi DATABASE() pada MySQL) guna mencetak senarai seluruh tabel, kecuali tabel system catalog. Parameter yang dimasukkan sama dengan pengujian:
curl -X POST "https://dagangbot.web.id/api/v1/integrations/db/tables" \
-H "Authorization: Bearer <TOKEN_ANDA>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"driver": "mysql",
"host": "198.51.100.42",
"port": 3306,
"database": "toko_utama",
"user": "dagangbot_ro",
"password": "secure_password",
"ssl": false
}
}'Respons JSON yang diterima akan mencetak deretan string yang merujuk pada identitas tabel (misalnya ["tb_barang", "tb_variasi", "vw_katalog_bot"]), yang nantinya disalurkan oleh antarmuka frontend ke dalam dropdown Table Picker.
5. Relasi & Integrasi Ekosistem
Integrasi spesifik basis data ini tidak berdiri sebagai modul bisu, melainkan secara aktif menjadi bahan bakar (fuel) esensial bagi fungsionalitas hulu DAGANGBOT. Ia beresonansi erat dengan entitas AI dan berbagai alur penagihan kuota:
- Rekonstruksi Basis Pengetahuan RAG (Retrieval-Augmented Generation): Berbeda dengan bot tradisional yang membaca skrip teks statis, agen AI DAGANGBOT secara dinamis menelan (meng-ingest) seluruh baris data dari tabel eksternal yang sukses dibaca. Tiap baris tabel dikonversi menjadi representasi vektor matematis (embedding). Hal ini memampukan asisten pintar untuk memahami maksud linguistik pembeli, mencocokkan stok barang tanpa kueri kata kunci kaku, menyinggung sisa kuantitas terkini, serta menginformasikan penyesuaian harga terbaru (seperti diskon flash sale akhir bulan) dalam hitungan detik. Ketika sebuah produk Anda hapus di database Anda (row deletion), sistem DAGANGBOT secara otomatis membersihkannya dari konteks obrolan pada sesi sinkronisasi berjalannya, menghapus risiko penawaran barang usang.
- Sistem Manajemen Pesanan Eksekutif: Data mentah (seperti ID Variasi dan Harga Pokok Barang) yang dipetakan dari pangkalan data asal Anda, akan diturunkan secara hierarkis ke modul pengelolaan pesanan. Ketika tagihan (invoice) akhirnya digeneralisasi oleh bot untuk pembeli, DAGANGBOT merekatkan pengenal unik internal dari database asal tersebut, mempermudah ERP perusahaan Anda melakukan pencocokan (reconciliation) sewaktu transaksi dinyatakan berhasil dilunasi.
- Bebas Kuotasi Token Gateway (Zero-Consumption Sync): Dalam arsitektur penagihan komersial (kredit pemakaian DAGANGBOT), rutinitas mesin klaster backend yang menarik belasan ribu baris pangkalan data secara berkala digolongkan sebagai aktivitas maintenance internal. Aktivitas masif ini sepenuhnya gratis dan sama sekali tidak memengaruhi, mengurangi, atau menggerus saldo Kuotasi Gateway (Token) bulan berjalan milik Anda. Kuota token Anda murni dicadangkan dan digunakan hanya saat percakapan bot berbasis Large Language Model (LLM) melayani masuknya obrolan pembeli.
- Log Audit Keamanan (Security Audit Trail): Mengingat pengaitan database eksternal membuka potensi interaksi ranah privat, sistem DAGANGBOT merekam ketat setiap percobaan konektivitas awal, kegagalan login karena kata sandi keliru, atau jejak pemblokiran jangkauan firewall ke dalam catatan permanen. Manajer atau Pemilik Cabang (Level Platform Admin) dapat mengulas histori rekaman di masa lalu dengan merujuk ke modul Log Audit Interaksi Keamanan.
6. Pemecahan Masalah
Sistem konektivitas internet lintas penyedia (cross-provider) sering kali menyimpan kompleksitas yang tidak terlihat di permukaan. Adakalanya peladen pangkalan data Anda beroperasi secara normal ketika diakses dari jaringan area lokal (LAN) kantor, namun memblokir permintaan dari luar. Oleh karena itu, penting untuk memahami lapisan-lapisan diagnostik ini agar Anda dapat segera mengarahkan tim IT internal menemukan sumbatan jaringan atau kesalahan konfigurasi.
Sistem konektivitas internet lintas penyedia sering kali membingungkan. Jika Anda mengalami kendala saat memutar spinner ketika menghubungkan database eksternal ke lingkungan platform:
- Waktu Tenggang 10 Detik Terlampaui (Timeout pada Jabat Tangan):
Probe jaringan DAGANGBOT memuat toleransi waktu maksimal yang ketat, yakni
10 * time.Second(databaseProbeTimeout). Jika uji coba pengujian berputar lama lalu mendadak memutus sesi dengan kode batas kadaluwarsa waktu (TIMEOUT), akar masalahnya hampir pasti mengerucut pada firewall jaringan host Anda yang secara senyap menjatuhkan koneksi port. Firewall tidak menolak dengan pesan Reject, melainkan mengabaikan (mendrop) paket (perilaku stealth). Hubungi sysadmin Anda untuk memastikan Egress IP spesifik DAGANGBOT telah bertengger dalam senarai whitelist aturan masuk (Inbound Rules). - Proteksi Jaringan Tertutup Aktif: Apabila antarmuka DAGANGBOT merespons cepat namun dengan error mencolok "alamat privat/internal diblokir", sistem proteksi Netguard internal kami dengan sengaja menolak host tujuan tersebut karena IP hasil resolusi tersebut diklasifikasikan sebagai ruang alamat lokal menurut IANA (seperti jaringan tipe A 10.x.x.x, atau tipe C 192.168.x.x). Anda tidak dapat memerintahkan DAGANGBOT yang berada di Cloud Internet untuk mengakses peladen bare-metal tertutup di garasi Anda tanpa melewati router Public IP (Port Forwarding atau VPN).
- Peringatan Pemotongan Batas Baris (Truncation Warning):
Jika struktur katalog backend Anda membengkak hingga puluhan ribu variasi SKU, mesin DAGANGBOT akan memotong pembacaan tepat pada batas perlindungan (
defaultMaxRowsPerTable = 5000baris). Jutaan baris sisanya secara otomatis diabaikan oleh mesin, yang berpotensi memicu hilangnya konteks untuk produk di baris tersebut. Untuk merchant dengan katalog yang luar biasa masif, disarankan untuk mengatur ulang atau memfilter koleksi menggunakan view SQL terpisah agar produk inti berada di indeks teratas, karena limitasi kapasitas embedding tidak dapat dilonggarkan melalui parameter.

Kode Error & Penanganan Khusus
Berikut adalah kompilasi rincian struktur pesan kesalahan sistem saat memanggil API uji konektivitas atau akses integrasi database target, beserta resolusinya:
