تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
srv
الأمر المستخدم لتشغيل StackQL كخدمة يمكن بعد ذلك الوصول إليها من خلال عملاء بروتوكول الاتصال الخاص بـ Postgres الذين تتم مصادقتهم باستخدام mTLS. يمكن للأمر srv أيضًا تشغيل خادم Model Context Protocol (MCP) إلى جانب خادم بروتوكول الاتصال الخاص بـ PostgreSQL، مما يتيح الوصول عبر بروتوكولين لكل من عملاء قواعد البيانات التقليدية ووكلاء الذكاء الاصطناعي.
بناء الجملة
stackql srv [server_options] [flags]
على الرغم من أن خادم StackQL يستخدم بروتوكول الاتصال الخاص بـ Postgres، فإنه ليس خادم Postgres ولا يتطلب وجود خادم منه. يستخدم العميل بروتوكول الاتصال للتواصل مع الخادم، الذي يستخدم StackQL لتنفيذ الاستعلامات أو عمليات DML على مزودي الخدمات السحابية ومزودي خدمات SaaS البعيدين وإعادة النتائج إلى العميل.
يتم ربط المعلمات المرسلة عبر بروتوكول الاستعلام الموسع (Parse / Bind / Execute، كما يستخدمه psycopg 3 وpgx وJDBC) على جانب الخادم كقيم حرفية نصية. بدءًا من v0.12.742، يبقى العنصر النائب $n الموجود داخل قيمة حرفية نصية أو معرف بين علامتي اقتباس أو تعليق دون تغيير، ويتم إلغاء الشرطات المائلة العكسية في قيم المعلمات، وتبقى القيمة النصية NULL هي السلسلة النصية NULL (يتم نقل قيمة SQL NULL بشكل منفصل).
خيارات الخادم
| الخيار | الوصف | القيمة الافتراضية |
|---|---|---|
--pgsrv.address | العنوان الذي يستمع عليه الخادم. | 0.0.0.0 |
--pgsrv.port | منفذ TCP الذي يستمع عليه الخادم. | 5466 |
--pgsrv.tls | كائن تكوين TLS بتنسيق JSON. راجع مثال mTLS أدناه. | لا يوجد |
--pgsrv.debug.enable | تمكين إخراج تصحيح أخطاء الاستعلامات لعملاء PostgreSQL، على سبيل المثال باستخدام stackql srv --pgsrv.debug.enable=true. اترك هذا الخيار دون تمكين ما لم يكن من المفترض أن يتلقى العملاء معلومات تصحيح الأخطاء. | false |
--pgsrv.sundry | تعيين متقدم بتنسيق JSON أو YAML يتم تمريره إلى خادم بروتوكول الاتصال الخاص بـ PostgreSQL فقط عندما لا يتم تحديد الخيار --pgsrv.tls. | {} |
--pgsrv.loglevel | مقبول لكنه لا يعين مستوى أداة التسجيل في المحرك الحالي. استخدم --loglevel بدلًا من ذلك. | WARN |
راجع العلامات العامة للاطلاع على خيارات إضافية
خيارات خادم MCP
عند تشغيل الأمر srv مع دعم MCP، تتوفر الخيارات الإضافية التالية:
| الخيار | الوصف |
|---|---|
--mcp.server.type | نوع خادم MCP: http (في الذاكرة) أو reverse_proxy (يعتمد على TCP) |
--mcp.config | كائن تكوين بتنسيق JSON لخادم MCP (راجع وثائق MCP) |
--mcp.log.format | ترميز سجل تدقيق MCP: jsonl (افتراضي) أو otel (إدخالات سجل OTLP/JSON)؛ يتجاوز server.audit.format في كائن التكوين |
--mcp.protocol.version | أحدث مراجعة لبروتوكول MCP يتم الإعلان عنها: auto (افتراضي)، أو 2026-07-28 (بدون جلسات فقط)، أو مراجعة أقدم مثل 2025-11-25؛ يتجاوز server.protocol_version في كائن التكوين |
بدءًا من v0.12.742، ترفض وسيلة النقل HTTP في MCP (--mcp.server.type=http أو reverse_proxy) بدء التشغيل إلا إذا حدد كائن التكوين الرمز المميز من نوع bearer باستخدام server.auth_token_env_var أو اختار بشكل صريح الاستغناء عن المصادقة باستخدام "allow_unauthenticated": true. راجع مصادقة عملاء HTTP.
راجع وثائق أمر MCP للحصول على معلومات مفصلة حول تكوين خادم MCP واستخدامه، بما في ذلك أوضاع النشر وخيارات التكوين والتكامل مع مساعدي الذكاء الاصطناعي.
يجب عليك تعيين متغيرات البيئة المطلوبة لمصادقة الموفرين قبل بدء تشغيل الخادم، وراجع استخدام موفر لمزيد من المعلومات.
بالنسبة إلى الخوادم التي تعمل لفترات طويلة، تتيح لك العلامة --env.file وضع بيانات الاعتماد أو تدويرها في ملف بنمط dotenv على القرص قبل بدء التشغيل بدلًا من تصدير المتغيرات إلى واجهة الأوامر:
stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env
بالنسبة إلى الأمر stackql srv، تتم قراءة الملف مرة واحدة عند بدء التشغيل؛ ووسيلة إعادة التحميل أثناء الجلسة هي أداة MCP reload_credentials.
العلامات
| العلامة | الوصف |
|---|---|
-h,--help | طباعة معلومات المساعدة |
-v,--verbose | تشغيل الاستعلامات في الوضع المفصل مع إرسال إخراج إضافي إلى stdout، وإذا تم تعيين العلامة العامة -f (--outfile)فستتم كتابة معلومات التسجيل الإضافية هذه في ملف الإخراج مع نتائج الاستعلام |
راجع العلامات العامة للاطلاع على خيارات إضافية
أمثلة
تشغيل عملية خادم StackQL والاتصال باستخدام عميل سطر الأوامر psql.
أولًا، نزّل ملف التكوين openssl.cnf من stackql/stackql.
بعد ذلك، أنشئ ملفات الشهادة والمفتاح التي سيستخدمها الخادم والعميل لمصادقة TLS المتبادل (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
الآن عيّن متغيرات البيئة، وإذا كان العميل والخادم على الجهاز نفسه، فيمكن مشاركتها.
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
عيّن بيانات الاعتماد للموفرين الذين يحتاجهم الخادم. بالنسبة إلى GitHub، يقرأ الموفر اسم المستخدم والرمز المميز للوصول الشخصي من هذين المتغيرين:
export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken
الآن ابدأ تشغيل الخادم في إحدى الوحدات الطرفية.
stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'
في وحدة طرفية أخرى، اتصل بالخادم باستخدام عميل سطر الأوامر psql.
psql -h 127.0.0.1 -d stackql
الآن شغّل استعلام StackQL على موفر تمت مصادقته.
psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.
stackql=> SHOW SERVICES IN github LIKE '%repos%';
id | name | title
--------------+-------+----------------------------
repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)
stackql=>