Hasura GraphQL engine

Use the Hasura GraphQL Engine with YugabyteDB to use GraphQL with your YugabyteDB databases and applications.

Follow the steps below to learn how easily you can begin using the Hasura GraphQL Engine with YugabyteDB. For details on using the Hasura GraphQL engine, see the Hasura GraphQL engine documentation.

Before you begin

Install and start YugabyteDB

If you are new to YugabyteDB, you can be up and running with YugabyteDB in under five minutes by following the steps in Quick start.

To use the Hasura GraphQL Engine with YugabyteDB, you need to set the yb-tserver option —ysql_suppress_unsupported_error to true so that errors on the use of unsupported SQL statements are suppressed and only raise warnings instead.

If you’re using yb-ctl to start your cluster, you can add the option like this:

  1. $ ./bin/yb-ctl start --tserver_flags "ysql_suppress_unsupported_error=true"

Install and start Hasura

To install the Hasura GraphQL engine, follow the steps in the Hasura Quick start with Docker.

To use Hasura with YugabyteDB, the configuration should be similar to PostgreSQL, except that the port should be 5433.

For a local Mac setup, the configuration should be:

  1. docker run -d -p 8080:8080 \
  2.        -e HASURA_GRAPHQL_DATABASE_URL=postgres://postgres:@host.docker.internal:5433/yugabyte \
  3.        -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
  4.        hasura/graphql-engine:v1.1.0

NoteFor the hasura/graphql-engine value, make sure that the version matches the Hasura GraphQL Engine version that you are using.

After following the steps in the Hasura Quick start with Docker above and downloading the docker-run.sh file, you need to change the user permissions on the file to make it executable by running the following chmod command:

  1. $ chmod +x docker-run.sh

When this script runs, the Hasura GraphQL Engine starts in the Docker container and returns the unique container ID.

  1. $ hasura-yb ./docker-run.sh
  2. 8afee92b0e2535baf3fdb1308f78f008b3e3c950d4f560a58449b4ef7e23652a

To start the Hasura GraphQL Engine, run the following script:

  1. $ ./docker-run.sh

Note

The initialization step may take a few seconds or more.

To check the Docker logs, you can use the container ID returned by the command above:

  1. docker logs <container-id>

Create sample tables and relationships

Follow the steps below to add tables to the yugabyte database specified in the configuration above.You can use another database, if you want, but make sure to change the database name in the HASURA_GRAPHQL_DATABASE_URL setting.

To perform the steps below, open the Hasura UI on localhost:8080 and go to the DATA tab as shown here.

DATA tab in Hasura UI

1. Create the author table

Click Create Table and fill in the details as below to create a table author(id, name).

author table form

After filling in details, click Add Table at the bottom, then go back to the DATA tab.

2. Create the article table

Click Create Table again to create a table article(id, title, content, rating, author_id), with a foreign key reference to author.

Fill in the details as shown here.

article table form

Under Foreign Keys, click Add a foreign key and fill in as shown here.

foreign keys form

After completing the entries, click Save for the foreign key constraint, and then click Add Table at the bottom. Then go back to the DATA tab.

3. Create an object relationship

  • Go to the article table on the left-side menu, then click the Relationships tab.relationships form

  • Click Add, and then click Save.

4. Create an array relationship

Now go to the author table’s Relationship tab.

array relationships form

Click Add, and then click Save.

5. Load sample data

  • On the command line, change your directory to the root yugabyte directory, and then open ysqlsh (the YSQL CLI) to connect to the YugabyteDB cluster:
  1. ./bin/ysqlsh
  • Copy the YSQL statements below into the shell and press Enter.
  1. INSERT INTO author(name) VALUES ('John Doe'), ('Jane Doe'); 
  2. INSERT INTO article(title, content, rating, author_id) 
  3. VALUES ('Jane''s First Book', 'Lorem ipsum', 10, 2);
  4. INSERT INTO article(title, content, rating, author_id) 
  5. VALUES ('John''s First Book', 'dolor sit amet', 8, 1);
  6. INSERT INTO article(title, content, rating, author_id) 
  7. VALUES ('Jane''s Second Book', 'consectetur adipiscing elit', 7, 2);
  8. INSERT INTO article(title, content, rating, author_id) 
  9. VALUES ('Jane''s Third Book', 'sed do eiusmod tempor', 8, 2);
  10. INSERT INTO article(title, content, rating, author_id) 
  11. VALUES ('John''s Second Book', 'incididunt ut labore', 9, 1);
  12. SELECT * FROM author ORDER BY id;
  13. SELECT * FROM article ORDER BY id;

Run some GraphQL queries

Go back to the Hasura UI and click GRAPHIQL.

Query using the object relationship

Fetch a list of articles and sort each article’s author in descending order and by rating.

  1. {
  2.   article(order_by: {rating: desc}) {
  3.     id
  4.     title
  5.     author {
  6.       id
  7.       name
  8.     }
  9.   }
  10. }

Relationships form

Query using the array relationship

Fetch a list of authors and a nested list of each author’s articles where the authors are ordered by descending by the average ratings of their articles, and their article lists are ordered by title.

  1.  {
  2.    author(order_by: {articles_aggregate: {avg: {rating: desc}}}) {
  3.      name
  4.      articles(order_by: {title: asc}) {
  5.        title
  6.        content
  7.        rating
  8.      }
  9.    }
  10.  }

query array relationship

Clean up

Now that you’re done with this exploration, you can clean up the pieces for your next adventure.

  • Stop the YugabyteDB cluster by running the yb-ctl stop command.
  1. ./bin/yb-ctl stop

Note: To completely remove all YugabyteDB data/cluster-state you can instead run:

  1. ./bin/yb-ctl destroy
  • Stop The Hasura container,
  1. docker stop <container-id>

You can list running containers using the following command:

  1. docker ps