GrafikQL
Postgres uzantı pg_graphql, proje başına katılım ve varsayılan olarak devre dışı. Etkinleştirildiğinde, özel /graphql yolları veya genel RPC proxy'si aracılığıyla RLS ve ayrı GraphQL kimlik doğrulaması olmayan rolleri devralarak REST API'nizle aynı şemayı ortaya çıkarır.
Ayrı bir hizmeti değil, aynı şemayı sorgulamanın ikinci bir yolu#
GraphQL, doğrudan kiracı veritabanınızdaki Postgres pg_graphql uzantısı tarafından desteklenir ve SQL tablolarınızdan, görünümlerinizden ve ilişkilerinizden bir GraphQL şeması oluşturur. Etkinleştirildiğinde, REST API'nizle aynı Postgres şeması üzerine ikinci bir sorgu yüzeyi eklenir; ayrı bir GraphQL sunucusu veya kimlik doğrulama katmanı olmadan tamamen aynı RLS politikalarını ve rollerini devralır.
Tüm projeler için varsayılan olarak devre dışıdır. Aurabase, proje başına açık katılım durumunda yalnızca pg_graphql 'yi etkinleştirir. Tam sorgu, filtre, imleç sayfalandırması ve mutasyon sözdizimi için resmi pg_graphql belgelerine bakın.
/graphql ve /rpc/graphql'de kullanıma sunulan bir SQL çözümleyici#
Bir projede GraphQL'in etkinleştirilmesi, tek bir işlemde pg_graphql yükler ve "<project_schema>".graphql(query, variables, operationName, extensions) oluşturur. Bir proje alt etki alanında, POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 ve POST /v1/db/{project_id}/graphql (ayrıca POST /v1/db/{project_id}/rpc/graphql) istekleri pg_graphql öğesine yönlendirilir ve REST { data, meta } olmadan standart { "data": ..., "errors": ... } GraphQL JSON yükünü doğrudan döndürür. sarıcı.
ACTIVATION ────▶ POST .../graphql/enable veya aura projeleri graphql-enable
ENQUEUE ────▶ "graphql_enable" işi sıraya alındı (idempotent, zaten etkinse işlem yok)
DDL ────▶ CREATE EXTENSION pg_graphql + sarmalayıcı işlevi + GRANT'lar, 1 tek işlem
FLAG ────▶ projeler.graphql_enabled = doğru, yalnızca işlemin tamamlanmasından sonra ayarlanır
QUERY ────▶ POST /graphql veya /v1/db/{project_id}/graphql (ham GraphQL JSON'u döndürür)
Etkinleştirme işlemi atomiktir: herhangi bir adım (uzantı, sarmalayıcı işlev veya GRANT'lar) başarısız olursa, her şey geri alınır ve graphql_enabled false olarak kalır.
Hangi aktivasyon ayarları#
- Otomatik olarak oluşturulan şema. pg_graphql, Postgres şemanızı inceler ve her tabloyu, varsayılan olarak
camelCase'ye eklenmiş SQLsnake_casesütunlarıyla bir Relay GraphQL türü (<table>Collection,edges,node) olarak kullanıma sunar — elle yazılacak SDL yoktur. - SECURITY INVOKER — Devralınan RLS. Sarma işlevi, arayanın ayrıcalıklarıyla (
aura_anon/aura_authenticated/aura_service_role) çalışır ve REST istekleriyle tamamen aynı RLS ilkelerini uygular. - Değiştirebileceğiniz üç ayar atomik olarak uygulanır.
introspection(varsayılan olarak kapalı:{ __schema { ... } }Unknown field "__schema"ile reddedilir, dolayısıyla GraphiQL ve Apollo codegen siz onu açana kadar şemayı keşfedemez),max_rows(koleksiyon başına döndürülen satırlar, 1 ila 10000, varsayılan 1000) veinflect_names(created_at→createdAt, varsayılan olarak açıktır). pg_graphqlCOMMENT ON SCHEMA … @graphql(...)tarifi bir projede çalışmaz (rolünüz şemanın sahibi değildir ve/raw,E'…'değişmezlerini reddeder): bunun yerineaura projects graphql-configveyaPATCH …/graphql/configkullanın, bkz. Ayarları ayarlayın. - Etkinleştirmeyi etkinleştirme, bağımsız.
POST .../graphql/enable(konsol JWT) veyaaura projects graphql-enable --wait(CLI), hazırlama işini gönderir ve--waitile GraphQL gerçekten etkinleştirildiğinde geri döner; hiçbir zaman otomatik olarak açılmaz. - Tüm Postgres katmanlarında mevcuttur. Projeniz ister bir kuruluş Postgres kümesinde ister özel bir Kurumsal kümede çalışıyor olsun çalışır; uçtan uca doğrulanmış (uzantı, RLS sarmalayıcı, gerçek sorgu).
- Yalnızca Postgres projeleri. Bir MongoDB projesi aktivasyonu reddediyor (
GRAPHQL_UNSUPPORTED_ENGINE).
Etkinleştirin, ardından sorgulayın#
# Idempotent: Halihazırda etkinleştirilmiş bir projede tekrarlanan bir çağrı, işlem yapılmaz.
# --wait, GraphQL gerçekten etkinleştirildiğinde geri döner (etkinleştirme bir arka plan işidir).
aura projects graphql-enable <project_id> --wait
Etkinleştirme, güncellenen projeyle yanıt verir (graphql_enabled: true). Sütun bükülmesine dikkat edin (created_at → createdAt): filtreler, orderBy, imleç sayfalandırması (first/after) ve mutasyonlar (insertInto<Table>Collection) için resmi pg_graphql API referansına bakın .
Ayarları düzenleyin: iç gözlem, maksimum satırlar, ad çekimi#
pg_graphql, ayarlarını projenizin şemasındaki bir yorumdan okur. Bunu yalnızca şema sahibi yazabilir, bu nedenle platform bunu siz istediğinizde tek bir işlemde sizin için yapar. Bir değişiklik önemsizdir (halihazırda uygulanmış olanı istemek hiçbir şey yapmaz) ve sınırlıdır (1–10000 dışındaki max_rows herhangi bir şey kuyruğa alınmadan önce reddedilir).
# Geçerli ayarları göster
aura projects graphql-config <project_id>
# İç gözlemi açın (GraphiQL, graphql-codegen, Apollo), uygulanana kadar bekleyin
aura projects graphql-config <project_id> --introspection on --wait
# Koleksiyonları 100 satırla sınırlandırın ve SQL adlarını olduğu gibi tutun
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state değişiklik hakkındaki gerçeği söyler: pending uygulanırken (pending_config ile), failed eğer olamıyorsa (config içindeki ayarlar o zaman hala geçerli olanlardır), aksi takdirde applied. Önce GraphQL etkinleştirilmelidir (aksi takdirde GRAPHQL_NOT_ENABLED) ve yanıtlar beklenirken ikinci bir değişiklik GRAPHQL_CONFIG_PENDING: birkaç saniye içinde yeniden deneyin.
introspection açıkken, projenin genel anahtarını elinde bulunduran herkes GraphQL'in sunduğu her tablo ve sütunu listeleyebilir (RLS hala satırları korur). Şemanızın şekli hassassa geliştirme için açın ve üretim için tekrar kapatın.
Dikkat edilecek noktalar#
Varsayılan olarak pg_graphql, SQL snake_case adlarını GraphQL camelCase'ye dönüştürür (created_at createdAt olur, blog_posts tablosu blogPostsCollection olur). DDL değişikliklerinden sonra PostgREST şema önbelleğini saniyeler içinde yeniden yükler, böylece hem /graphql hem de /rpc/graphql güncellenmiş alanları ortaya çıkarır.
Daha ileri gitmek için#
- Veritabanı
Postgres yönetildi, uzantılar etkinleştirildi, RLS — pg_graphql'nin kullanıma sunduğu şema.
- Bir Postgres işlevini çağırın
GraphQL sorguları tarafından kullanılan genel RPC proxy'si (/rpc/{function}).
- Güvenlik ve RBAC
RLS, anon/authenticated/service_role rolleri — GraphQL tarafından devralınan model.
- CLI
aura projeleri graphql-enable ve projelerin geri kalan komutları.