Setup Connection
Buka di CMSLangkah pertama dalam mengonfigurasi SQL Database Reader adalah menentukan dari mana Qlar membaca data Anda, lalu memberikan apa yang dibutuhkannya untuk itu.
Buka Tools → Plugins di sidebar agent, buka plugin SQL Database Reader, lalu mulai dari langkah Access.
Pilih sumber data
Langkah Access menanyakan dua hal sekaligus: datanya berbentuk apa — database atau file — dan di mana data diproses — dijangkau atau disimpan oleh Qlar, atau tetap di jaringan Anda lewat on-premise gateway. Hasilnya empat kartu dalam dua grup:
| Dijangkau atau disimpan oleh Qlar | Tetap di jaringan Anda (gateway) | |
|---|---|---|
| Database | Direct connection — Qlar terhubung ke database Anda | Through your gateway — gateway menjalankan query di dekat database Anda |
| Files | Upload a workbook — Qlar menyimpan salinan satu file .xlsx | Parquet on your server — gateway meng-query folder file Parquet di tempatnya |
| Direct connection | Through your gateway | Upload a workbook | Parquet on your server | |
|---|---|---|---|---|
| Port database dapat dijangkau dari Qlar | Wajib | Tidak wajib | Tanpa database | Tanpa database |
| Kredensial dipegang oleh Qlar | Ya | Tidak, kredensial tetap di mesin Anda | Tidak perlu | Tidak perlu |
| Data diproses | Di database Anda | Di database Anda | Oleh Qlar, pada salinan file | Di server Anda, oleh gateway |
| Yang dikonfigurasi berikutnya | Field di bawah ini | Gateway mana yang digunakan | File yang diupload | Gateway mana yang digunakan |
Pilih Direct connection jika database Anda bisa menerima koneksi dari Qlar dan Anda tidak keberatan Qlar memegang kredensialnya. Sisa halaman ini berlaku untuk Anda.
Pilih Through your gateway jika membuka port database atau menyerahkan kredensial tidak dapat diterima di lingkungan Anda; lihat On-Premise Data Gateway. Semua langkah setelah ini, mulai dari pemilihan tabel, sama persis untuk kedua mode.
Pilih Upload a workbook jika datanya tersimpan di spreadsheet, bukan di database; lihat Excel File Source.
Pilih Parquet on your server jika datanya berupa folder file Parquet yang tidak boleh keluar dari jaringan Anda; lihat Parquet Files.
Anda bisa mengganti sumber data nanti, tetapi beralih berarti menyiapkan sumber data dari awal lagi.
Provider Database yang Didukung
| Provider | Key | Port Default |
|---|---|---|
| Microsoft SQL Server | sqlserver | 1433 |
| PostgreSQL | postgresql | 5432 |
| MySQL | mysql | 3306 |
| Oracle | oracle | 1521 |
Field Koneksi
| Field | Deskripsi |
|---|---|
| Provider | Jenis database yang Anda hubungkan. |
| Server | Hostname atau alamat IP server database. Sertakan port jika bukan port default, misalnya db.example.com:1433. |
| Database | Nama database target. |
| Authentication | Khusus SQL Server: SQL Login (default) atau Service Principal (Microsoft Entra ID). Lihat Service principal Microsoft Entra ID. |
| User | Username database yang dipakai untuk autentikasi. Dengan service principal, field ini berlabel Client ID. |
| Password | Password untuk user database tersebut. Dengan service principal, field ini berlabel Client Secret. Qlar menyimpannya agar plugin bisa terhubung kembali dengan sendirinya. Jika kredensial yang keluar dari lingkungan Anda tidak dapat diterima, gunakan on-premise gateway sebagai gantinya, karena di sana kredensial sama sekali tidak pernah sampai ke Qlar. |
Service principal Microsoft Entra ID (SQL Server)
Azure SQL Database, Azure Synapse, dan SQL endpoint Microsoft Fabric (warehouse atau lakehouse) bisa dibaca dengan app registration Microsoft Entra ID, tanpa SQL login. Pilih SQL Server sebagai provider, lalu ubah Authentication menjadi Service Principal (Microsoft Entra ID).
| Field | Yang diisi |
|---|---|
| Server | Host SQL endpoint, misalnya xxxx.datawarehouse.fabric.microsoft.com atau myserver.database.windows.net. Di Fabric, buka warehouse atau SQL analytics endpoint milik lakehouse, lalu gunakan Copy SQL connection string. |
| Database | Nama warehouse, lakehouse, atau database. |
| Client ID | Application (client) ID dari app registration. Jika app berada di tenant yang berbeda dari database, isi clientId@tenantId. |
| Client Secret | Nilai client secret dari app registration tersebut. |
Berhasil login saja tidak cukup: service principal juga harus punya akses baca ke data. Tanpa itu, pengujian koneksi berhasil tetapi tidak ada tabel yang tampil. Berikan akses sebelum menguji:
- Microsoft Fabric — Admin workspace men-share warehouse atau lakehouse ke app tersebut dan mencentang Read all SQL endpoint data, atau menambahkan app ke workspace dengan role Viewer. Share item saja adalah opsi yang lebih sempit.
- Azure SQL / Synapse — buat contained user dari external provider (
CREATE USER [nama-app] FROM EXTERNAL PROVIDER) lalu masukkan kedb_datareader, atau berikanSELECTpada schema yang dibutuhkan agent.
Koneksi selalu terenkripsi dan memvalidasi sertifikat server.
Fabric dan Azure SQL sering menyimpan tabel di luar schema dbo, sehingga tabel SQL Server ditampilkan sebagai schema.table, misalnya SLV.customer atau GLD.dim_branch.
Autentikasi service principal hanya tersedia untuk koneksi SQL Server langsung (direct). PostgreSQL, MySQL, dan Oracle memakai user dan password database.
Menguji Koneksi
Sebelum menyimpan, klik Test Connection. Plugin akan mencoba membuka koneksi dan menjalankan query ringan untuk memverifikasi konektivitas. Pengujian ini memiliki batas waktu 30 detik.
Pengujian yang berhasil mengembalikan:
- Connected: Yes
- Response time: waktu yang dibutuhkan untuk terhubung, dalam milidetik
- Database version: string versi yang dilaporkan oleh server
Jika pengujian gagal, respons menyertakan pesan error untuk membantu Anda mendiagnosis masalahnya.
Kegagalan pengujian yang umum
| Error | Kemungkinan penyebab |
|---|---|
| Connection timeout | Firewall memblokir port, atau server tidak dapat dijangkau dari host plugin. |
| Authentication failed | Username atau password salah. |
ClientSecretCredential authentication failed | Client ID, tenant, atau client secret salah, atau secret sudah kedaluwarsa. |
| Login failed untuk service principal | App berhasil diautentikasi tetapi belum punya akses ke workspace atau database tersebut. |
| Koneksi berhasil tetapi tidak ada tabel yang tampil | Service principal bisa login tetapi tidak bisa membaca data. Berikan akses baca seperti dijelaskan di Service principal Microsoft Entra ID, lalu muat ulang tabelnya. |
| Database not found | Field Database tidak cocok dengan nama database yang ada di server tersebut. |
| SSL/TLS error | Server mewajibkan autentikasi berbasis sertifikat. |
Memuat Tabel dari Koneksi
Setelah pengujian koneksi berhasil, klik Load Tables. Plugin membaca skema database yang terhubung dan mengembalikan daftar semua tabel beserta kolom, tipe data, dan constraint-nya.
Tabel PostgreSQL dan SQL Server ditampilkan beserta schema-nya (schema.table), sehingga tabel bernama sama di schema berbeda tetap terpisah.
Yang dimuat untuk setiap kolom:
- Nama kolom dan tipe data
- Penanda nullable
- Apakah kolom tersebut primary key
- Relasi foreign key yang terdeteksi dari constraint database
Langkah ini wajib dilakukan sebelum Anda bisa lanjut ke mengonfigurasi tabel dan kolom.
Catatan Keamanan
- Gunakan user database read-only khusus. Jangan pernah menggunakan akun admin.
- Batasi akses user database hanya ke tabel-tabel yang dibutuhkan agent.
- Jika memungkinkan, konfigurasikan server database agar hanya menerima koneksi dari alamat IP host plugin.
- Jika kebijakan keamanan Anda tidak mengizinkan port database dapat dijangkau dari luar jaringan, on-premise gateway menghilangkan persyaratan itu sepenuhnya.