Menjalankan kueri berparameter

Kueri berparameter memungkinkan Anda mempertahankan placeholder di SQL dan memberikan nilai saat dijalankan. Ekstensi PostgreSQL mengikat nilai-nilai tersebut sebagai parameter kueri; ini tidak menempelkan nilai ke dalam teks SQL.

Gunakan halaman ini saat Anda ingin menjalankan SQL yang disalin dari alat atau kode aplikasi yang menggunakan tempat penampung seperti :name, , $1atau ?.

Sintaks placeholder yang didukung

Editor kueri mendeteksi gaya placeholder ini di luar string, komentar, cast, irisan array, isi bertanda kutip dolar, dan operator JSON PostgreSQL.

Tempat penampung bernama

select id, email
from users
where id = :user_id;

Placeholder bernama membedakan huruf besar dan huruf kecil. Kemunculan berulang dengan nama yang sama menggunakan satu baris grid.

Tempat penampung posisi PostgreSQL

select id, email
from users
where id = $1;

$N placeholder bersifat posisional dalam pernyataan yang memuatnya.

Tempat penampung posisi Qmark

select id, email
from users
where active = ?;

? placeholder berfungsi dalam urutan dari kiri ke kanan. ? di posisi nilai mana pun berfungsi sebagai parameter, termasuk setelah operator perbandingan (>=, <=, <>), dalam cabang CASE, dan dalam LIMIT/OFFSET. Operator JSONB PostgreSQL ?, ?|, dan ?&, serta operator jalur JSON @?, dikenali sebagai operator, bukan parameter.

Important

Gunakan satu gaya placeholder dalam setiap pernyataan. Pernyataan yang mencampurkan :name dengan $N, atau mencampurkan $N dengan ?, akan ditolak sebelum dijalankan.

Buka dan gunakan tab Parameter

  1. Buka atau buat .sql file dan sambungkan ke database.
  2. Jalankan Jalankan Kueri Eksekusi (PostgreSQL), Jalankan Pernyataan Saat Ini (PostgreSQL), atau jalankan rentang SQL yang dipilih.
  3. Jika SQL berisi placeholder, tab Parameters akan dibuka di panel bawah.
  4. Masukkan nilai untuk setiap baris, pilih jenis jika diperlukan, dan pilih Jalankan kueri.
  5. Setelah eksekusi pertama, edit nilai dan pilih Jalankan lagi untuk mengulangi kueri.

Tab menampilkan satu baris untuk setiap placeholder bernama yang unik dan satu baris untuk setiap placeholder posisional. Setiap baris mencakup nama atau indeks placeholder, input nilai, kotak centang NULL, daftar tarik-turun tipe, dan aksi baris jika tersedia.

Skrip dengan beberapa pernyataan

Catatan (Mei 2026): versi sebelumnya dari artikel ini secara keliru menjelaskan indeks posisi sebagai tidak bergantung pada pernyataan. Perilaku tidak berubah; hanya dokumentasi yang dikoreksi.

Parameter posisional ($N, ?) berbagi array nilai tunggal di seluruh skrip yang dijalankan. $1 (atau yang pertama ?) dalam pernyataan apa pun selalu mengikat ke nilai yang sama seperti $1 dalam pernyataan lain. Menggunakan kembali indeks posisi yang sama di seluruh pernyataan tidak memberinya nilai independen. Jika Anda memerlukan nilai yang berbeda untuk indeks yang sama dalam pernyataan yang berbeda, gunakan parameter bernama (:name) sebagai gantinya.

Jika nilai bernama bersama tidak kompatibel dengan salah satu statemen yang menggunakannya, PostgreSQL menampilkan error dan grid tetap menyimpan nilai Anda sehingga Anda dapat menyesuaikannya dan menjalankannya lagi.

Nilai NULL

Gunakan kotak centang NULL untuk mengikat SQL NULL. Jika dicentang, kolom nilai diabaikan untuk baris itu.

Jika Anda mengetik teks literal NULL saat kotak centang NULL tidak dicentang, grid akan memperingatkan bahwa nilai tersebut diperlakukan sebagai teks NULL, bukan SQL NULL.

Pilih jenis parameter

Daftar tarik-turun jenis secara bawaan diatur ke auto, yang memungkinkan PostgreSQL menentukan jenis parameter. Pilih jenis saat Anda menginginkan validasi sisi klien atau pengikatan yang lebih jelas:

  • text
  • integer
  • bigint
  • numeric
  • boolean
  • date
  • timestamp
  • timestamptz
  • uuid
  • json
  • jsonb

Validasi bersifat lunak. Peringatan tidak memblokir pengiriman; PostgreSQL tetap menjadi validator akhir pada waktu eksekusi.

Membuat rencana kueri dengan parameter

Saat Anda memvisualisasikan rencana kueri untuk SQL yang berisi placeholder, tab Parameters digunakan untuk menjalankan visualisasi rencana kueri alih-alih mengembalikan baris hasil. Tombol Jalankan bertuliskan Visualisasikan Rencana Kueri, dan setelah pertama kali dijalankan, tombol tersebut bertuliskan Visualisasikan lagi. Masukkan nilai, lalu pilih tombol untuk menjalankan EXPLAIN dan membuka visualisasi rencana kueri. Jalur ini tidak mengembalikan hasil kueri.

Gunakan opsi Abaikan

Gunakan Abaikan saat kisi menunjukkan token yang harus tetap berada di SQL, seperti operator PostgreSQL yang valid. Abaikan diaktifkan hanya ketika token tetap valid SQL tanpa pengikatan.

Edit SQL dan jalankan lagi

Saat membuka tab Parameter , Anda dapat mengedit SQL dan memilih Jalankan lagi. Ekstensi mengekstrak ulang placeholder dan membandingkan SQL ber-template yang baru dengan fingerprint sebelumnya.

Jika kumpulan placeholder berubah, banner perubahan merangkum perubahan yang terjadi, seperti placeholder yang ditambahkan atau dihapus. Ekstensi menggabungkan nilai ke posisi berikutnya ketika placeholder masih cocok berdasarkan nama atau indeks posisi. Jika semua placeholder dihapus, grid akan ditutup dan kueri akan berjalan seperti biasa.

Membatalkan dan memulihkan transaksi

Saat eksekusi berparameter aktif, tombol jalankan berubah menjadi kontrol berhenti (berlabel Batal). Batal menghentikan batch yang sedang berjalan, melewati batch-batch berikutnya, dan membiarkan tab Parameters tetap terbuka dengan nilai-nilainya tetap tersimpan. Proses yang dibatalkan menampilkan status batch dibatalkan, bukan kegagalan, sehingga baris-barisnya tidak disorot sebagai kesalahan.

Ekstensi tidak memutar kembali transaksi yang dimulai pengguna secara otomatis. Jika pembatalan meninggalkan koneksi dalam status transaksi yang dibatalkan, tab Parameter menunjukkan pemberitahuan pemulihan dengan Jalankan ROLLBACK. Pilih opsi ini untuk mengirimkan satu ROLLBACK secara eksplisit pada koneksi yang sama, lalu jalankan skrip lagi.

Tinjau kegagalan dan coba lagi

Saat eksekusi berparameter gagal, tab Parameter menyimpan nilai Anda dan memperlihatkan status gagal dengan ringkasan kesalahan database. Pilih Lihat Pesan untuk membuka detail pesan lengkap.

Eksekusi yang dibatalkan menunjukkan status dibatalkan secara terpisah dari eksekusi yang gagal, dan batch yang kemudian tidak dijalankan ditandai sebagai dilewati.

Setelah Anda memperbaiki nilai atau jenis, pilih Jalankan lagi. Tab ini menghapus status kegagalan lama, status pembatalan, dan status sorotan baris untuk percobaan baru. Jika koneksi masih dalam transaksi yang dibatalkan, pemberitahuan pemulihan muncul lagi.

Retensi nilai riwayat kueri

Pengaturan pgsql.queryPlaceholders.historyValueRetention mengontrol apakah nilai parameter dipertahankan dalam riwayat kueri dalam memori sesi saat ini:

Nilai Behavior
ask Tanyakan setelah setiap eksekusi berparameter berhasil.
always Pertahankan nilai untuk entri riwayat selama sesi tanpa meminta konfirmasi.
never Pertahankan SQL templat saja.

Saat ask aktif, perintah yang ditampilkan setelah eksekusi berhasil menawarkan Simpan sekali (pertahankan entri ini saja), Selalu simpan (juga alihkan pengaturan ke always), Lewati (hanya SQL templat), dan Jangan tanya lagi (juga alihkan pengaturan ke never).

Nilai disimpan dalam memori saja dan dibersihkan saat Visual Studio Code memuat ulang atau ruang kerja berubah. Nilai parameter diredaksi dari telemetri dan log.

MENYIAPKAN peringatan

PREPARE ... AS SELECT $1 menggunakan sintaks posisi sisi server PostgreSQL. Ekstensi mendeteksi pernyataan PREPARE dan membiarkan placeholder di dalam body PREPARE untuk PostgreSQL alih-alih melakukan binding di sisi klien. Pernyataan lain dalam skrip yang sama diurai secara normal.

Kasus MVP yang tidak didukung

MVP tidak mencakup:

  • Riwayat nilai persisten berbasis disk.
  • Set parameter yang diberi nama atau disimpan di antara sesi editor.
  • Penggunaan ulang PREPARE/EXECUTE di sisi server sebagai eksekusi berparameter di sisi klien.
  • Komposit, array, bytea, rentang, interval, enum, atau jenis pengikatan lainnya di luar jenis daftar dropdown yang didukung.

Konten terkait

  • Last updated on