Intro to PostGraphile V5 (Part 5): Polymorphism!

Benjie is the community–funded maintainer of the Graphile suite — a collection of MIT–licensed Node.js developer tooling for GraphQL and/or PostgreSQL. A key project in this suite is PostGraphile, a high performance, customizable and extensible GraphQL schema generator for APIs backed primarily (but not exclusively!) by PostgreSQL.

This is part five in the "Intro to PostGraphile V5" series, which started with Part 1: Replacing the Foundations. This week, Benjie takes a look at how Grafast enables PostGraphile to support polymorphism; you can get your hands on the pre–release now by becoming a sponsor — see postgraphile.org

Polymorphism in GraphQL is where a field can return different types of things. For example a field might state it will return a Pet, but at runtime that must actually be a Cat or a Dog:

interface Pet {
  id: ID!
  name: String!
}

type Cat implements Pet {
  id: ID!
  name: String!
  color: String
}

type Dog implements Pet {
  id: ID!
  name: String!
  breed: String
}

In the above case, Pet is an interface type which means that every type it can be has to implement at least the shared fields.

However, there are also situations where there aren't shared fields — for example your morning alarm might be your phone, or it might be your hungry cat — for these, we use a union type:

union MorningAlarm = Device | Cat

type Device {
  make: String!
  model: String!
}

Polymorphism can be very important in GraphQL APIs, and yet has been traditionally overlooked in PostGraphile due to the complexity of implementing it in the old look–ahead system, and concerns over runtime performance. In fact it's one of our longest running issue threads: https://github.com/graphile/postgraphile/issues/387

But no more!

Thanks to the magic that is Grafast, we now support both interfaces and unions at the planning layer, and you can now use smart tags to indicate to PostGraphile that a given table (or set of tables) is polymorphic so that PostGraphile will automatically generate the interfaces/unions and types for you!

We support a number of patterns of polymorphism in your PostgreSQL database, the most common of which is probably the "single table inheritance" pattern, where you have a table containing a type column indicating the type of the row, and columns for all the different attributes that the different types may need. We also support "relational polymorphism" where a central table represents an interface and stores all the common attributes (plus the type), and then this table is one–to–one joined to another table (depending on the type) which has additional columns specific to that type.

Unions are much simpler, you can simply declare that any of your tables belongs to a particular union via the @unionMember smart tag, and that union will be created if it didn't already exist, and the table added to it.

We also support more exotic forms of polymorphism, including a many–join–tables polymorphism pattern that Netflix uses with PostGraphile V5, and Grafast is flexible enough that we can add more patterns over time if the need arises! It's worth keeping in mind that Grafast itself is completely independent of data source, so though we have built in a number of optimized polymorphic patterns for Postgres into PostGraphile, Grafast users can leverage flexible polymorphism no matter what data sources they are using.

If you have access to the V5 documentation, you can read more about it here: https://postgraphile.org/postgraphile/next/polymorphism

This has been one of the most eagerly anticipated features of PostGraphile V5, and I'm extremely excited to announce that not only is it now, finally, possible; but it has been since late last year and the early adopters are getting on well with it!

A happy user of V5 polymorphism.

Next up, another massive feature of V5 that'll be loved by serverless aficionados and people concerned about being locked into a PostGraphile schema alike!

Check back next week to find out what the next new feature is Next, check out Intro to PostGraphile V5 (Part 6): Excellent Executable Exports; and remember: to get your hands on a pre–release version of PostGraphile V5 including all its polymorphic goodness, all you need to do is sponsor Graphile at any tier and then drop us an email or DM! Find out more at graphile.org/sponsor