Przejdź do treści
Logo Aurabase
aurabaza

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.

Objaśnienie5 min przeczytanePoziom mediatorZmieniono 11 lis 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

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.

Informacje

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 }.

cykl aktywacjitext
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)
Wskazówka

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 (&lt;table&gt;Collection, edges, node) z kolumnami SQL snake_case odmienionymi domyślnie na camelCase — 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) i inflect_names (created_at → createdAt, wł. domyślny). Przepis pg_graphql COMMENT ON SCHEMA … @graphql(...) nie działa z projektu (twoja rola nie jest właścicielem schematu, a /raw odmawia literałów E'…'): użyj zamiast tego aura projects graphql-config lub PATCH …/graphql/config, zobacz Dostosuj ustawienia.
  • Aktywacja zgody, idempotentna. POST .../graphql/enable (konsola JWT) lub aura 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#

graphql-enable.shbash
# 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
Wskazówka

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).

graphql-config.shbash
# 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.

Introspekcja obnaża Twój schemat

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#

Odmiana nazewnictwa i ponowne ładowanie schematu

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#