Deploying Hasura GraphQL engine with a Database for PostgreSQL

• Hasura
• GraphQL
• PostgreSQL

The Hasura GraphQL Engine is a GraphQL server and provides developers with real-time GraphQL APIs for Postgres applications. The application allows you to configure webhook triggers on database events and helps you build GraphQL apps backed by Postgres or incrementally move to GraphQL for existing applications using Postgres.

In this tutorial, you will learn how to get started with Hasura GraphQL Engine using a pre-built Docker container on your local computer, linked to a managed Scaleway Database for PostgreSQL.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• A Scaleway Database for PostgreSQL
• Installed Docker on your local computer

Linking Hasura GraphQL engine with a Database for PostgreSQL

Hasura provides a pre-configured repository to deploy the application in a few simple steps in a Docker container.

1. Download the Docker docker-run.sh script using wget.

   wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-run/docker-run.sh
   

2. The run-docker.sh script contains a sample Docker command to run in it. Open the script in a text editor and modify the database URL and network configuration in the script.

   #! /bin/bash
   docker run -d -p 8080:8080 \
         -e HASURA_GRAPHQL_DATABASE_URL=postgres://username:password@hostname:port/dbname \
         -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
         hasura/graphql-engine:latest
   

   Replace the part postgres://username:password@hostname:port/dbname with the login credentials of your managed PostgreSQL database for the HASURA_GRAPHQL_DATABASE_URL variable.

   Note

   If your password contains special characters (e.g. #, %, $, @, etc.), you need to URL encode them in the HASURA_GRAPHQL_DATABASE_URL environment variable (e.g. %40 for @).

   You can find the credentials of your database in your Scaleway console in the Database section:

   

   The modified file should look like the following example:

   #! /bin/bash
   docker run -d -p 8080:8080 \
         -e HASURA_GRAPHQL_DATABASE_URL=postgres://hasura:p4ssw0rd@195.154.69.220:21568/hasura \
         -e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
         hasura/graphql-engine:latest
   

3. Make the script executable and run the modified script to start Hasura GraphQL Engine:

   ./docker-run.sh
   

Docker will download the container and start it. 4. Check if the container is running using the docker ps command:

docker ps
CONTAINER ID        IMAGE                          COMMAND                  CREATED             STATUS              PORTS                    NAMES
01fd79964ade        hasura/graphql-engine:latest   "graphql-engine serve"   6 seconds ago       Up 5 seconds        0.0.0.0:8080->8080/tcp   dreamy_lalande

5. Open the Hasura Console in your web browser by pointing it to http://localhost:8080/console. The console displays:

   

   Your Hasura GraphQL Engine is ready now.

Making your first GraphQL query

1. Create a table from the Hasura console. Click Data -> Create table and create two new tables called author and book with the following columns to create a simple library indexing system:

   author (
     id SERIAL PRIMARY KEY,
     name TEXT
   )
   book (
     id SERIAL PRIMARY KEY,
     title TEXT,
     summary TEXT,
     rating INT,
     author_id INT
   )
   

   For example the configuration of the book table:

   

2. Add some Sample data by clicking on the Insert Row tab on each of the newly created tables.

3. Query the data using GraphQL commands from the GraphQL tab in the console.

   For example, to query all rows in the book table:

   {
     book {
       id
       title
       summary
       rating
       author_id
     }
   }
   

   You will see an output like the following:

   

   To add a new author to the database, run the following command:

   mutation add_author {
     insert_author(
       objects: [
         { name: "Jarrad Higgins" }
       ]
     ) {
       affected_rows
       returning {
         id
         name
       }
     }
   }
   

   In the output, the ID (here, 5) of the new author displays:

   {
     "data": {
       "insert_author": {
         "affected_rows": 1,
         "returning": [
           {
             "id": 5,
             "name": "Jarrad Higgins"
           }
         ]
       }
     }
   }
   

Conclusion

You have now deployed Hasura GraphQL Engine using Docker, connected it to a Scaleway Database for PostgreSQL, and taken your first steps with GraphQL.

To learn more about Hasura GraphQL Engine, refer to the official documentation.