Parametreli sorguları çalıştırma

Parametreli sorgular, yer tutucuları SQL'de tutmanıza ve çalışma zamanında değerler sağlamanıza olanak sağlar. PostgreSQL uzantısı bu değerleri sorgu parametreleri olarak bağlar; DEĞERLERI SQL metnine yapıştırmaz.

, :nameveya $1gibi ?yer tutucuları kullanan araçlardan veya uygulama kodundan kopyalanan SQL'i çalıştırmak istediğinizde bu sayfayı kullanın.

Desteklenen yer tutucu söz dizimleri

Sorgu düzenleyicisi bu yer tutucu stilleri dizeler, açıklamalar, atamalar, dizi dilimleri, dolar tırnak içine alınmış gövdeler ve PostgreSQL JSON işleçleri dışında algılar.

Adlandırılmış yer tutucular

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

Adlandırılmış yer tutucular büyük/küçük harfe duyarlıdır. Aynı adın tekrarlanan örnekleri aynı ızgara satırını paylaşır.

PostgreSQL konumsal yer tutucuları

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

$N yer tutucular, bunları içeren ifade içinde konuma bağlıdır.

Qmark konumlu yer tutucuları

select id, email
from users
where active = ?;

? yer tutucuları soldan sağa sırayla çalışır. A ?, karşılaştırma işleçlerinden (>=, <=, <>) sonra, CASE dallarında ve LIMIT/OFFSET içinde olmak üzere, herhangi bir değer konumunda parametre olarak işlev görür. PostgreSQL'in JSONB işleçleri ?, ?|ve ?& JSON yol işleci @? parametre olarak değil işleç olarak kabul edilir.

Important

Deyim başına bir yer tutucu stili kullanın. :name ile $N’i veya $N ile ?’ü karıştıran bir ifade, yürütülmeden önce reddedilir.

Parametreler sekmesini açma ve kullanma

  1. Bir .sql dosya açın veya oluşturun ve bir veritabanına bağlayın.
  2. Execute Query (PostgreSQL), Execute Current Statement (PostgreSQL) veya seçili bir SQL aralığını çalıştırın.
  3. SQL yer tutucular içeriyorsa, parametreler sekmesi alt panelde açılır.
  4. Her satır için bir değer girin, gerekirse bir tür seçin ve Sorguyu çalıştır'ı seçin.
  5. İlk çalıştırmadan sonra değerleri düzenleyin ve sorguyu yinelemek için yeniden Çalıştır'ı seçin.

Sekmede, her benzersiz adlandırılmış yer tutucu için bir satır ve her konumsal yer tutucu için bir satır gösterilir. Her satırda yer tutucu adı veya dizin, bir değer girişi, NULL onay kutusu, bir tür açılır listesi ve varsa satır eylemleri bulunur.

Çok deyimli betikler

Not (Mayıs 2026): Bu makalenin önceki sürümlerinde deyim başına bağımsız konumsal dizinler yanlış şekilde açıklanmıştır. Davranış değişmedi; yalnızca belgeler düzeltildi.

Konumsal parametreler ($N, ?) yürütülen betikte tek bir değer dizisi paylaşır. Herhangi bir deyimdeki $1 (veya ilk ?), başka herhangi bir deyimdeki $1 ile her zaman aynı değere bağlanır. Deyimler arasında aynı konumsal dizini yeniden kullanmanız onlara bağımsız değerler vermez. Farklı deyimlerde aynı dizin için farklı değerlere ihtiyacınız varsa, bunun yerine adlandırılmış parametreleri (:name) kullanın.

Paylaşılan adlandırılmış değer onu kullanan deyimlerden biriyle uyumlu değilse PostgreSQL hatayı döndürür ve kılavuz değerlerinizi korur, böylece yeniden ayarlayıp çalıştırabilirsiniz.

NULL değerler

SQL'i bağlamak için NULL onay kutusunu kullanın. İşaretlendiğinde, değer alanı o satırda göz ardı edilir.

NULL onay kutusu kapalıyken değişmez metni yazarsanız, kılavuz değerin SQL NULLdeğil metin NULLolarak bağlandığı konusunda sizi uyarır.

Parametre türlerini seçme

Tür açılır listesi varsayılan olarak auto seçilidir; bu, PostgreSQL’in parametre türünü belirlemesine olanak tanır. İstemci tarafı doğrulaması veya daha net bağlama istediğinizde bir tür seçin:

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

Doğrulama esnektir. Uyarı gönderimi engellemez; PostgreSQL yürütme zamanında son doğrulayıcı olmaya devam eder.

Parametrelerle sorgu planı oluşturma

Yer tutucular içeren sql için bir sorgu planı görselleştirdiğinizde, Parametreler sekmesi satır döndürmek yerine sorgu planı görselleştiricisini kullanır. Çalıştır düğmesi Sorgu Planını Görselleştir'i okur ve ilk çalıştırmadan sonra yeniden Görselleştir'i okur. Değerleri girin ve çalıştırılacak EXPLAIN düğmeyi seçin ve sorgu planı görselleştiricisini açın. Bu yol sorgu sonuçlarını döndürmez.

Yok say seçeneğini kullan

Tablo, geçerli bir PostgreSQL işleci gibi SQL'de kalması gereken bir belirteç gösterdiğinde Ignore seçeneğini kullanın. Yoksay, yalnızca belirteç bağlama yapılmadan geçerli bir SQL ifadesi olarak kaldığında etkinleştirilir.

SQL'i düzenleme ve yeniden çalıştırma

Parametreler sekmesini açtığınızda SQL'i düzenleyebilir ve yeniden Çalıştır'ı seçebilirsiniz. Uzantı, yer tutucuları yeniden ayıklar ve yeni şablonlanmış SQL'i önceki parmak iziyle karşılaştırır.

Yer tutucu kümesi değiştiyse, kayma başlığı eklenen veya kaldırılan yer tutucular gibi değişenleri özetler. Yer tutucu ad veya konumsal dizin açısından hâlâ eşleşiyorsa, uzantı değerleri ileriye doğru birleştirir. Tüm yer tutucular kaldırılırsa kılavuz kapatılır ve sorgu normal şekilde çalışır.

İşlemleri iptal etme ve kurtarma

Parametreli çalıştırma etkinken, çalıştırma düğmesi durdurma denetimine ( İptal etiketli) dönüşür. İptal, uçuş içi toplu işlemi kesintiye uğratır, sonraki toplu işlemleri atlar ve Parametreler sekmesini değerler olduğu gibi açık bırakır. İptal edilen çalıştırma, hata yerine iptal edilen toplu iş durumunu gösterir, bu nedenle satırları hata olarak vurgulanmaz.

Uzantı, kullanıcı tarafından başlatılan işlemleri otomatik olarak geri almaz. İptal işlemi bağlantıyı iptal edilmiş işlem durumunda bırakırsa, Parameters sekmesinde Çalıştır ROLLBACK ile bir kurtarma bildirimi gösterilir. Aynı bağlantı üzerinden bir açık ROLLBACK göndermek için bunu seçin, ardından betiği yeniden çalıştırın.

Hataları gözden geçirme ve yeniden deneme

Parametreli çalıştırma başarısız olduğunda , Parametreler sekmesi değerlerinizi tutar ve veritabanı hata özetiyle başarısız durumu gösterir. İleti ayrıntılarının tamamını açmak için İletileri Gör'e tıklayın.

İptal edilen çalışmalar, başarısız çalışmalardan ayrı olarak iptal edildi durumunda gösterilir ve daha sonra çalıştırılmayan toplu işlemler atlandı olarak işaretlenir.

Bir değeri veya türü düzeltdikten sonra yeniden Çalıştır'ı seçin. Sekme, yeni deneme için eski hata, iptal ve satır vurgulama durumunu temizler. Bağlantı hala durdurulan bir işlemdeyse kurtarma bildirimi yeniden görünür.

Sorgu geçmişi değeri saklama

Ayar pgsql.queryPlaceholders.historyValueRetention , parametre değerlerinin geçerli oturumun bellek içi sorgu geçmişinde tutulup tutulmayacağını denetler:

Value Davranış
ask Her başarılı parametreli çalıştırmadan sonra sor.
always İstenmeden oturum geçmişi girdilerinin değerlerini koruyun.
never Yalnızca şablonlu SQL'i koruyun.

Etkin olduğunda ask , başarılı bir çalıştırmadan sonra gösterilen istem bir kez kaydet (yalnızca bu girdiyi koru), Her zaman kaydet (ayrıca ayarı alwaysolarak değiştir ), Atla (yalnızca şablonlu SQL) ve Bir daha sorma (ayarı neverolarak da değiştirin) sunar.

Değerler yalnızca bellekte tutulur ve VS Code yeniden yüklendiğinde veya çalışma alanı değiştiğinde temizlenir. Parametre değerleri telemetri ve günlüklerden gizlenir.

PREPARE uyarı

PREPARE ... AS SELECT $1 PostgreSQL sunucu tarafı konumsal söz dizimlerini kullanır. Uzantı, PREPARE deyimlerini algılar ve bunları istemci tarafında bağlamak yerine PostgreSQL için yer tutucuları PREPARE gövdesinin içinde bırakır. Aynı betikteki diğer ifadeler normal şekilde ayrıştırılır.

Desteklenmeyen MVP durumları

MVP şunları içermez:

  • Disk üzerinde tutulan kalıcı değer geçmişi.
  • Düzenleyici oturumlarında adlandırılmış veya kaydedilmiş parametre kümeleri.
  • Sunucu tarafı PREPARE/EXECUTE yeniden kullanımı, istemci tarafında parametreli çalıştırma olarak.
  • Desteklenen açılır liste türlerinin ötesinde composite, array, bytea, range, interval, enum veya başka bir tür bağı.

İlgili içerik

  • Last updated on