Service: Hasura GraphQL Engine - EyevinnOSC/community GitHub Wiki

Hasura GraphQL Engine

Hasura GraphQL Engine (serviceId hasura-graphql-engine) instantly gives your database a real-time GraphQL and REST API. Connect a database and Hasura generates queries, mutations and subscriptions with fine-grained access control, with no backend code required. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0.

What it can do

  • Expose tables in a PostgreSQL database as a GraphQL API (queries, mutations, subscriptions) and as REST.
  • Define row and column-level access control per role.
  • Authenticate clients with the admin secret, with JWT, or allow anonymous access through an unauthorized role.
  • Provide the Hasura Console (when enabled) to track tables, set permissions, run queries in the GraphiQL explorer and define relationships between tables.

Creating an instance

Hasura stores its metadata in the database you give it and also uses it as the primary data source. Create the database first and confirm it is running:

  1. Create a PostgreSQL instance (birme-osc-postgresql, see Service: PostgreSQL) with a password. Use describe-service-instance to read its address and port. The connection string has the form postgres://postgres:<password>@<host>:<port>/postgres.
  2. Store the connection string as a service secret with create-service-secret (serviceId hasura-graphql-engine), for example named dburl, and the admin secret as adminsecret. The admin secret can be any strong password. A {{secrets.NAME}} reference only works as the entire field value.
  3. Create the instance with create-service-instance, serviceId: "hasura-graphql-engine":
{
  "name": "mygraphql",
  "DatabaseUrl": "{{secrets.dburl}}",
  "AdminSecret": "{{secrets.adminsecret}}",
  "EnableConsole": true
}

Use wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL. With the OSC CLI:

npx -y @osaas/cli create hasura-graphql-engine mygraphql \
  -o DatabaseUrl="{{secrets.dburl}}" \
  -o AdminSecret="{{secrets.adminsecret}}" \
  -o EnableConsole=true

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
DatabaseUrl Yes string, sensitive Connection string for the primary database. Used for Hasura's metadata and as a data source for GraphQL operations. Hasura supports several database types and the connection string format varies by type; the OSC PostgreSQL service is the documented setup.
AdminSecret Yes string, sensitive Secret that gives admin access: managing metadata, schema changes and the Hasura Console. Admin access bypasses all permission rules, so keep it secret. Sent in the x-hasura-admin-secret header.
EnableConsole No boolean Enables the Hasura Console web interface (default: disabled). Useful for development and administration; consider disabling in production.
JwtSecret No string, sensitive JWT authentication configuration: a JSON object with the key, algorithm and other JWT settings used to verify tokens sent by clients.
UnauthorizedRole No string Role used for unauthenticated requests. When set, anonymous users can access the GraphQL API with the permissions of this role. The role must be defined in your permission system.

Sensitive options should be stored as secrets and passed as {{secrets.NAME}}.

Dependency: PostgreSQL options

The PostgreSQL service (birme-osc-postgresql) has the following options. It is associated with Hasura through DatabaseUrl.

Option Required Type Meaning
name Yes string Name of the instance.
PostgresPassword Yes string, sensitive Password for the PostgreSQL superuser account. Example secret reference: {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at start. Defaults to the same name as the user.
PostgresInitDbArgs No string Extra arguments passed to initdb during cluster initialization.
PostgresInitDbSql No string SQL executed during database initialization.

Using the instance

Open the instance URL and, if the console is enabled, enter the admin secret to use the Hasura Console. Query the GraphQL endpoint with the admin secret header:

curl -X POST \
  https://<instance>.hasura-graphql-engine.auto.prod-se.osaas.io/v1/graphql \
  -H "x-hasura-admin-secret: <your-admin-secret>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { id name email } }"}'

Resources

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