Lewati ke konten utama
Halaman terjemahan

Halaman ini diterjemahkan dari bahasa Inggris dengan bantuan AI. Jika keduanya berbeda, versi bahasa Inggris menjadi acuannya.

Sesi provider dan rahasia

Lihat juga:
[SET] [UNSET] [ Variabel sesi ] [ Flag global ]

Sebuah sesi dapat mengikat provider dengan sebuah alias yang memiliki kredensial, label tenancy, nilai default parameter, dan batas konkurensi permintaan sendiri, sehingga beberapa akun atau tenant dari provider yang sama dapat dikueri dalam satu sesi, dan juga dalam satu pernyataan. Field kredensial juga dapat diganti untuk sesi tersebut, dan rahasia dapat disimpan di memori sesi atau, dengan aktivasi eksplisit oleh operator, di penyimpanan rahasia sistem operasi. Semua ini dikonfigurasi dengan SET dan UNSET dan tersedia mulai StackQL v1.0.

Semua yang dijelaskan di sini berlaku dalam cakupan sesi saat ini. Koneksi independen ke server stackql srv tidak berbagi pengikatan atau rahasia, dan setiap permintaan MCP adalah sesi tersendiri; karena itu, lakukan konfigurasi dan kueri dalam satu batch pernyataan saat menggunakan server MCP.

Alias provider​

Pernyataan SET "$.providers.<alias>" mengikat sebuah alias ke provider. Nilainya berupa dokumen JSON yang disimpan dalam string:

KunciWajibDeskripsi
providerYaProvider kanonis yang dirujuk oleh alias, misalnya aws.
tenancyYaLabel pengelompokan seperti nama akun atau tenant. StackQL tidak memverifikasinya terhadap provider.
authSalah satu dari auth atau auth_secretDokumen autentikasi dengan bentuk yang sama seperti entri provider di objek --auth. Alias tidak meminjam kredensial provider kanonis.
auth_secretSalah satu dari auth atau auth_secretNama rahasia sesi yang menyimpan dokumen autentikasi.
paramsTidakNilai default untuk parameter provider yang dideklarasikan, termasuk parameter server yang dideklarasikan. Predikat dalam kueri mengganti nilai default.
tuningTidakBatas max_concurrent dan max_per_host untuk permintaan alias tersebut. Alias yang berbagi provider dan tenancy juga berbagi kontrol ini dan harus mendeklarasikan penyetelan yang identik.

Contoh berikut mengikat dua akun AWS dengan alias terpisah, masing-masing membaca kuncinya dari variabel lingkungan dengan nama yang berbeda, lalu mengkueri keduanya dalam satu pernyataan:

SET "$.providers.production" = '{
"provider": "aws",
"tenancy": "production-account",
"auth": {
"type": "aws_signing_v4",
"access_key_id_env_var": "PRODUCTION_AWS_ACCESS_KEY_ID",
"secret_access_key_env_var": "PRODUCTION_AWS_SECRET_ACCESS_KEY"
},
"params": {"region": "ap-southeast-2"},
"tuning": {"max_concurrent": 4, "max_per_host": 4}
}';

SET "$.providers.development" = '{
"provider": "aws",
"tenancy": "development-account",
"auth": {
"type": "aws_signing_v4",
"access_key_id_env_var": "DEVELOPMENT_AWS_ACCESS_KEY_ID",
"secret_access_key_env_var": "DEVELOPMENT_AWS_SECRET_ACCESS_KEY"
},
"params": {"region": "ap-southeast-2"},
"tuning": {"max_concurrent": 2}
}';

SELECT name, 'production' AS account FROM production.s3.buckets
UNION ALL
SELECT name, 'development' AS account FROM development.s3.buckets;

Referensi variabel lingkungan di-resolve dari lingkungan proses StackQL; tidak ada lingkungan lokal khusus sesi. Kredensial AWS sementara juga memerlukan field token sesi atau referensi variabel lingkungannya.

Alias berperilaku seperti provider asalnya untuk pernyataan metadata dan pernyataan data: SHOW, DESCRIBE, SELECT, INSERT, UPDATE, DELETE, dan EXEC semuanya menerima alias sebagai pengganti nama provider. Alias tidak berlaku untuk relasi native bawaan atau relasi IaC yang masih dalam pratinjau. Cabang UNION ALL yang menggunakan alias berbeda dijalankan secara berurutan.

Setiap kueri mengambil snapshot terpisah dari kredensial alias. Mengubah pengikatan memengaruhi kueri berikutnya, bukan kueri yang sedang berjalan. Pernyataan UNSET "$.providers.<alias>" menghapus pengikatan tersebut.

Mengganti field kredensial​

Pernyataan SET "$.auth.<provider>.<field>" mengubah satu field dari konteks autentikasi provider untuk sesi tersebut, dengan nama field berupa kunci dari entri --auth provider:

SET "$.auth.github.credentialsenvvar" = 'GITHUB_TOKEN_READONLY';
SELECT name FROM github.repos.repos WHERE org = 'stackql';
UNSET "$.auth.github.credentialsenvvar";

Seperti halnya alias, perubahan berlaku untuk kueri yang dimulai setelah pernyataan SET. Kueri terhadap provider yang autentikasinya telah dihapus, atau yang aliasnya tidak memiliki auth yang dapat digunakan, gagal sebelum permintaan apa pun dikirim.

Rahasia sesi​

Secara default, setiap sesi memiliki penyimpanan rahasia yang hanya berada di memori, tanpa perlu konfigurasi. Pernyataan SET "$.secrets.<name>" menyimpan string literal, biasanya dokumen autentikasi JSON, dan alias provider merujuknya dengan auth_secret:

SET "$.secrets.production" = '{"type":"aws_signing_v4","access_key_id_env_var":"PRODUCTION_AWS_ACCESS_KEY_ID","secret_access_key_env_var":"PRODUCTION_AWS_SECRET_ACCESS_KEY"}';
SET "$.providers.production" = '{"provider":"aws","tenancy":"production-account","auth_secret":"production","params":{"region":"ap-southeast-2"}}';

SELECT name FROM production.s3.buckets;

UNSET "$.secrets.production";

Merotasi rahasia memengaruhi kueri berikutnya; menghapusnya membuat penggunaan berikutnya gagal. Sesi baru menerima penyimpanan baru yang kosong, dan mengakhiri sesi akan melepaskannya. Pernyataan UNSET "$.secret_store" membuang pengikatan penyimpanan saat ini dan memulai lagi dengan memori sesi yang kosong.

Penggunaan kredensial biasa, serta pernyataan SET yang menyimpan variabel atau konfigurasi, tidak menulis rahasia ke backend SQL. Memasukkan data sensitif ke variabel atau tabel biasa merupakan tanggung jawab pemanggil.

Penyimpanan rahasia OS persisten​

Penyimpanan persisten dinonaktifkan secara default dan hanya dapat diaktifkan oleh operator yang menjalankan StackQL dengan --allow-persistent-secrets; SQL tidak dapat memberikannya. Jika flag tersebut digunakan, sesi memilih penyimpanan OS dengan:

SET "$.secret_store" = '{"backend": "os", "namespace": "stackql/provider-auth"}';

Penyimpanan tersebut adalah macOS Keychain, Linux Secret Service (secret-tool dengan layanan sesi yang berfungsi), atau Windows Credential Manager. Hanya backend os yang diterima: penyimpanan berbasis file datar, jalur file, dan fallback implisit apa pun ke file ditolak meskipun flag tersebut digunakan, dan fasilitas OS yang tidak tersedia akan gagal alih-alih beralih ke file.

Nilai yang ditulis ke penyimpanan OS bertahan lebih lama daripada sesi SQL dan dihapus secara eksplisit dengan UNSET "$.secrets.<name>". Mengatur ulang pengikatan penyimpanan tidak menghapus nilai yang sudah tersimpan secara persisten. Akses ke penyimpanan diatur oleh identitas sistem operasi dari proses StackQL; namespace bukan kontrol akses per pengguna, karena itu jangan perlakukan aktivasi eksplisit ini sebagai penyimpanan rahasia multipengguna.

Nilai rahasia di SQL​

Nilai rahasia tidak pernah didereferensi ke dalam SQL kecuali operator menjalankan StackQL dengan --allow-secret-dereference. Dengan flag tersebut, referensi seperti "$secrets.production", "$secrets.production.credentials", "$auth.github.password", dan "$providers.production.auth.credentials" di-resolve dalam ekspresi:

SELECT upper("$secrets.production.credentials") AS credential;

/*
-- the same statement in a session started without --allow-secret-dereference
SELECT upper("$secrets.production.credentials") AS credential;
-- FAILS with secret variable dereferencing is disabled
*/

Jika StackQL dijalankan tanpa flag tersebut, pernyataan yang sama ditolak sebelum apa pun dievaluasi, seperti yang ditunjukkan oleh salinan yang dijadikan komentar. Flag ini merupakan pengakuan bahwa nilai yang didereferensi secara eksplisit dapat masuk ke staging SQL, hasil, log, dan artefak kueri yang tersimpan secara persisten. Autentikasi provider biasa tidak memerlukannya.

Izin​

Jika manajemen akses diaktifkan, membaca variabel dan rahasia memerlukan session/variables:read, dan SET atau UNSET memerlukan session/config:write. Alias yang telah di-resolve diotorisasi sebagai provider kanonisnya sebelum eksekusi. Kepemilikan dan pemberian izin per variabel dan per rahasia tidak diimplementasikan.