GraphQL, PostgreSQL & Hasura (Pt1)

Photo: Unsplash - Isaac Smith

In a recent project, we decided to build our backend in Hasura. This was my first time working with it and I have been impressed with the ease and power it provides. Essentially, Hasura melds the GraphQL language with PostgreSQL database to provide easy and fast real-time API’s powered by your data schema. In this post, I will cover GraphQL (at a high level) and how Hasura makes it easy to set up an API in no time.

(This is based purely on my recent experience and I am not in any way affiliated with Hasura).

GraphQL

GraphQL is an open-source query language that was developed by Facebook. It was released publicly in 2015 and is designed to power API’s by providing a runtime that allows clients to query just the data they need without the complexity and baggage of something like an ORM. Its flexibility means it makes evolving API’s overtime easier and it speeds development by removing the need to generate as much boilerplate code. For example, using an ORM like Objection.js you might write something like the following:

const person = await Person.query().findById(1);

console.log(person.firstName);
console.log(person.lastName);

This means that you are returning the whole Person record to be able to generate an object which the data is mapped to. You are then just using a small subset of the fields on that object. With GraphQL you can query just the data you need rather than having to return a whole record. The above query in GraphQL could be written as:

query{
  person{
    firstName
    lastName
  }
}

Which returns

{
  "person":{
    "firstName": "Donald",
    "lastName": "Duck"
  }
}

This is a trivial example but shows the power behind GraphQL Ask for what you want and get the response as JSON. The GraphQL language includes everything you need to create, read, update and delete data. Query’s, such as the snippet above, allow you to read existing data, Mutations allow you to create, update and delete data and Subscriptions allow you to monitor part of your schema to receive real-time updates.

Rather than provide a walk-through of GraphQL top to bottom I recommend you read the excellent tutorial on GraphQL.org.

PostgreSQL

PostgreSQL doesn’t really need an introduction as it really is the most advance open-source database available. If you have worked with SQL Server or a MySQL derivative then you will be at home. In the way in which Hasura works you do not need to interact with PostgreSQL directly. If you do want to learn more about it then the documentation can be found here.

Hasura

Setting up a playground to test Hasura is very easy. You can deploy an image to Heroku on their free tier and be up and running in minutes. Once deployed you will have a PostgreSQL database and an endpoint with which to access Hasura. I followed the tutorial for building a todo app which can be found here. I should mention I have found their documentation really good.

Once you are up and running you access the UI from your browser.

There are 4 main tabs to the UI labelled:

• Graphiql
• Data
• Remote Schema’s
• Events

All running GraphQL instances provide graphiql which is a repl type environment in which you can build and test your queries, mutations and subscriptions. The Hasura version is standard and provides automatically generate documentation and point and click query building capabilities.

The Data tab is where you will design and build your database schema. You have a point and click UI that simplifies the design of tables, keys and relationships. There is also a SQL pane in which you can create any PostgreSQL items you want such as functions or triggers. These can then be used from the UI to link functions, views and triggers to your schema.

The Remote Schema and Events tabs are powerful features which I want to cover in more depth in a follow-up article. The Remote Schema tab allows you to set up and consume one or more URL’s as part of your Hasura Schema. This means that you can write a Serverless function, for example, that accepts data to pass to a REST API but which exposes the results as GraphQL. The Events tab allow you to hook into schema-based events and react to them. So, again, you can use Serverless functions to process a new entry in a table and push the results to an endpoint or a different table.

After working through the tutorials I could immediately see how good this software could be. I still had questions around security and manageability:

• Security - How easy is it to secure and what about Role Base permissions. Firstly, you can secure the entire Hasura instance with a password which is passed in all requests as a request header. It also then means if you try to visit the instance from your browser you will also need the password. Hasura provides full Role-Based permissions that can be added to each table and right down to actions on the table.
• Manageability - First off migrations. They provide a migration framework through the Hasura console app that means you can push changes from your development instance through to staging and production with a simple command. I have opted to use Digital Ocean as a host as Hasura offered one-click deployment but they also support Azure and Google Could. Applying a custom domain was as easy as creating an A record for your domain and using the IP address of your instance. They also provide a health monitoring endpoint on each instance via /healthz.

All the features I have outlined in this post are available on the free tire and the performance is only limited by your hosting provider. I really am impressed by how we have used Hasura so far and how easy it has made creating API’s.

I will follow up to this post with more detailed howto around the Remote Schema and Event functionality. In the meantime if you have used Hasura for a project or have any interesting tips then let me know via twitter or email.