Service: GraphQL Engine - EyevinnOSC/community GitHub Wiki
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.
- 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.
- Create a PostgreSQL instance (
serviceId: "birme-osc-postgresql", options below) withcreate-service-instanceand wait until it is running. Usedescribe-service-instanceto get its address and port. The connection URL has the formpostgres://postgres:<password>@<IP>:<PORT>/postgres. - Store two secrets with
create-service-secret(serviceIdhasura-graphql-engine):hasuradbwith the connection URL, andhasuraadminwith a long random string (the admin secret that protects the console and the metadata API). - Create the instance with
create-service-instance,serviceId: "hasura-graphql-engine":
{
"name": "myhasura",
"DatabaseUrl": "{{secrets.hasuradb}}",
"AdminSecret": "{{secrets.hasuraadmin}}",
"EnableConsole": true
}- Wait for it to be running (
wait-for-service-readyorget-instance-status) and get the URL withdescribe-service-instance.
| 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.
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. |
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"- For applications, do not ship the admin secret to browsers. Set
JwtSecretandUnauthorizedRoleand define permissions per role instead.