Learning GraphQL through PostGraphile

This post will not walk through how to do anything in particular — it’s not a tutorial. It goes through what I learned and points to tools and documentation I used to get started — which might be a good starting point for others.

I recently wanted to take a jump into learning GraphQL, so I sped through this (opens in a new tab) course (way shorter than it looks). For some reason, I had this mental barrier thinking GraphQL was more complicated than REST, but the fundamentals are actually quite simple. The way this course framed GraphQL made it easy to understand.

I knew some friends that had used and spoke highly of PostGraphile (opens in a new tab), a tool written in TypeScript that reads your PostgreSQL database schema and generates a GraphQL API on top of it. I went through all of the documentation and ended up learning a lot more about database design in the process. In effect, by learning PostGraphile and actually trying to build an initial project with it, I learned about GraphQL and more about Postgres. It was awesome to double dip and become more familiar with some of the many powerful features Postgres has.

PostGraphile forces you to think of the database as your application. Another way to do put it is that you’re doing database-driven-design. Now you might be wondering, how do you actually get work done (e.g. send emails)? One awesome tool the same folks have built is called worker (opens in a new tab). This allows you to use your database as a job queue, that your javascript code can pull jobs from and do work. Additionally, if you check out the PostGraphile documentation, there are easy ways to extend your GraphQL schema so you can add your own queries and mutations, similar to how you might do it if you had to write your own schemas and resolvers. You can use migrate (opens in a new tab) to write your SQL migrations. Migrate simply has you write SQL files and the migrations run quickly.

Something to note is that if you run primarily on PostGraphile, you will likely end up using Node.JS (or any compile-to-JS language, e.g. ReasonML) for anything related to PostGraphile or its workers due to the tools being written in TypeScript. Extending PostGraphile easily with plugins requires JS code in your codebase.

I’m not sure if people would typically recommend learning GraphQL through a tool like this, but I found it great to get started. Anything that runs through PostGraphile’s autogenerated schema (not necessarily custom stuff you’ve written) also avoids N+1 query problems, as your GraphQL query is parsed into a SQL query prior to running against your database, keeping things performant. I saved a ton of time building with PostGraphile, and you get lots of interesting benefits doing things through DB-driven design. You could build say, a user-facing API and admin API largely just by setting database permissions per table, without having to write entire APIs or dealing with security for it separately. You can build a lot more a lot faster, especially as you aren’t spending time in your REST APIs thinking specifically about what query you need to write to get certain data. You spend a lot more time in the database, but less time overall.

After giving PostGraphile a try, if you use Node.JS or are willing to have part of your project in it, I would highly recommend PostGraphile!