GraphQL

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

Golang Community Moderator. Software Engineer - Open Source Enthusiast. Goper Lover

Published · Jul 9 2019

  
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…
Quickstart with Docker | Hasura 1.0 documentation

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 

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…
Installing the Hasura CLI | Hasura 1.0 documentation

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).