2019-11-19

Hasura for beginners

elitasson's avatar on Twitter
Johan Eliasson

This guide gives a brief overview of Hasura and defines important concepts. This guide includes, step-by-step, how to set up your Hasura and how to insert and get data from a GraphQL API.

Hasura in one sentence:

Hasura connects to your databases and instantly gives you a production-ready GraphQL API.

Hasura is between your GrahpQL API (top) and database (bottom)
Hasura is between your GrahpQL API (top) and database (bottom)

More specifically, Hasura generates a GraphQL API based on your tables, columns and database structure. GraphQL is mostly known as a way to GET data, but Hasura generates full capabilities of CRUD (Create, Read, Update and Delete).

But let's explore what GraphQL is and why Facebook, Github and other big organizations are adopting GraphQL.

What is GraphQL?

GraphQL is a query language for your API. GraphQL enables clients to ask for exactly the data they need, and nothing more.

What do you mean "the data you need"?

Simple. GraphQL gives you the data you want. GraphQL does not care if the data you need is in different tables, databases or even in different services. GraphQL will stitch everything together for you and give you the data you need.

What do you mean "nothing more"?

"Nothing more" means you specify exactly the data you want you wont get anything else. Data you don't need, you don't get. No over head. You will get the data you need, and nothing more.

Here is an example. Let's say you have a table of cities.

idnamepopulationcoordinate
1Stockholm1515017(59.329444,18.068611)
2Amsterdam838338(2.373056,4.892222)
3Bangalore8443675(12.971389,77.594444)

And you only care about id, name and population (not the coordinates). This is simple with GraphQL. All you do is:

query {
  cities {
    id
    name
    population
  }
}

And you will get the response back:

{
  "data": {
    "cities": [
      {
        "id": 1,
        "name": "Stockholm",
        "population": 1515017
      },
      {
        "id": 2,
        "name": "Amsterdam",
        "population": 838338
      },
      {
        "id": 3,
        "name": "Bangalore",
        "population": 8443675
      }
    ]
  }
}

GraphQL can also connect multiple tables based on a relation, and get the data you need in one request. Let's see an example.

We will continue work with our cities table, and we will add a countries table:

idnamepopulation
1India1339000000
2Netherlands17180000
3Sweden10120000

We will make a relation between the cities and countries table. We do this by adding a country_id to every cities row. This is our updated cities table:

idnamepopulationcoordinatecountry_id
1Stockholm1515017(59.329444,18.068611)3
2Amsterdam838338(2.373056,4.892222)2
3Bangalore8443675(12.971389,77.594444)1

With GraphQL we can make a single request to receive information about both cities and countries, and how they relate to each other:

query {
  cities {
    id
    name
    population
    country {
      name
    }
  }
}
{
  "data": {
    "cities": [
      {
        "id": 1,
        "name": "Stockholm",
        "population": 1515017,
        "country": {
          "name": "Sweden"
        }
      },
      {
        "id": 2,
        "name": "Amsterdam",
        "population": 838338,
        "country": {
          "name": "Netherlands"
        }
      },
      {
        "id": 3,
        "name": "Bangalore",
        "population": 8443675,
        "country": {
          "name": "India"
        }
      }
    ]
  }
}

We made a single query to get the data we wanted. The data we wanted was spread out in two different tables. But we only had to do a single request to get the data. This is the power of GraphQL.

Ok, but what has Hasura to do with all this?

Hasura creates the whole GraphQL API for you. If it was not for Hasura, you would have to write the GraphQL backend your self. Hasura automates everything and saves you a lot of work.

Subscriptions

Subscriptions in GraphQL lets you get realtime updates. It could be that a city gets updated, inserted, or deleted.

subscription {
  cities {
    id
    name
    population
    country {
      name
    }
  }
}

With Hasura you can transform any single query to a subscription. Now, when anything changes that is relevant for your subscription you instantly get the new data.

GraphQL to insert, update and delete data

GraphQL is a powerful technology to query data, but it can also be used to insert, update and delete data. Hasura also automatically generates everything you need to do just that.

Here is an example on how to use GraphQL to insert a city:

mutation {
  insert_cities (
    objects: [{
      name: "New York City",
      population: 8170000,
      coordinate: '40.781944,-73.966111'
    }]
  ) {
    affected_rows
  }
}

And update:

mutation {
  update_cities(_set: { population: 8175133 }, where: { id: { _eq: 4 } }) {
    affected_rows
  }
}

And delete:

mutation {
  delete_cities(where: { population: { _gt: 10000000 } }) {
    affected_rows
  }
}

In addition to automatically provide the GraphQL API based on the database, Hasura also provides a console. The Hasura console.

Hasura console

Hasura console is much like phpMyAdmin. It's a web interface to manage your database. You can, among other things, create tables, add data and run test GraphQL queries.

Managing your database

Manage all your tables. Manage each column, add foreign keys and other constraints. Hasura console is a powerful tool to manage your whole database.

Hasura database management
Hasura database management

GraphiQL

Test GraphQL queries and mutations on the data in your database.

Hasura GraphiQL
Hasura GraphiQL

Remote schema

Add a remote schema. A remote schema is an external GraphQL endpoint.

Hasura Remote Schema
Hasura Remote Schema

Managing events

Create webhooks based on database events. You could for example trigger a webhook that sends an email when a new user is inserted in the database.

Hasura Event Triggers
Hasura Event Triggers

Start a Hasura instance

To be able to follow this guide you need to set up Hasura. The simplest way to quickly get your own Hasura instance is to create a Nhost project. Every Nhost project comes with Hasura, together with PostgreSQL, authentication and storage.

Log in to your Nhost account and create your project.

Create a new Nhost project
Create a new Nhost project

Nhost takes a few seconds to create your project. Hasura is now available for you and the Hasura console URL is presented to you on the dashboard.

Nhost dashboard
Nhost dashboard

Use the HASURA_ADMIN_SECRET (under the Hasura menu) to login to your Hasura web console.

Login to the Hasura console
Login to the Hasura console

In the Hasura web console you have full access to managing Hasura and your database.

Hasura console
Hasura console

Summary

This was a brief overview of Hasura, what it is and what it can do. We have explained that Hasura creates a GraphQL API based on your database. Hasura also provides a console where you can manage your database.

GraphQL is a query language that lets you get data with a relations in an easy and intuitive matter.

Try Nhost for Free Today

Get a perfect backend with Hasura
Get started