Перейти к содержимому
Логотип Аурабаза
аурабаза

ГрафQL

Расширение Postgres pg_graphql, включается для каждого проекта и отключено по умолчанию. После включения он предоставляет ту же схему, что и ваш REST API — наследующий RLS и роли без отдельной аутентификации GraphQL — через выделенные маршруты /graphql или общий прокси-сервер RPC.

Пояснение5 мин читатьУровень среднийПересмотрено 11 нояб. 2026 г.

Эта страница была переведена автоматически. Английская версия является авторитетной.

Второй способ запроса той же схемы, а не отдельной службы.#

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

цикл активацииtext
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 (&lt;table&gt;Collection, edges, node) со столбцами SQL snake_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_graphql COMMENT 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).

Активируйте, затем запросите#

graphql-enable.shbash
# Идемпотент: повторный вызов уже включенного проекта невозможен.
# --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 отклоняется до того, как что-либо будет поставлено в очередь).

graphql-config.shbash
# Показать действующие настройки
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 предоставляют обновленные поля.

Чтобы пойти дальше#