pg_graphql to rozszerzenie Postgres typu open source obsługiwane przez Supabase — nie jest to wynalazek Aurabase. To, co zbudowaliśmy, to natywna i opcjonalna integracja z platformą: pole do zaznaczenia dla każdego projektu, a nie usługi do świadczenia. W tym poście szczegółowo opisano rzeczywistą architekturę, pokazano, jak ją włączyć i uczciwie porównano kompromisy z Hasura i PostGraphile v5.
pg_graphqluruchamia w Postgres jako rozszerzenie SQL — nie ma osobnego serwera GraphQL do wdrożenia, w przeciwieństwie do Hasura i PostGraphile.- Funkcja opakowania udostępniana przez Aurabase to
SECURITY INVOKER: Twoje zasady RLS są stosowane automatycznie, bez drugiego systemu uprawnień do równoległego utrzymywania. - Aktywacja zgody tylko na projekt —
aura projects graphql-enablelub Studio — nigdy nie jest aktywowana domyślnie w żadnym projekcie. - W czerwcu 2025 r. firma Hasura oficjalnie ponownie skupiła się na agentach PromptQL i AI, nie rezygnując przy tym ze swojego silnika GraphQL.
- PostGraphile v5 stał się ogólnie dostępny 24 marca 2026 r. — był to bezpośredni i aktywny konkurent, a nie uśpiony projekt.
pg_graphql, w jednym zdaniu
pg_graphql dokonuje introspekcji Twojego schematu SQL i generuje schemat GraphQL zgodny z konwencją Relay — <table>Collection, edges, node, filtruje według typu kolumny, paginacja według kursora. Brak SDL do ręcznego pisania lub utrzymywania: schemat GraphQL jest zgodny ze schematem Postgres.
Punkt mający znaczenie dla architektury: ten generator schematów znajduje się w bazie danych jako funkcja SQL, a nie jako proces HTTP obok niego. Aurabase przypina wersję rozszerzenia 1.6.1 (wydaną 7 maja 2026 r.) w obrazie Postgres — ten sam oficjalny pakiet .deb rozpowszechniany przez Supabase. Jest instalowany zarówno na klastrze współdzielonym, jak i na dedykowanych instancjach Postgres.
Jeśli pochodzisz z Supabase, gdzie pg_graphql było natywnie włączone przez długi czas, logika będzie ci znana. Nasze szczegółowe porównanie i nasz przewodnik migracji obejmują resztę schematu i zasad RLS, które pozostają takie same.
Co się zmieniło w Hasura i PostGraphile
Żaden z dwóch historycznych konkurentów „natychmiastowego GraphQL na Postgres” nie zniknął. Ich pozycja uległa zmianie i zaktualizowany artykuł powinien to odzwierciedlać, a nie cytować stan sprzed dwóch lat.
Hasura opublikował post w czerwcu 2025 r. o wyraźnym tytule „Od GraphQL do PromptQL: początek nowego rozdziału”, podpisany przez współzałożyciela Tanmai Gopala. Przesłanie: firma ponownie koncentruje swój plan działania na PromptQL, warstwie dostępu do danych zaprojektowanej dla agentów AI. Silnik GraphQL nie został usunięty – strona główna Hasura nadal przedstawia go jako „przetestowany w boju” – ale nie jest to już wiadomość priorytetowa.
PostGraphile ze swojej strony postąpiło odwrotnie. Jego wersja 5, rozwijana od 2023 roku w formie beta, stała się powszechnie dostępna 24 marca 2026 roku, wraz z nowym silnikiem planowania zapytań o nazwie Grafast. To nie jest projekt, któremu brakuje pary: ostatnia wersja, 5.1.4, pochodzi z 5 sierpnia 2026 r. Pakiet npm naliczył 119 230 pobrań tylko w tygodniu od 16 do 22 sierpnia 2026 r. (rejestr npm, konsultowano 23 sierpnia 2026 r.).
Praktyczna konsekwencja: prawdziwą wolną przestrzenią nie jest „GraphQL na Postgres, nikt jej nie dotyka” — jest to specyficzny slot GraphQL o zerowej konfiguracji, aktywowany jednym poleceniem, bez obsługi hosta. Hasura odchodzi od niego w drodze strategicznego wyboru; PostGraphile nigdy nie był na to ukierunkowany, jego model pozostaje „biblioteką Node.js do samodzielnej integracji”.
Gdzie każde rozwiązanie faktycznie się obraca
Różnica, która kształtuje wszystko inne – koszt operacyjny, powierzchnię ataku, opóźnienie – polega na tym, gdzie działa silnik GraphQL.
| Gdzie się obraca | Rozszerzenie SQL, w Postgres | Oddzielny serwer GraphQL (Go), przed Postgres | Biblioteka/serwer Node.js, przed Postgres |
|---|---|---|---|
| Wymagane wdrożenie | Brak — aktywowany przez flagę projektu | Tak — hostuj i skaluj silnik Hasura | Tak — hostuj proces Node lub zintegruj go ze swoim serwerem |
| Model uprawnień | Starsze wersje Postgres RLS (WYWOŁAJĄCY BEZPIECZEŃSTWA) | Własny system uprawnień Hasura, według roli/tabeli | RLS Postgres przez pgSettings — również delegowanie natywne |
| Domyślnie introspekcja | Wyłączony | W zależności od konfiguracji silnika | W zależności od konfiguracji serwera |
| Pozycjonowanie 2026 | Natywna opcja Postgres BaaS | Od czerwca 2025 ponownie skupiłem się na PromptQL/IA | GA v5 od marca 2026, aktywny projekt |
| AURABAZA | HASURA | POSTGRAFIKA V5 |
Szczerze mówiąc: PostGraphile deleguje także uprawnienia do Postgres poprzez pgSettings i przełączanie ról — natywny RLS nie jest wyłącznie dla pg_graphql. Różnica polega na tym, kto hostuje i konfiguruje ten most: w PostGraphile to ty; w Aurabase jest to już zrobione.
Jak Aurabase aktywuje pg_graphql w projekcie
Aktywacja jest opcjonalna dla każdego projektu i jest zarezerwowana dla projektów silnika Postgres — projekt MongoDB odrzuca żądanie (GRAPHQL_UNSUPPORTED_ENGINE), pg_graphql jest rozszerzeniem Postgres i nie ma odpowiednika w drugim silniku.
Poprzez CLI lub bezpośrednio wywołując plan zarządzania:
# Idempotentny: przywołanie już aktywowanego projektu niczego nie odtwarza
aura projects graphql-enable <project_id>
# Odpowiednik HTTP (płaszczyzna zarządzania, konsola JWT)
curl -X POST "$AURA_CONTROL_URL/v1/control/projects/$PROJECT_ID/graphql/enable" \
-H "Authorization: Bearer $CONSOLE_JWT"
Po stronie serwera wywołanie wykonuje zadanie graphql_enable, które dostawca wykonuje w pojedynczej transakcji: instalacja rozszerzenia, utworzenie funkcji graphql() w schemacie, GRANTy do ról aplikacji. Jeśli krok się nie powiedzie, wszystko zostaje anulowane — opakowanie nigdy nie jest instalowane w połowie, a graphql_enabled przechodzi do true dopiero po całkowitym sukcesie.
Działa zarówno na współdzielonym klastrze Postgres, jak i na dedykowanej instancji CNPG na projekt — dwa różne obrazy Postgres, ale ten sam mechanizm rozszerzenia. W dedykowanych instancjach rozszerzenie jest instalowane za pośrednictwem manifestu deklaratywnego operatora CNPG, a nie bezpośredniego SQL — jest to niedawna poprawka. Dedykowany klaster działa bez dostępu superużytkownika aplikacji, a pg_graphql wymaga dokładnie tego uprawnienia dla swojego CREATE EXTENSION.
W Studio ten sam przepływ przechodzi przez kartę Konfiguracja tabeli. Znajdujący się tam przycisk aktywuje rozszerzenie na poziomie projektu — to samo wywołanie HTTP co powyżej, z odpytywaniem aż do uzyskania konwergencji. Następnie druga kontrola ustawia dyrektywę @graphql dla każdej tabeli, aby aktywować lub nie totalCount i pola agregacji w jej kolekcji GraphQL, bez opuszczania edytora.
Widok pojedynczego polecenia: aktywacja → zadanie udostępniania wątkowe (idempotent, brak operacji, jeśli jest już w trakcie wykonywania) → transakcja DDL (rozszerzenie, funkcja opakowania, GRANT) → flaga graphql_enabled ustawiana dopiero po całkowitym powodzeniu → żądania możliwe poprzez /rpc/graphql.
Starsza wersja RLS, a nie drugi system do utrzymania
Funkcja ustawiona przez Aurabase to SECURITY INVOKER — domyślne zachowanie Postgres, wyjaśnione tak, aby przyszły refaktoryzator nie zmienił go przypadkowo. Działa z uprawnieniami rzeczywistego wywołującego (aura_anon, aura_authenticated lub aura_service_role, w zależności od żądania JWT), więc zasady RLS obowiązują dokładnie tak samo, jak w przypadku żądania REST.
Funkcja SECURITY DEFINER ominęłaby cały RLS — sprawdzane wewnętrznie: wywołanie graphql.resolve w ramach połączenia superużytkownika bez zmiany roli aplikacji zwraca wiersze wszystkich właścicieli, RLS lub nie. Dokładnie takie ryzyko związane z różnymi najemcami, którego pozwala uniknąć ten wybór.
W Hasura architektura różni się konstrukcją: silnik konwertuje każde zapytanie GraphQL na zapytanie SQL ograniczone regułami uprawnień specyficznymi dla Hasura. Reguły te są definiowane dla każdej roli i tabeli w jej własnej warstwie — system równoległy do Postgres RLS, a nie delegacja do niego. Dwa miejsca do audytu reguł dostępu zamiast jednego.
Introspekcja ({ __schema { ... } }) pozostaje domyślnie wyłączona w każdym projekcie Aurabase — postawa spójna z resztą platformy. Można go aktywować według schematu poprzez COMMENT ON SCHEMA, jeśli potrzebuje tego narzędzie takie jak Apollo Studio lub graphql-codegen.
Włącz, a następnie zapytaj API GraphQL
Po graphql_enabled do true na bramie nie pojawia się żadna dedykowana trasa /graphql. Żądanie przechodzi przez ogólny serwer proxy RPC, podobnie jak każda funkcja Postgres wywoływana z zestawu SDK.
curl -X POST "$NEXT_PUBLIC_AURABASE_URL/v1/db/$PROJECT_ID/rpc/graphql" \
-H "apikey: $NEXT_PUBLIC_AURABASE_ANON_KEY" -H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{"query":"query { postsCollection(first: 10, filter: { published: { eq: true } }) { edges { node { id title created_at } } } }"}'
Odpowiedź jest zgodna ze specyfikacją GraphQL — { data, errors } — bez dodatkowego zawijania Aurabase: brama wykrywa, że docelowym wywołaniem RPC jest graphql i nie zawija go ponownie, w przeciwieństwie do zwykłego wywołania RPC. Standardowy klient GraphQL (Apollo, urql, graphql-request) zużywa dane wyjściowe w niezmienionej postaci.
Po aktywacji domyślnie ustawiane są dwa ustawienia za pomocą dyrektywy @graphql na schemacie: max_rows: 1000 i inflect_names: true. pg_graphql domyślnie ogranicza liczbę wierszy do 10 000 na kolekcję — bez first: duża tabela może zapełnić pamięć. inflect_names daje czytelne nazwy typów zamiast surowego węża_case tabel SQL.
Czego pg_graphql nie robi (jeszcze)
Należy je dokumentować, a nie ukrywać, w duchu tego bloga.
- Brak natywnych subskrypcji GraphQL. pg_graphql obejmuje zapytania i mutacje, a nie działanie w czasie rzeczywistym
subscriptions— jest to ograniczenie samego rozszerzenia, a nie pominięcie Aurabase. Aurabase w czasie rzeczywistym istnieje, ale za pośrednictwem oddzielnego kanału (postgres_changes), a nie mostu subskrypcji GraphQL. - Brak działań deklaratywnych typu Hasura. Model „biznesowego webhooka podłączonego do mutacji GraphQL” nie ma bezpośredniego odpowiednika — w Aurabase ta logika przechodzi przez funkcję Postgres lub funkcję Edge, a nie przez dedykowaną konfigurację GraphQL.
- Zarezerwowane dla silnika Postgres. Projekt MongoDB nie może tego włączyć — nie przewidziano żadnego obejścia.
Dlaczego aktywacja pozostaje opcją opcjonalną, a nie domyślną: obszar GRANT/Roles bazy danych dzierżawy ma udokumentowaną historię regresji. To wystarczy, aby uzasadnić, że żadna funkcjonalność nie dotyka jej bez wyraźnej walidacji, projekt po projekcie, przed rozważeniem szerszej wady.
Aurabase, Hasura lub PostGraphile: w zależności od kontekstu
Wszystkie trzy opcje są uzasadnione — właściwy wybór zależy od tego, co już masz, a czego chcesz uniknąć.
- pg_graphql na Aurabase — jeśli Twoja baza danych i zasady RLS są już dostępne na Aurabase i chcesz uzyskać drugi sposób wysyłania zapytań bez dodatkowych usług do monitorowania.
- Hasura — jeśli połączysz wiele źródeł danych (nie tylko Postgres) w ramach jednego schematu GraphQL lub jeśli PromptQL i jego podejście do agenta AI pasują do Twojego planu działania.
- PostGraphile v5 — jeśli chcesz mieć pełną kontrolę nad schematem generowanym przez system wtyczek i masz już uruchomiony serwer Node.js, z którym możesz go zintegrować.
Aby zapoznać się z pełną składnią zapytań — filtry według typu kolumny, sortowanie orderBy, paginacja według kursora, mutacje insertInto<Table>Collection — zobacz oficjalną dokumentację pg_graphql. Poniższa dokumentacja Aurabase GraphQL również szczegółowo opisuje pełny cykl.