ГрафQL
Расширение Postgres pg_graphql, включается для каждого проекта и отключено по умолчанию. После включения он предоставляет ту же схему, что и ваш REST API — наследующий RLS и роли без отдельной аутентификации GraphQL — через выделенные маршруты /graphql или общий прокси-сервер RPC.
Второй способ запроса той же схемы, а не отдельной службы.#
GraphQL работает непосредственно на расширении Postgres pg_graphql внутри вашей базы данных клиента, генерируя схему GraphQL на основе ваших SQL-таблиц, представлений и связей. Включение этого параметра добавляет вторую поверхность запроса к той же схеме Postgres, что и ваш REST API, — наследуя те же политики и роли RLS, без отдельного сервера GraphQL или уровня аутентификации.
По умолчанию отключено для всех проектов. Aurabase активирует pg_graphql только при явном согласии для каждого проекта. См. официальную документацию pg_graphql для получения полной информации о запросах, фильтрах, нумерации страниц курсора и синтаксисе мутаций.
Резолвер SQL, доступный в /graphql и /rpc/graphql.#
Включение 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 и возвращают стандартную полезную нагрузку { "data": ..., "errors": ... } GraphQL JSON напрямую без оболочки REST { data, meta }.
ACTIVATION ────▶ POST .../graphql/enable или проекты аурыgraphql-enable
ENQUEUE ────▶ задание «graphql_enable» поставлено в очередь (идемпотентное, неактивное, если оно уже включено)
DDL ────▶ CREATE EXTENSION pg_graphql + функция-оболочка + GRANT, 1 отдельная транзакция
FLAG ────▶ project.graphql_enabled = true, устанавливается только после полной фиксации транзакции
QUERY ────▶ POST /graphql или /v1/db/{project_id}/graphql (возвращает необработанный файл GraphQL JSON)
Транзакция активации является атомарной: если какой-либо шаг (расширение, функция-оболочка или GRANT) терпит неудачу, все откатывается, и graphql_enabled остается false.
Что устанавливает активация#
- Автоматически созданная схема. pg_graphql анализирует вашу схему Postgres и предоставляет каждую таблицу как тип Relay GraphQL (
<table>Collection,edges,node) со столбцами SQLsnake_case, по умолчанию преобразованными вcamelCase— SDL для записи вручную не требуется. - SECURITY INVOKER — наследуется RLS. Функция-обертка выполняется с привилегиями вызывающего объекта (
aura_anon/aura_authenticated/aura_service_role), применяя те же политики RLS, что и запросы REST. - Три настройки, которые вы можете изменить, применяются атомарно.
introspection(выключено по умолчанию:{ __schema { ... } }отклоняется с помощьюUnknown field "__schema", поэтому GraphiQL и генератор кода Apollo не могут обнаружить схему, пока вы ее не включите),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 организации или в выделенном кластере Enterprise; сквозная проверка (расширение, оболочка RLS, реальный запрос).
- Postgres только проекты. Проект MongoDB отказывается от активации (
GRAPHQL_UNSUPPORTED_ENGINE).
Активируйте, затем запросите#
# Идемпотент: повторный вызов уже включенного проекта невозможен.
# --wait возвращается, как только GraphQL действительно включен (активация является фоновым заданием).
aura projects graphql-enable <project_id> --wait
Активация отвечает обновленным проектом (graphql_enabled: true). Обратите внимание на изменение столбца (created_at → createdAt): см. официальную ссылку на API pg_graphql pg_graphql API для фильтров orderBy, нумерации страниц курсора (first/after) и мутаций (insertInto<Table>Collection).
Настройте параметры: самоанализ, максимальное количество строк, изменение имени.#
pg_graphql считывает свои настройки из комментария к схеме вашего проекта. Ее может написать только владелец схемы, поэтому платформа сделает это за вас за одну транзакцию, когда вы попросите. Изменение является идемпотентным (запрос того, что уже применено, ничего не дает) и ограниченным (max_rows за пределами 1–10000 отклоняется до того, как что-либо будет поставлено в очередь).
# Показать действующие настройки
aura projects graphql-config <project_id>
# Включите самоанализ (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 сообщает правду об изменении: pending, пока оно применяется (с pending_config), failed, если этого не может быть (настройки в config остаются действующими), applied в противном случае. Сначала необходимо включить GraphQL (в противном случае GRAPHQL_NOT_ENABLED), а второе изменение, пока ожидается ответ GRAPHQL_CONFIG_PENDING: повторите попытку через несколько секунд.
Если introspection включен, любой, кто владеет открытым ключом проекта, может перечислить все таблицы и столбцы, которые предоставляет GraphQL (RLS по-прежнему защищает строки). Включите его для разработки и снова отключите для рабочей среды, если форма вашей схемы чувствительна.
Точки внимания#
По умолчанию pg_graphql преобразует имена SQL snake_case в GraphQL camelCase (created_at становится createdAt, таблица blog_posts становится blogPostsCollection). После изменения DDL PostgREST перезагружает свой кэш схемы в течение нескольких секунд, поэтому и /graphql, и /rpc/graphql предоставляют обновленные поля.
Чтобы пойти дальше#
- База данных
Postgres управляемый, расширения включены, RLS — схема, которую предоставляет pg_graphql.
- Вызов функции Postgres
Общий прокси-сервер RPC (/rpc/{function}), используемый запросами GraphQL.
- Безопасность и RBAC
RLS, роли anon/authenticated/service_role — модель, унаследованная GraphQL как есть.
- интерфейс командной строки
проекты aura, grappql-enable и остальные команды проектов.