تشغيل الاستعلامات ذات المعلمات

تتيح لك الاستعلامات ذات المعلمات الاحتفاظ بالعناصر النائبة في SQL وتوفير القيم في وقت التشغيل. يربط ملحق PostgreSQL تلك القيم كمعلمات استعلام؛ لا يقوم بلصق القيم في نص SQL.

استخدم هذه الصفحة عندما تريد تشغيل SQL المنسخة من الأدوات أو التعليمات البرمجية للتطبيق التي تستخدم عناصر نائبة مثل :nameأو $1أو ?.

بناء جملة العناصر النائبة المدعومة

يكتشف محرر الاستعلام أنماط العناصر النائبة هذه خارج السلاسل والتعليقات والقوالب وشرائح الصفيف والهيئات المقتبسة بالدولار وعوامل تشغيل PostgreSQL JSON.

العناصر النائبة المسماة

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

العناصر النائبة المسماة حساسة لحالة الأحرف. التكرارات المتكررة لنفس الاسم تشترك في صف شبكة واحد.

العناصر النائبة الموضعية PostgreSQL

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

$N العناصر النائبة موضعية ضمن العبارة التي تحتوي عليها.

العناصر النائبة الموضعية لعلامة Qmark

select id, email
from users
where active = ?;

? تعمل العناصر النائبة بترتيب من اليسار إلى اليمين. ? يعمل في أي موضع قيمة كمعلمة، بما في ذلك بعد عوامل المقارنة (>=، و<=، <>و، و في CASE الفروع، و في/LIMITOFFSET . يتم التعرف على عوامل تشغيل ??|JSONB الخاصة ب PostgreSQL و و وعامل ?& تشغيل @? مسار JSON كعوامل تشغيل وليس معلمات.

هام

استخدم نمط عنصر نائب واحد لكل عبارة. يتم رفض العبارة التي تخلط :name مع $N، أو تخلط $N مع ?، قبل التنفيذ.

فتح علامة التبويب المعلمات واستخدامها

1. افتح ملفا .sql أو أنشئه وقم بتوصيله بقاعدة بيانات.
2. تشغيل استعلام التنفيذ (PostgreSQL) أو تنفيذ العبارة الحالية (PostgreSQL) أو تشغيل نطاق SQL محدد.
3. إذا كان SQL يحتوي على عناصر نائبة، يتم فتح علامة التبويب Parameters في اللوحة السفلية.
4. أدخل قيمة لكل صف، واختر نوعا إذا لزم الأمر، وحدد تشغيل الاستعلام.
5. بعد التشغيل الأول، قم بتحرير القيم وحدد Run مرة أخرى لتكرار الاستعلام.

المؤشر

تعرض علامة التبويب صفا واحدا لكل عنصر نائب فريد مسمى وصفا واحدا لكل عنصر نائب موضعي. يتضمن كل صف اسم العنصر النائب أو الفهرس وإدخال قيمة وخانة اختيار NULL وقائمة منسدلة للنوع وإجراءات الصف عند توفرها.

البرامج النصية متعددة العبارات

ملاحظة (مايو 2026): وصفت الإصدارات السابقة من هذه المقالة بشكل غير صحيح الفهارس الموضعية على أنها مستقلة عن كل عبارة. لم يتغير السلوك؛ يتم تصحيح الوثائق فقط.

تشترك المعلمات الموضعية ($N، ?) في صفيف قيمة واحدة عبر البرنامج النصي المنفذ. $1 (أو الأول ?) في أي عبارة ترتبط دائما بنفس القيمة كما هو الحال $1 في أي عبارة أخرى. لا تمنحهم إعادة استخدام نفس الفهرس الموضعي عبر العبارات قيما مستقلة. إذا كنت بحاجة إلى قيم مختلفة لنفس الفهرس في عبارات مختلفة، فاستخدم المعلمات المسماة (:name) بدلا من ذلك.

إذا كانت القيمة المسماة المشتركة غير متوافقة مع إحدى العبارات التي تستخدمها، فإن PostgreSQL ترجع الخطأ وتحتفظ الشبكة بقيمك حتى تتمكن من ضبطها وتشغيلها مرة أخرى.

القيم الخالية

استخدم خانة الاختيار NULL لربط SQL NULL. عند تحديده، يتم تجاهل حقل القيمة لهذا الصف.

إذا كتبت النص NULL الحرفي أثناء إيقاف تشغيل خانة الاختيار NULL ، تحذرك الشبكة من أن القيمة ترتبط كنص NULL، وليس SQL NULL.

اختيار أنواع المعلمات

يتم تعيين القائمة المنسدلة النوع افتراضيا إلى auto، مما يتيح ل PostgreSQL استنتاج نوع المعلمة. اختر نوعا عندما تريد التحقق من صحة العميل أو ربط أكثر وضوحا:

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

التحقق من الصحة بسيط. لا يمنع التحذير الإرسال؛ يظل PostgreSQL المدقق النهائي في وقت التنفيذ.

إنشاء خطة استعلام باستخدام المعلمات

عند تصور خطة استعلام ل SQL تحتوي على عناصر نائبة، تقوم علامة التبويب Parameters بمحرك العرض المصور لخطة الاستعلام بدلا من إرجاع الصفوف. يقرأ زر التشغيل Visualize Query Plan، وبعد التشغيل الأول يقرأ Visualize مرة أخرى. أدخل القيم وحدد الزر لتشغيل EXPLAIN العرض المصور لخطة الاستعلام وفتحه. لا يرجع هذا المسار نتائج الاستعلام.

استخدام تجاهل

استخدم تجاهل عندما تعرض الشبكة رمزا مميزا يجب أن يبقى في SQL، مثل عامل تشغيل PostgreSQL صالح. يتم تمكين تجاهل فقط عندما يظل الرمز المميز SQL صالحا دون ربط.

تحرير SQL وتشغيله مرة أخرى

عند فتح علامة التبويب Parameters ، يمكنك تحرير SQL وتحديد Run مرة أخرى. يقوم الملحق بإعادة استخراج العناصر النائبة ومقارنة SQL القالب الجديد ببصمة الإصبع السابقة.

إذا تغيرت مجموعة العناصر النائبة، يلخص شعار الانجراف ما تم تغييره، مثل العناصر النائبة التي تمت إضافتها أو إزالتها. يدمج الملحق القيم إلى الأمام عندما لا يزال العنصر النائب يتطابق حسب الاسم أو حسب الفهرس الموضعي. إذا تمت إزالة كافة العناصر النائبة، يتم إغلاق الشبكة ويتم تشغيل الاستعلام بشكل طبيعي.

إلغاء المعاملات واستردادها

بينما يكون التشغيل الذي له معلمات نشطا، يتغير زر التشغيل إلى عنصر تحكم إيقاف (المسمى إلغاء الأمر). يقاطع إلغاء الدفعة أثناء الطيران، ويتخطى الدفعات اللاحقة، ويترك علامة التبويب Parameters مفتوحة مع القيم سليمة. يظهر التشغيل الذي تم إلغاؤه حالة الدفعة الملغاة بدلا من الفشل، لذلك لا يتم تمييز صفوفه كأخطاء.

لا يقوم الملحق بالتراجع التلقائي للمعاملات التي بدأها المستخدم. إذا ترك الإلغاء الاتصال في حالة معاملة تم إجهاضها، تعرض علامة التبويب Parameters إشعار استرداد مع Execute ROLLBACK. حدده لإصدار واحد صريح ROLLBACK على نفس الاتصال، ثم قم بتشغيل البرنامج النصي مرة أخرى.

مراجعة حالات الفشل وإعادة المحاولة

عند فشل تشغيل ذي معلمات، تحتفظ علامة التبويب Parameters بقيمك وتعرض الحالة الفاشلة مع ملخص خطأ قاعدة البيانات. حدد عرض الرسائل لفتح تفاصيل الرسالة الكاملة.

تظهر عمليات التشغيل التي تم إلغاؤها الحالة الملغاة بشكل منفصل عن عمليات التشغيل الفاشلة، ويتم وضع علامة على الدفعات اللاحقة التي لم يتم تشغيلها على أنها تم تخطيها.

بعد إصلاح قيمة أو نوع، حدد تشغيل مرة أخرى. تمسح علامة التبويب الفشل الذي لا معنى له والإلغاء وحالة تمييز الصف للمحاولة الجديدة. إذا كان الاتصال لا يزال في معاملة تم إجهاضها، يظهر إشعار الاسترداد مرة أخرى.

استبقاء قيمة محفوظات الاستعلام

يتحكم الإعداد pgsql.queryPlaceholders.historyValueRetention في ما إذا كان يتم الاحتفاظ بقيم المعلمات في محفوظات الاستعلام في الذاكرة لجلسة العمل الحالية:

قيمة	السلوك
ask	اسأل بعد كل تشغيل ناجح له معلمات.
always	الاحتفاظ بالقيم لإدخالات المحفوظات في جلسة العمل دون المطالبة.
never	الاحتفاظ ب SQL المقالب فقط.

عندما ask تكون نشطة، فإن المطالبة التي تظهر بعد تشغيل ناجح تقدم حفظ مرة واحدة (الاحتفاظ بهذا الإدخال فقط)، والحفظ دائما (أيضا تبديل الإعداد إلى always)، وتخطي (SQL المقالب فقط)، ولا تسأل مرة أخرى (قم أيضا بتبديل الإعداد إلى never).

يتم الاحتفاظ بالقيم في الذاكرة فقط ويتم مسحها عند إعادة تحميل VS Code أو تغيير مساحة العمل. يتم تنقيح قيم المعلمات من بيانات تتبع الاستخدام والسجلات.

إعداد التحذير

PREPARE ... AS SELECT $1 يستخدم بناء جملة موضعية من جانب خادم PostgreSQL. يكتشف PREPARE الملحق العبارات ويترك العناصر النائبة PREPARE داخل النص الأساسي ل PostgreSQL بدلا من ربطها على العميل. يتم تحليل العبارات الأخرى في نفس البرنامج النصي بشكل طبيعي.

حالات MVP غير معتمدة

لا يتضمن MVP ما يلي:

• محفوظات ثابتة مدعومة بالقرص للقيم.
• مجموعات المعلمات المسماة أو المحفوظة عبر جلسات عمل المحرر.
• إعادة استخدام من جانب PREPARE/EXECUTE الخادم كتنفيذ ذي معلمات من جانب العميل.
• مركب أو صفيف أو بايت أو نطاق أو فاصل زمني أو تعداد أو ربط نوع آخر خارج أنواع القائمة المنسدلة المدعومة.

المحتوى ذو الصلة

• محرر الاستعلام وIntelliSense
• عرض مصور لخطة الاستعلام
• البدء السريع: الاتصال واستعلام PostgreSQL
• مرجع الإعدادات