Service: GraphQL Engine - EyevinnOSC/community GitHub Wiki

GraphQL Engine

Hasura GraphQL Engine (serviceId hasura-graphql-engine) gives you an instant GraphQL API on top of a database, with role-based permissions and an admin console for managing schemas and testing queries. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0. Its OSC dependency is PostgreSQL (birme-osc-postgresql), which Hasura uses for its own metadata and as the first data source.

What it can do

  • Expose a GraphQL API (/v1/graphql) over your database tables.
  • Apply role-based permissions, with JWT authentication or an unauthorized role for anonymous access.
  • Provide a web console for tracking tables, managing schema and trying queries.

Creating an instance

  1. Create a PostgreSQL instance (serviceId: "birme-osc-postgresql", options below) with create-service-instance and wait until it is running. Use describe-service-instance to get its address and port. The connection URL has the form postgres://postgres:<password>@<IP>:<PORT>/postgres.
  2. Store two secrets with create-service-secret (serviceId hasura-graphql-engine): hasuradb with the connection URL, and hasuraadmin with a long random string (the admin secret that protects the console and the metadata API).
  3. Create the instance with create-service-instance, serviceId: "hasura-graphql-engine":
{
  "name": "myhasura",
  "DatabaseUrl": "{{secrets.hasuradb}}",
  "AdminSecret": "{{secrets.hasuraadmin}}",
  "EnableConsole": true
}
  1. Wait for it to be running (wait-for-service-ready or get-instance-status) and get the URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only (^\w+$), at most 20 characters.
DatabaseUrl Yes string, sensitive Connection string of the primary database, used for Hasura's metadata and as a data source. For PostgreSQL: postgres://<user>:<password>@<host>:<port>/<db>. Associated with birme-osc-postgresql.
AdminSecret Yes string, sensitive Admin secret that authenticates admin requests: console, metadata API and schema changes. Admin access bypasses all permission rules. Sent in the x-hasura-admin-secret header.
EnableConsole No boolean Turns the Hasura web console on. Useful for development; consider leaving it off in production.
JwtSecret No string, sensitive JWT authentication configuration as a JSON object (key, algorithm and other JWT settings), used to verify tokens sent by clients.
UnauthorizedRole No string Role used for unauthenticated requests. The role must have permissions defined, otherwise anonymous access gives nothing.

Store sensitive options as service secrets and pass them as {{secrets.NAME}} (whole field value only). Overwriting a secret does not restart a running instance.

PostgreSQL options

birme-osc-postgresql (https://app.osaas.io/dashboard/service/birme-osc-postgresql) is a long-running PostgreSQL instance. License: MIT.

Option Required Type Meaning
name Yes string Name of the instance (^\w+$, at most 20 characters).
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser account. Use a secret, for example {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at startup. Defaults to the user name.
PostgresInitDbArgs No string Extra arguments for initdb when the cluster is initialized (for example encoding or locale).
PostgresInitDbSql No string SQL executed during initialization.

Using the instance

There is no default username or password. Open the instance URL, open the console and enter the admin secret from hasuraadmin. Use the Data tab to track tables and the API tab to try queries.

Send requests to https://<your-instance-url>/v1/graphql with the admin secret in the x-hasura-admin-secret header:

curl -X POST https://<your-instance-url>/v1/graphql \
  -H "Content-Type: application/json" \
  -H "x-hasura-admin-secret: <admin secret>" \
  -d '{"query":"{ __typename }"}'

With the OSC CLI:

osc create hasura-graphql-engine myhasura \
  -o DatabaseUrl="{{secrets.hasuradb}}" \
  -o AdminSecret="{{secrets.hasuraadmin}}" \
  -o EnableConsole="true"

Limitations

  • For applications, do not ship the admin secret to browsers. Set JwtSecret and UnauthorizedRole and define permissions per role instead.

Resources

⚠️ **GitHub.com Fallback** ⚠️