Hasura for beginners

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.

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.

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:

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:

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.

GraphiQL

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

Remote schema

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

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.

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.

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.

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

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

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.