Getting Started With Hasura GraphQL

Hasura is a GraphQL engine that sits on top of PostgreSQL. Its a great way to introduce yourself to GraphQL


Hasura is a GraphQL engine that sits on top of PostgreSQL. Hasura will introspect a PostgreSQL database schema and build a GraphQL schema from that database schema. It’s a great way to introduce yourself to GraphQL and get something up and running very quickly.

It does have some small rough spots, but for the most part, it’s quite capable, even in its current incarnation of version 1.0.0-beta.2. This post will introduce Hasura by building a small GraphQL schema driven from the PostgreSQL schema that I’ll build up using the Hasura console. The accompanying GitHub repository can be found here.

Installing the Hasura GraphQL engine

There are a couple of different ways to use Hasura locally. I picked the Docker Compose approach, which runs two Docker container for the solution: one for PostgreSQL database engine and another for the Hasura GraphQL Engine. Just follow the documentation at…

It’s pretty straightforward documentation and running a single docker-compose up -d command is all you need to get the entire system up and running. Great out-of-box experience! However, I had a port conflict for port 8080:

A quick investigation with lsof revealed the culprit…
sudo lsof -iTCP:8080 -sTCP:LISTENCOMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME kube-apis 19412 root 3u IPv4 301080 0t0 TCP localhost:http-alt (LISTEN)

Looks like my Kubernetes installation conflicts with Hasura. I changed the ports configuration in the docker-compose.yaml file for the graphql-engine, as displayed below:
graphql-engine: image: hasura/graphql-engine:v1.0.0-beta.2 ports: - "8081:8080"

The default docker-compose YAML file has the integrated console enabled, so you can just navigate to http://localhost:8081 to view it and start playing with Hasura.

The Hasura Console
The Hasura Console

Installing the Hasura CLI

The next step in my experimentation with Hasura was to pull down the CLI tool. This tool is needed if you plan to use the Hasura database migrations feature. Follow the documentation at…

Again, the documentation is straightforward. When starting the Hasura console from the CLI tool, you do need to disable the console from coming up in the docker-compose.yml file: HASURA_GRAPHQL_ENABLE_CONSOLE: “false”. Make that change and restart your Hasura docker-compose system.

Once the docker containers are back up and running, from the command line, execute the following: hasura init --directory hasura --endpoint http://localhost:8081. This will initialize a project directory for the Hasura CLI to run the console from. The project directory will be use to maintain migration YAML files for creating the database schema. Change directory to the hasura directory and start the Hasura console from the CLI: hasura console. If all goes well, the Hasura Console should come up in a browser window (that is started by the CLI).

Creating your database schema

Your database schema can be created through the Hasura Console and all changes will be recorded in the migrations YAML files stored in hasura/migrations directory. The Hasura Console will create up and down migrations in this directory to allow migrating up and rollback back database migrations to the PostgreSQL schema.

Resetting Hasura when things go awry

I was working on two different systems, trying to keep the database schema in sync and simulation what multiple developers might encounter when using Hasura. Needless to say, it didn’t take me long to get one of the systems into a state where I could not apply new migrations pulled down in the git repository.

I finally just nuked all the tables and tried to reapply all the migrations. That did not work at all. I finally came upon a blog post (https://blog.hasura.io/resetting-hasura-migrations/) that described how to basically reset your system. Since I had all the migrations in source control, I blew away my database tables through the Hasura Console and reset the schema_migrations table:
TRUNCATE hdbcatalog.schemamigrations;

This SQL can be copy-pasted into the SQL window in the Hasura Console and executed. Once this step completed, I was able to run my migrations from the command line by executing: hasura migrate apply.

Generated GraphQL schema

Once you have one or more tables, you will notice that Hasura will auto-generate the GraphQL schema and API for you to use for interacting with your database via GraphQL. For each table, a collection query is generated for retrieving an enitty collection along with filters for…
  • distinct records based on a attribute
  • limit the number of records in the result set
  • offset index into the result set (along with limit, helpful for pagination)
  • ordering the result set by attribute value
  • and a where input for constraining the result set based on attribute value

There are also queries generated for entity aggregate and finding a single entity by it identifier (primary key value). Subscriptions are also generated that mirror the generated queries. The generated GraphQL API for querying and asynchronous subscriptions is quite full featured and should provide adequate coverage for most needs. Mutations for creating, updating and deleting entities are also generated.

Conclusions

I really like the out-of-box experience that Hasura provides. This is probably the easiest way to get a taste of GraphQL and do something that isn’t a complete toy. I really like how they went after creating a GraphQL mapping to a relational database schema. Most people get relational database schema, so it grounds a new concept (GraphQL) in a well-understood concept (relational schema).

Never miss a post from Chris Gregori, when you sign up for Ednsquare.