GraphQL
Postgres 확장 pg_graphql, 프로젝트별로 옵트인되고 기본적으로 비활성화됩니다. 활성화되면 전용 /graphql 경로 또는 일반 RPC 프록시를 통해 별도의 GraphQL 인증 없이 RLS 및 역할을 상속하여 REST API와 동일한 스키마를 노출합니다.
별도의 서비스가 아닌 동일한 스키마를 쿼리하는 두 번째 방법#
GraphQL은 테넌트 데이터베이스 내부의 Postgres pg_graphql 확장을 통해 직접 구동되어 SQL 테이블, 뷰 및 관계에서 GraphQL 스키마를 생성합니다. 이를 활성화하면 REST API와 동일한 Postgres 스키마에 두 번째 쿼리 표면이 추가되어 별도의 GraphQL 서버 또는 인증 계층 없이 정확히 동일한 RLS 정책 및 역할을 상속합니다.
모든 프로젝트에 대해 기본적으로 비활성화되어 있습니다. Aurabase는 프로젝트별로 명시적으로 동의한 경우에만 pg_graphql을 활성화합니다. 전체 쿼리, 필터, 커서 페이지 매김 및 돌연변이 구문은 공식 pg_graphql 문서를 참조하세요.
/graphql 및 /rpc/graphql에 노출된 SQL 해석기#
프로젝트에서 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로 라우팅되고 REST { data, meta } 래퍼 없이 표준 { "data": ..., "errors": ... } GraphQL JSON 페이로드를 직접 반환합니다.
ACTIVATION ────▶ POST .../graphql/enable 또는 aura 프로젝트 graphql-enable
ENQUEUE ────▶ 작업 "graphql_enable"이 대기열에 있음(멱등성, 이미 활성화된 경우 작동하지 않음)
DDL ────▶ CREATE EXTENSION pg_graphql + 래퍼 함수 + GRANT, 단일 트랜잭션 1개
FLAG ────▶ projects.graphql_enabled = true, 전체 트랜잭션 커밋 후에만 설정됩니다.
QUERY ────▶ POST /graphql 또는 /v1/db/{project_id}/graphql(원시 GraphQL JSON 반환)
활성화 트랜잭션은 원자적입니다. 단계(확장, 래퍼 함수 또는 GRANT)가 실패하면 모든 것이 롤백되고 graphql_enabled는 false로 유지됩니다.
활성화 설정#
- 자동으로 생성된 스키마입니다. pg_graphql는 Postgres 스키마를 검사하고 기본적으로 SQL
snake_case열이camelCase에 반영된 Relay GraphQL 유형(<table>Collection,edges,node)으로 각 테이블을 노출합니다. 직접 작성할 SDL이 없습니다. - 보안 호출자 — 상속됨 RLS. 래퍼 함수는 호출자의 권한(
aura_anon/aura_authenticated/aura_service_role)으로 실행되어 REST 요청과 정확히 동일한 RLS 정책을 적용합니다. - 변경할 수 있는 세 가지 설정은 원자적으로 적용됩니다.
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'…'리터럴을 거부합니다). 대신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)를 거부합니다.
활성화한 후 쿼리#
# 멱등성: 이미 활성화된 프로젝트에 대한 반복 호출은 작동하지 않습니다.
# --wait는 GraphQL이 실제로 활성화되면 반환됩니다(활성화는 백그라운드 작업입니다).
aura projects graphql-enable <project_id> --wait
활성화는 업데이트된 프로젝트(graphql_enabled: true)로 응답합니다. 열 변형(created_at → createdAt)에 유의하세요. 필터, orderBy, 커서 페이지 매기기(first/after) 및 변형(insertInto<Table>Collection)에 대해서는 공식 pg_graphql API 참조을 참조하세요.
설정 조정: 내부 검사, 최대 행, 이름 활용#
pg_graphql는 프로젝트 스키마에 대한 주석에서 해당 설정을 읽습니다. 스키마 소유자만이 이를 작성할 수 있으므로 플랫폼은 사용자가 요청할 때 한 번의 트랜잭션으로 이를 작성합니다. 변경 사항은 멱등성(이미 적용된 항목을 요청하면 아무 작업도 수행되지 않음) 및 제한적(1~10000 외부의max_rows은 대기열에 추가되기 전에 거부됨)입니다.
# 적용된 설정 표시
aura projects graphql-config <project_id>
# Introspection을 켜고(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 tells the truth about the change: pending while it is being applied (with pending_config), failed if it could not be (the settings in config are then still the ones in effect), applied otherwise. GraphQL must be enabled first (GRAPHQL_NOT_ENABLED otherwise), and a second change while one is pending answers GRAPHQL_CONFIG_PENDING: retry in a few seconds.
introspection를 켜면 프로젝트의 공개 키를 보유한 사람은 누구나 GraphQL이 노출하는 모든 테이블과 열을 나열할 수 있습니다(RLS는 여전히 행을 보호합니다). 개발용으로 설정하고 스키마 모양이 민감한 경우 프로덕션용으로 다시 끕니다.
주의사항#
기본적으로 pg_graphql는 SQL snake_case 이름을 GraphQL camelCase에 적용합니다(created_at 는 createdAt, 테이블 blog_posts 는 blogPostsCollection). DDL이 변경된 후 PostgREST는 몇 초 내에 스키마 캐시를 다시 로드하므로 /graphql 및 /rpc/graphql 모두 업데이트된 필드를 노출합니다.