WykresQL
Postgres rozszerzenie pg_graphql, opcja opt-in dla każdego projektu i domyślnie wyłączona. Po włączeniu udostępnia ten sam schemat, co interfejs API REST — dziedzicząc RLS i role bez oddzielnego uwierzytelniania GraphQL — za pośrednictwem dedykowanych tras /graphql lub ogólnego serwera proxy RPC.
Drugi sposób wysyłania zapytań do tego samego schematu, a nie do osobnej usługi#
GraphQL jest obsługiwany bezpośrednio przez rozszerzenie Postgres pg_graphql w bazie danych dzierżawy, generując schemat GraphQL na podstawie tabel, widoków i relacji SQL. Włączenie tej opcji powoduje dodanie drugiej powierzchni zapytań na tym samym schemacie Postgres co interfejs API REST — dziedziczenie dokładnie tych samych zasad i ról RLS, bez oddzielnego serwera GraphQL lub warstwy autoryzacji.
Domyślnie wyłączone dla wszystkich projektów. Aurabase aktywuje pg_graphql tylko po wyraźnej zgodzie na projekt. Zobacz oficjalną dokumentację pg_graphql, aby zapoznać się z pełnymi zapytaniami, filtrami, paginacją kursorów i składnią mutacji.
Mechanizm rozpoznawania nazw SQL udostępniony w /graphql i /rpc/graphql#
Włączenie GraphQL w projekcie instaluje pg_graphql i tworzy "<project_schema>".graphql(query, variables, operationName, extensions) w pojedynczej transakcji. W subdomenie projektu żądania do POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1 i POST /v1/db/{project_id}/graphql (a także POST /v1/db/{project_id}/rpc/graphql) są kierowane do pg_graphql i zwracają standardowy ładunek JSON { "data": ..., "errors": ... } GraphQL bezpośrednio bez opakowania REST { data, meta }.
ACTIVATION ────▶ POST .../graphql/enable lub projekty aura graphql-enable
ENQUEUE ────▶ zadanie „graphql_enable” w kolejce (idempotent, no-op, jeśli jest już włączone)
DDL ────▶ UTWÓRZ ROZSZERZENIE pg_graphql + funkcja opakowania + GRANT, 1 pojedyncza transakcja
FLAG ────▶ projekty.graphql_enabled = true, ustawiane dopiero po zatwierdzeniu pełnej transakcji
QUERY ────▶ POST /graphql lub /v1/db/{project_id}/graphql (zwraca surowy plik GraphQL JSON)
Transakcja aktywacji jest niepodzielna: jeśli jakikolwiek krok (rozszerzenie, funkcja opakowania lub GRANT) zakończy się niepowodzeniem, wszystko zostanie cofnięte, a graphql_enabled pozostanie false.
Co konfiguruje aktywacja#
- Automatycznie wygenerowany schemat. pg_graphql dokonuje introspekcji schematu Postgres i udostępnia każdą tabelę jako typ Relay GraphQL (
<table>Collection,edges,node) z kolumnami SQLsnake_caseodmienionymi domyślnie nacamelCase— brak SDL do ręcznego zapisu. - WYWOŁYWACZ ZABEZPIECZEŃ — Dziedziczony RLS. Funkcja opakowania działa z uprawnieniami osoby wywołującej (
aura_anon/aura_authenticated/aura_service_role), wymuszając dokładnie te same zasady RLS co żądania REST. - Trzy ustawienia, które możesz zmienić, stosowane pojedynczo.
introspection(domyślnie wyłączone:{ __schema { ... } }jest odrzucane za pomocąUnknown field "__schema", więc generator kodów GraphiQL i Apollo nie może wykryć schematu, dopóki go nie włączysz),max_rows(wiersze zwracane na kolekcję, od 1 do 10000, domyślnie 1000) iinflect_names(created_at→createdAt, wł. domyślny). Przepis pg_graphqlCOMMENT ON SCHEMA … @graphql(...)nie działa z projektu (twoja rola nie jest właścicielem schematu, a/rawodmawia literałówE'…'): użyj zamiast tegoaura projects graphql-configlubPATCH …/graphql/config, zobacz Dostosuj ustawienia. - Aktywacja zgody, idempotentna.
POST .../graphql/enable(konsola JWT) lubaura projects graphql-enable --wait(CLI) wywołuje zadanie udostępniania i, z--wait, powraca po faktycznym włączeniu GraphQL; nigdy nie włączał się automatycznie. - Dostępne na wszystkich poziomach Postgres. Działa niezależnie od tego, czy projekt działa w klastrze Postgres organizacji, czy w dedykowanym klastrze Enterprise; zweryfikowane od początku do końca (rozszerzenie, opakowanie RLS, prawdziwe zapytanie).
- Tylko projekty Postgres. Projekt MongoDB odmawia aktywacji (
GRAPHQL_UNSUPPORTED_ENGINE).
Aktywuj, a następnie zapytaj#
# Idempotent: wielokrotne wywołanie już włączonego projektu jest nieskuteczne.
# --wait powraca, gdy GraphQL jest rzeczywiście włączony (aktywacja jest zadaniem w tle).
aura projects graphql-enable <project_id> --wait
Aktywacja odpowiada zaktualizowanym projektem (graphql_enabled: true). Zwróć uwagę na przegięcie kolumny (created_at → createdAt): zobacz oficjalną dokumentację pg_graphql API dla filtrów, orderBy, paginacji kursora (first/after) i mutacji (insertInto<Table>Collection).
Dostosuj ustawienia: introspekcja, maksymalna liczba wierszy, odmiana nazwy#
pg_graphql odczytuje swoje ustawienia z komentarza do schematu projektu. Może go zapisać tylko właściciel schematu, więc platforma zrobi to za Ciebie w jednej transakcji, kiedy o to poprosisz. Zmiana jest idempotentna (prośba o to, co zostało już zastosowane, nic nie daje) i ograniczona (max_rows poza 1–10000 jest odrzucany, zanim cokolwiek zostanie umieszczone w kolejce).
# Pokaż obowiązujące ustawienia
aura projects graphql-config <project_id>
# Włącz introspekcję (GraphiQL, graphql-codegen, Apollo), poczekaj aż zostanie zastosowana
aura projects graphql-config <project_id> --introspection on --wait
# Ogranicz kolekcje do 100 wierszy i zachowaj nazwy SQL bez zmian
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait
state mówi prawdę o zmianie: pending w trakcie jej stosowania (z pending_config), failed jeśli nie byłoby to możliwe (ustawienia w config są wtedy nadal aktualne), applied w przeciwnym razie. Najpierw należy włączyć GraphQL (w przeciwnym razie GRAPHQL_NOT_ENABLED), a następnie dokonać drugiej zmiany, gdy jedna oczekuje na odpowiedź GRAPHQL_CONFIG_PENDING: spróbuj ponownie za kilka sekund.
Przy włączonej opcji introspection każdy, kto posiada klucz publiczny projektu, może wyświetlić listę każdej tabeli i kolumny udostępnianej przez GraphQL (RLS nadal chroni wiersze). Włącz go na potrzeby programowania i wyłącz ponownie na potrzeby produkcji, jeśli kształt schematu jest wrażliwy.
Punkty uwagi#
Domyślnie pg_graphql odmienia nazwy SQL snake_case na GraphQL camelCase (created_at staje się createdAt, tabela blog_posts staje się blogPostsCollection). Po zmianach DDL PostgREST ponownie ładuje pamięć podręczną schematu w ciągu kilku sekund, więc zarówno /graphql, jak i /rpc/graphql udostępniają zaktualizowane pola.
Aby pójść dalej#
- Baza danych
Postgres zarządzany, rozszerzenia włączone, RLS — schemat udostępniany przez pg_graphql.
- Wywołaj funkcję Postgres
Ogólny serwer proxy RPC (/rpc/{function}) używany przez zapytania GraphQL.
- Bezpieczeństwo i RBAC
RLS, role anon/authenticated/service_role — model odziedziczony w niezmienionej postaci przez GraphQL.
- interfejs wiersza polecenia
aura projekty graphql-enable i reszta poleceń projektów.