GraphQL API with Hasura

How to build and deploy realtime GraphQL APIs in a few minutes

Before we dive deep into details, I'll quickly describe the tools I used to build and deploy a realtime GraphQL API and tell you why you should fall in love with GraphQL and all the tools I used.

First, why to use GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with existing data. GraphQL provides a schema that describes the API and allows clients (e.g. your frontend or mobile application) to easily fetch data they want and nothing more.

Here is what you get from using GraphQL instead of standard RESTful APIs:

  • GraphQL queries get exactly what you need, nothing more and nothing less
  • Instead of making multiple requests to fetch required data, you make just one request to one endpoint
  • GraphQL schema is typed, what makes the contract between frontend and backend clear and understandable

If you are a frontend engineer, you will not like to consume other APIs than GraphQL after trying it out. It makes your life so much more pleasurable and easy.

You don't need to know GraphQL to follow this article. All you need to know is that GraphQL allows you to define contract between frontend and backend and do operations on the data you are interested in.

Productivity boosting tools

Hasura is an open source engine that connects to your databases & microservices and auto-generates a production-ready GraphQL backend. By using Hasura in conjunction with Qovery (platform that combines the power of Kubernetes, the reliability of AWS and the simplicity of Heroku to allow developers deploy their apps with pleasure), you get a blazing fast, auto-scallable and extensible solution to quickly build your applications.

Why Hasura?

Consuming GraphQL APIs is a pleasure. We'd like to have more GraphQL APIs. But those APIs do not come out of nowhere. Somebody has to implement them first - the data won't just flow out of the database through the schema to your frontend automagically, right? Well... with Hasura it will!

Hasura allows you to bootstrap a realtime GraphQL API in seconds by simply modeling your data. Hasura will do the hard work of translating your needs into queries to the database and translating them to GraphQL schema. Thanks to this, all you need to do is to define the data you want to store in the database - Hasura will do the rest.

This is unbelievable how much time it saves. If you don't believe, try implementing a GraphQL server yourself - with all the featuers and options that Hasura offers.

If you have doubts about flexibility - you don't have to worry. If you need to perform a very custom business logic, you can implement this part in any language you want and connect it to Hasura engine. This way you will not only save a lot of time, but also have flexibility to write your custom code if needed.

Why Qovery?

Managing infrastructure is hard and takes time. Developers want to focus on building their apps instead of wasting time on managing servers or databases. Qovery is tool that does it all for you - all you have to do is to write your application code. It's powered by Docker and Kubernetes underneath, so you get all the benefits of using those modern tools without the complexity and costs of learning and managing them.

Qovery is also a great fit for Hasura - its free plan allows you to deploy Hasura and database for free, without any limits, performance degradations or putting your app to sleep like it's done on other platforms.

If you have any questions regarding this post or other things, feel free to reach me on Discord.

Hasura deployment on Qovery

  1. Create a new project

    Migrate from Heroku

  2. Create a new environment

    Migrate from Heroku

  3. Create a new application

    To follow the guide, [you can fork and use our repository][https://github.com/Qovery/hasura.git]

    Use the forked repository (and branch main) while creating the application in the repository field:

    Migrate from Heroku

  4. Deploy a database

    Create and deploy a new database (name it my-pql-db to follow the guide flawlessly)

    To learn how to do it, you can follow this guide

  5. Add the database to the application

    In application overview, select Settings

    Open Settings

    Switch to Database, pick your database and Save

    Link Database

  6. Use Dockerfile

    In application overview, select Settings

    Open Settings

    In the Build Mode, select Dockerfile and set Dockerfile path as Dockerfile

  7. Setup Hasura

    We need to add two environment variables to our Hasura application:

    First, go to your application envioronment variables and add HASURA_GRAPHQL_ENABLE_CONSOLE variable with value true.

    Then, select secrets tab, and create an alias to QOVERY_DATABASE_MY_PQL_DB_CONNECTION_URI named HASURA_GRAPHQL_DATABASE_URL.

    You can read more about environment variables in our configuration section.

  8. Deploy the app on Qovery

    All you have to do now is to navigate to your application and click Deploy button

    Deploy App

    That's it. Watch the status and wait till the app is deployed.

Well done! After a while, your Hasura app should be up and running.

Creating realtime GraphQL APIs

To open the application in your browser, click on Action and Open buttons in your application overview:

Open App

Navigate to your Hasura application URL and choose Data tab in the console.

Hasura Console In this section we'll configure our data model. Now, click on the Create Table button.

You’ll see the table creator. We are going to create a simple "Todo" items table. We'll name it "todos" and the table will contain three columns:

  • id - unique identifier of given "Todo" item
  • title
  • description - optional description of "Todo" item

Fill the form as in the screenshots below to prepare the table.

Table Table

At the end, we should specify our id column as a Primary Key.‍

Primary Key

The table is ready to be created. Click Add Table button at the bottom of the page.

Voila! The table has been created in Postgres and Hasura has exposed GraphQL APIs to interact with our data.

Testing GraphQL APIs

To test the GraphQL API, navigate to the GraphiQL tab and run the following query:

mutation query {
todos {
id
title
description
}
}

GraphiQL As you can see, Hasura returned an empty array of "Todo" items. Let’s add a "Todo" item by executing the following query:

mutation {
insert_todos(objects:[
{
title: "My first TODO"
description: "It's very important TODO item"
}
]) {
affected_rows
}
}

After you run the above query, in the response you'll see information about one affected row. Congrats! You have created a first "Todo" item. Let's now move further to a more interesting topic.

GraphQL realtime APIs

It's time to use a realtime GraphQL APIs - GraphQL Subscriptions. Subscription allows you to fetch data and get updates about any changes that occur in data you are interested in.

In the GraphiQL, run the following query:

subscription {
todos {
id
title
description
}
}

In the response in the right-hand of console you'll see a "Todo" item you have created previously. That's great. Let's now test if the subscription really works - open one more Hasura console in a separate browser tab and navigate to GraphiQL.

Execute the following query a few times:

mutation {
insert_todos(objects:[
{
title: "Another TODO to test subscriptions"
description: "Subscriptions!"
}
]) {
affected_rows
}
}

At the same time, keep an eye at the subscription. Each and every newly created "Todo" item automagically appears in the subscription response!

Realtime GraphQL

Conclusions

By following this article you quickly deployed a realtime GraphQL backend using Qovery, Hasura and Postgres database.

Using this stack saves you tons of time. Deploying it on Qovery is extremely easy. We take care of your application and your database. With Qovery and Hasura all you have to do to expose quality, realtime GraphQL backend is just a few clicks. After minutes your application is ready - define your data schema and expose GraphQL API to the world!

Tutorial