Halaman ini diterjemahkan dari bahasa Inggris dengan bantuan AI. Jika keduanya berbeda, versi bahasa Inggris menjadi acuannya.
srv
Perintah yang digunakan untuk menjalankan StackQL sebagai layanan, yang kemudian dapat diakses oleh klien protokol komunikasi Postgres yang diautentikasi menggunakan mTLS. Perintah srv juga dapat menjalankan server Model Context Protocol (MCP) bersama server protokol komunikasi PostgreSQL, sehingga memungkinkan akses melalui dua protokol bagi klien database tradisional maupun agen AI.
Sintaksis
stackql srv [server_options] [flags]
Meskipun server StackQL menggunakan protokol komunikasi Postgres, server ini bukan server Postgres dan juga tidak memerlukannya. Protokol komunikasi digunakan oleh klien untuk berkomunikasi dengan server, yang menggunakan StackQL untuk menjalankan kueri atau operasi DML terhadap penyedia cloud dan SaaS jarak jauh dan mengembalikan hasilnya ke klien.
Parameter yang dikirim melalui protokol kueri yang diperluas (Parse / Bind / Execute, seperti yang digunakan oleh psycopg 3, pgx, dan JDBC) diikat di sisi server sebagai literal string. Mulai v0.12.742, placeholder $n di dalam literal string, pengidentifikasi yang diapit tanda kutip, atau komentar dibiarkan apa adanya, garis miring terbalik dalam nilai parameter di-escape, dan nilai teks NULL tetap menjadi string NULL (NULL SQL dibawa secara terpisah).
Opsi server
| Opsi | Deskripsi |
|---|---|
--pgsrv.address | Alamat tempat server mendengarkan (biasanya 0.0.0.0) |
--pgsrv.port | Port tempat server mendengarkan (misalnya 5444) |
--pgsrv.tls | Objek konfigurasi mTLS, lihat contoh di bawah |
--pgsrv.loglevel | Level log (default WARN) |
lihat Flag global untuk opsi tambahan
Opsi server MCP
Saat menjalankan perintah srv dengan dukungan MCP, opsi tambahan berikut tersedia:
| Opsi | Deskripsi |
|---|---|
--mcp.server.type | Tipe server MCP: http (dalam memori) atau reverse_proxy (berbasis TCP) |
--mcp.config | Objek konfigurasi JSON untuk server MCP (lihat dokumentasi MCP) |
--mcp.log.format | Pengodean log audit MCP: jsonl (default) atau otel (catatan log OTLP/JSON); mengganti nilai server.audit.format di objek konfigurasi |
--mcp.protocol.version | Revisi protokol MCP terbaru yang dinyatakan: auto (default), 2026-07-28 (hanya tanpa sesi), atau revisi yang lebih lama seperti 2025-11-25; mengganti nilai server.protocol_version di objek konfigurasi |
Mulai v0.12.742, transport HTTP MCP (--mcp.server.type=http atau reverse_proxy) menolak untuk berjalan kecuali objek konfigurasi menyebutkan token bearer dengan server.auth_token_env_var atau secara eksplisit memilih untuk tidak menggunakan autentikasi dengan "allow_unauthenticated": true. Lihat Autentikasi klien HTTP.
Lihat dokumentasi perintah MCP untuk informasi terperinci tentang cara mengonfigurasi dan menggunakan server MCP, termasuk mode deployment, opsi konfigurasi, dan integrasi dengan asisten AI.
Anda perlu mengatur variabel lingkungan yang diperlukan untuk autentikasi provider sebelum memulai server, lihat Menggunakan provider untuk informasi selengkapnya.
Untuk server yang berjalan lama, flag --env.file memungkinkan Anda menempatkan atau merotasi kredensial dalam file bergaya dotenv di disk sebelum server dijalankan, alih-alih mengekspor variabel ke shell:
stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env
Untuk perintah stackql srv, file dibaca sekali saat server dijalankan; cara memuat ulang kredensial di tengah sesi adalah melalui alat MCP reload_credentials.
Flag
| Flag | Deskripsi |
|---|---|
-h,--help | Menampilkan informasi bantuan |
-v,--verbose | Menjalankan kueri dalam mode verbose dengan output tambahan yang dikirim ke stdout; jika flag global -f (--outfile) ditetapkan,informasi log tambahan ini akan ditulis ke file output bersama hasil kueri |
lihat Flag global untuk opsi tambahan
Contoh
Jalankan proses server StackQL dan sambungkan menggunakan klien baris perintah psql.
Pertama, unduh file konfigurasi openssl.cnf dari stackql/stackql.
Selanjutnya, buat file sertifikat dan kunci yang akan digunakan oleh server dan klien untuk autentikasi TLS timbal balik (mTLS).
openssl req -x509 -keyout ~/stackqlcreds/server_key.pem -out ~/stackqlcreds/server_cert.pem -config ./openssl.cnf -days 365
openssl req -x509 -keyout ~/stackqlcreds/client_key.pem -out ~/stackqlcreds/client_cert.pem -config ./openssl.cnf -days 365
chmod 400 ~/stackqlcreds/client_key.pem
Sekarang atur variabel lingkungan; jika klien dan server berada di host yang sama, variabel ini dapat digunakan bersama.
export PGPORT=5444
export PGSSLCERT=~/stackqlcreds/client_cert.pem
export PGSSLKEY=~/stackqlcreds/client_key.pem
export PGSSLROOTCERT=~/stackqlcreds/server_cert.pem
export PGSSLSRVKEY=~/stackqlcreds/server_key.pem
export CLIENT_CERT=$(base64 -w 0 ~/stackqlcreds/client_cert.pem)
export PGSSLMODE=allow
Siapkan objek autentikasi untuk provider apa pun yang perlu diakses oleh server, misalnya untuk GitHub.
export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken
Sekarang jalankan server di satu terminal.
stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'
Di terminal lain, sambungkan ke server menggunakan klien baris perintah psql.
psql 127.0.0.1
Sekarang jalankan kueri StackQL terhadap provider yang telah diautentikasi.
psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.
127.0.0.1=> SHOW SERVICES IN github LIKE '%repos%';
id | name | title
--------------+-------+----------------------------
repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)
127.0.0.1=>