Setup Connection

Buka di CMS

Langkah 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 QlarTetap di jaringan Anda (gateway)
DatabaseDirect connection — Qlar terhubung ke database AndaThrough your gateway — gateway menjalankan query di dekat database Anda
FilesUpload a workbook — Qlar menyimpan salinan satu file .xlsxParquet on your server — gateway meng-query folder file Parquet di tempatnya
Direct connectionThrough your gatewayUpload a workbookParquet on your server
Port database dapat dijangkau dari QlarWajibTidak wajibTanpa databaseTanpa database
Kredensial dipegang oleh QlarYaTidak, kredensial tetap di mesin AndaTidak perluTidak perlu
Data diprosesDi database AndaDi database AndaOleh Qlar, pada salinan fileDi server Anda, oleh gateway
Yang dikonfigurasi berikutnyaField di bawah iniGateway mana yang digunakanFile yang diuploadGateway 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

ProviderKeyPort Default
Microsoft SQL Serversqlserver1433
PostgreSQLpostgresql5432
MySQLmysql3306
Oracleoracle1521

Field Koneksi

FieldDeskripsi
ProviderJenis database yang Anda hubungkan.
ServerHostname atau alamat IP server database. Sertakan port jika bukan port default, misalnya db.example.com:1433.
DatabaseNama database target.
AuthenticationKhusus SQL Server: SQL Login (default) atau Service Principal (Microsoft Entra ID). Lihat Service principal Microsoft Entra ID.
UserUsername database yang dipakai untuk autentikasi. Dengan service principal, field ini berlabel Client ID.
PasswordPassword 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).

FieldYang diisi
ServerHost 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.
DatabaseNama warehouse, lakehouse, atau database.
Client IDApplication (client) ID dari app registration. Jika app berada di tenant yang berbeda dari database, isi clientId@tenantId.
Client SecretNilai 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 ke db_datareader, atau berikan SELECT pada 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

ErrorKemungkinan penyebab
Connection timeoutFirewall memblokir port, atau server tidak dapat dijangkau dari host plugin.
Authentication failedUsername atau password salah.
ClientSecretCredential authentication failedClient ID, tenant, atau client secret salah, atau secret sudah kedaluwarsa.
Login failed untuk service principalApp berhasil diautentikasi tetapi belum punya akses ke workspace atau database tersebut.
Koneksi berhasil tetapi tidak ada tabel yang tampilService 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 foundField Database tidak cocok dengan nama database yang ada di server tersebut.
SSL/TLS errorServer 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.

Halaman Terkait