GraphQL
Postgres الامتداد pg_graphql، يتم الاشتراك فيه لكل مشروع ويتم تعطيله افتراضيًا. بمجرد تمكينه، فإنه يكشف نفس المخطط مثل REST API الخاص بك - وراثة RLS والأدوار بدون مصادقة GraphQL منفصلة - عبر مسارات /graphql مخصصة أو وكيل RPC العام.
طريقة ثانية للاستعلام عن نفس المخطط، وليس خدمة منفصلة#
يتم تشغيل GraphQL مباشرة بواسطة الامتداد Postgres pg_graphql داخل قاعدة بيانات المستأجر، مما يؤدي إلى إنشاء مخطط GraphQL من جداول SQL وطرق العرض والعلاقات. يؤدي تمكينها إلى إضافة سطح استعلام ثانٍ فوق نفس مخطط Postgres مثل REST API - وراثة نفس سياسات وأدوار RLS تمامًا، بدون خادم GraphQL منفصل أو طبقة مصادقة.
معطل بشكل افتراضي لجميع المشاريع. يقوم Aurabase بتنشيط pg_graphql فقط عند الاشتراك الصريح لكل مشروع. راجع المستندات الرسمية pg_graphql للاستعلام الكامل والتصفية وترقيم الصفحات للمؤشر وبناء جملة الطفرة.
محلل SQL مكشوف على /graphql و/rpc/graphql#
يؤدي تمكين GraphQL في مشروع إلى تثبيت pg_graphql وإنشاء "<project_schema>".graphql(query, variables, operationName, extensions) في معاملة واحدة. في المجال الفرعي للمشروع، يتم توجيه الطلبات إلى POST /graphql و POST /graphql/v1 و POST /v1/graphql و POST /v1/graphql/v1 و POST /v1/db/{project_id}/graphql (بالإضافة إلى POST /v1/db/{project_id}/rpc/graphql) إلى pg_graphql وإرجاع حمولة { "data": ..., "errors": ... } القياسية GraphQL JSON مباشرة بدون REST { data, meta } المجمع.
ACTIVATION ────▶ POST .../graphql/enable أو مشاريع الهالة graphql-enable
ENQUEUE ────▶ الوظيفة "graphql_enable" في قائمة الانتظار (غير فعالة، غير قابلة للتشغيل إذا كانت ممكّنة بالفعل)
DDL ────▶ إنشاء امتداد pg_graphql + وظيفة التغليف + المنح، معاملة واحدة واحدة
FLAG ────▶ project.graphql_enabled = true، يتم تعيينه فقط بعد الالتزام الكامل بالمعاملة
QUERY ────▶ POST /graphql أو /v1/db/{project_id}/graphql (إرجاع GraphQL JSON الخام)
معاملة التنشيط ذرية: إذا فشلت أي خطوة (ملحق أو وظيفة مجمعة أو منح)، فسيتم التراجع عن كل شيء ويبقى graphql_enabled false.
ما التنشيط يحدد#
- المخطط الذي تم إنشاؤه تلقائيًا. pg_graphql يتأمل مخطط Postgres الخاص بك ويكشف كل جدول كنوع Relay GraphQL (
<table>Collection,edges,node) مع أعمدة SQLsnake_caseالتي تم تحويلها إلىcamelCaseافتراضيًا - لا يوجد SDL للكتابة يدويًا. - مستحضر الأمان — موروث RLS. تعمل وظيفة التغليف بامتيازات المتصل (
aura_anon/aura_authenticated/aura_service_role)، وتفرض نفس سياسات RLS تمامًا مثل طلبات REST. - ثلاثة إعدادات يمكنك تغييرها، ويتم تطبيقها ذريًا.
introspection(إيقاف التشغيل بشكل افتراضي:{ __schema { ... } }يتم رفضه معUnknown field "__schema"، لذلك لا يتمكن برنامج GraphiQL وApollo codegen من اكتشاف المخطط حتى تقوم بتشغيله)،max_rows(يتم إرجاع الصفوف لكل مجموعة، من 1 إلى 10000، افتراضي 1000) وinflect_names(created_at→createdAt، قيد التشغيل افتراضيًا). الوصفة pg_graphqlCOMMENT ON SCHEMA … @graphql(...)لا تعمل من مشروع (دورك لا يمتلك المخطط، و/rawيرفضE'…'literals): استخدمaura projects graphql-configأوPATCH …/graphql/configبدلاً من ذلك، راجع ضبط الإعدادات. - تفعيل الاشتراك، غير فعال. يقوم
POST .../graphql/enable(وحدة التحكم JWT) أوaura projects graphql-enable --wait(CLI) بإرسال مهمة التزويد، وباستخدام--wait، يعود بمجرد تمكين GraphQL فعليًا؛ لم يتم تشغيله تلقائيًا أبدًا. - متوفر في جميع مستويات Postgres. يعمل سواء كان مشروعك يعمل على مجموعة مؤسسة Postgres أو مجموعة مؤسسة مخصصة؛ تم التحقق من صحته من النهاية إلى النهاية (الامتداد، RLS المجمع، الاستعلام الحقيقي).
- Postgres مشاريع فقط. يرفض مشروع MongoDB التنشيط (
GRAPHQL_UNSUPPORTED_ENGINE).
قم بالتفعيل ثم الاستعلام#
# Idempotent: يعد الاتصال المتكرر بمشروع ممكّن بالفعل أمرًا محظورًا.
# --wait يعود بمجرد تمكين GraphQL فعليًا (التنشيط عبارة عن مهمة في الخلفية).
aura projects graphql-enable <project_id> --wait
يستجيب التنشيط بالمشروع المحدث (graphql_enabled: true). ملاحظة انعطاف عمود الإشعار (created_at → createdAt): راجع مرجع الرسمي pg_graphql API للمرشحات، orderBy وترقيم الصفحات للمؤشر (first/after) والطفرات (insertInto<Table>Collection).
قم بضبط الإعدادات: الاستبطان والحد الأقصى للصفوف وتصريف الاسم#
يقرأ pg_graphql إعداداته من تعليق على مخطط مشروعك. يمكن لمالك المخطط فقط كتابته، وبالتالي تقوم المنصة بذلك نيابةً عنك، في معاملة واحدة، عندما تطلب ذلك. التغيير غير فعال (السؤال عما تم تطبيقه بالفعل لا يفعل شيئًا) ومحدودًا (يتم رفض max_rows خارج 1-10000 قبل وضع أي شيء في قائمة الانتظار).
# إظهار الإعدادات السارية
aura projects graphql-config <project_id>
# قم بتشغيل الاستبطان (GraphiQL، graphql-codegen، Apollo)، انتظر حتى يتم تطبيقه
aura projects graphql-config <project_id> --introspection on --wait
# قم بتغطية المجموعات بـ 100 صف واحتفظ بأسماء SQL كما هي
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state يخبرنا بالحقيقة حول التغيير: pending أثناء تطبيقه (مع pending_config)، failed إذا لم يكن من الممكن أن يكون (الإعدادات في config لا تزال سارية)، applied بخلاف ذلك. يجب تمكين GraphQL أولاً (GRAPHQL_NOT_ENABLED بخلاف ذلك)، وإجراء تغيير ثانٍ أثناء انتظار الإجابات GRAPHQL_CONFIG_PENDING: أعد المحاولة خلال بضع ثوانٍ.
مع تشغيل introspection، يمكن لأي شخص يحمل المفتاح العام للمشروع إدراج كل جدول وعمود يعرضه GraphQL (لا يزال RLS يحمي الصفوف). قم بتشغيله للتطوير، ثم قم بإيقاف تشغيله مرة أخرى للإنتاج إذا كان شكل مخططك حساسًا.
نقاط الاهتمام#
افتراضيًا، يقوم pg_graphql بتحويل أسماء SQL snake_case إلى GraphQL camelCase (created_at يصبح createdAt، الجدول blog_posts يصبح blogPostsCollection). بعد تغييرات DDL، يقوم PostgREST بإعادة تحميل ذاكرة التخزين المؤقت للمخطط الخاص به خلال ثوانٍ حتى يعرض كل من /graphql و/rpc/graphql الحقول المحدثة.
للذهاب أبعد من ذلك#
- قاعدة البيانات
تمت إدارة Postgres، وتمكين الامتدادات، RLS - المخطط الذي يكشفه pg_graphql.
- استدعاء وظيفة Postgres
وكيل RPC العام (/rpc/{function}) المستخدم بواسطة استعلامات GraphQL.
- الأمن وRBAC
RLS، الأدوار المجهولة/المصادقة/service_role — النموذج الموروث كما هو بواسطة GraphQL.
- سطر الأوامر
مشاريع Aura graphql-enable وأوامر بقية المشاريع.