PostGraphile is packaged as a Node.js module, you can install it with
yarn (depending on your preference) - users tend to have fewer issues with
yarn, so we recommend it.
We recommend using the latest LTS version of Node.js and PostgreSQL, but we have limited support for older versions. Using newer released versions should work fine (we don't recommend using with alpha/beta versions though).
Your PostgreSQL database
These aren't exactly "requirements", but they will impact your PostGraphile experience.
- Use primary keys: if you don't have primary keys on your tables then they
won't get the
nodeIdglobally unique identifier interface. Further if you don't have unique constraints then you won't be able to use the automatic update/delete mutations.
- Use foreign keys: we infer relations between tables using foreign key constraints; if you don't use these constraints then we won't know there's a relationship between the tables. There are plugins to get around this (using smart comments) but it's highly recommended that you use PostgreSQL's built in relations support.
- **Don't use column-based SELECT grants**: column-based grants work well for `INSERT` and `UPDATE` (especially when combined with `--no-ignore-rbac`!), but they don't make sense for `DELETE` and they cause issues when used with `SELECT`. Quite a few things in PostGraphile depend on full-table `SELECT` grants; if you don't want to use full-table grants then you will need to disable the default mutations and use custom mutations instead (because we use `RETURNING *` on the mutations), you may also have to miss out on computed columns (because we pass the entire row object to the function, though these typically still work if you're using `LANGUAGE sql` rather than `LANGUAGE plpgsql`/etc). It's recommended that you instead split your tables on permission boundaries and use one-to-one relations to join them together again - this also makes writing your RBAC/RLS policies simpler. If you want to omit a column entirely then you can use the [`@omit` smart comment](./smart-comments/#omitting).
- Function restrictions: we have pretty good support for PostgreSQL functions, but there's some common function restrictions you should check out.
- Use unique constraints rather than unique indexes when appropriate: we use
unique constraints to create mutations such as
updateUserByUsername; note that "PostgreSQL automatically creates a unique index when a unique constraint or primary key is defined for a table." -- PG docs
- Use the defaults for formatting output; for example we only support the
intervalstyle = 'postgres'rather than
intervalstyle = 'iso_8601'. Many times this can be solved by returning the relevant default setting value from the pgSettings function.
- Use UTF8 encoding: GraphQL operates over the UTF8 character set, using different encodings may impact your ability to store/retrieve certain values.
On top of this standard PostgreSQL best practices apply: use indexes carefully for performance, use constraints to ensure your data is valid and consistent, use triggers to take an action when something happens, etc.
Node.js: use the LTS
From PostGraphile v4 onwards, PostGraphile requires Node.js version 8.6+ which
provides native support for
await and supports many of the ES2017 and
PostgreSQL: use latest
For best results we recommend you use the latest stable release of PostgreSQL that we officially support (v14 at time of writing), however it should run well on 9.6 or higher and anything that breaks v9.6 support will be deemed a breaking change. The absolute earliest version it will run well against is v9.4, however we do not support this version officially - we strongly recommend you upgrade.
PG 9.4 [not officially supported, but works]
Basic operation including introspection.
PG 9.5 [not officially supported, but works]
Introduces Row-Level Security - important for securing your schema.
PG 9.6 [officially supported]
missing_ok parameter to the
function - without this you'll need to ensure all
reference settings that always exist (e.g. you may need to set them on the
--watch is also only officially supported on 9.6+ (although it might work on
PG 10 [officially supported]
PostgreSQL 10 solves a number of performance issues - the most interesting of which for us is a significant performance boost to Row Level Security policies!
Introduces "identity columns" which we have preliminary support for.
PG 11 [officially supported]
PG 12 [officially supported]
PG 13 [officially supported]
PG 14 [officially supported]
PostGraphile is developed on Mac OS X and tested on GNU/Linux. It works on Windows and we would like to officially support Windows but no-one in the core team uses Windows so we need your help for this. Please get in touch if this is something you'd like to help with.