crystal

• Look for jwtSecret in process.env.JWT_SECRET (#1236, @AxelUlmestig)
• Update supported pg version range to support Node 14 (#1270)
• Expose parseTags, withPgClient and getPgClientAndReleaserFromConfig from graphile-build-pg (engine#601, @enisdenjo)
• Don't query roles when ignoring RBAC (engine#598, @jnbarlow) - reduces introspection time on databases with a very large number of database roles
• Fix index signature of JSONPgSmartTags (engine#618, @LeoBakerHytch)
• Various other docs and code maintenance events

If you're using self-signed certificates for your PostgreSQL database, either keep your pg version pinned to whatever it is currently, or read: https://node-postgres.com/announcements#2020-02-25.

Please note that we do not consider widening the range of a supported module to be a breaking change. You should use a lockfile and only upgrade the dependencies you intend to. Read more in our versioning policy.

The main features in this release are:

• smart-tags: ability to @omit many from foreign key constraints (https://github.com/graphile/graphile-engine/pull/565; thanks @ab-pm)
• graphql: support non-scalar value ranges (https://github.com/graphile/graphile-engine/pull/591; thanks @singingwolfboy)
• pg-pubsub: the @pgSubscription directive now supports a filter argument (#596; thanks @enisdenjo)

We also did an amount of housekeeping including adding a couple minor TypeScript types, improving our snapshot tests, and adding more tests on the built project.

IMPORTANT: we released a preliminary 4.6.0-alpha.0 which completed conversion of the entire project to TypeScript (finally removing Flow from its last places) but unfortunately the type churn was too high for this to be included in a non-breaking update (even though it was only the types that changed) so we decided to move the release of TypeScript conversion until v5 of PostGraphile. Effectively we're going to pretent v4.6.0-alpha.0 never happened.

Additional fix to smart tags; be sure to update graphile-utils to 4.5.6 too!

(v4.5.1-v4.5.3 were skipped)

Fixes some Smart Tags teething problems (specifically related to fake constraints).

Features

• utils: makeExtendSchemaPlugin accepts typeDef array (#574) (82ff872) thanks @jkantr

Bug Fixes

• utils: fix smart tags for attributes (324f066)
• utils: to match early enough, we need build to be passed (9aa5565)
• deps: bump graphile-utils peerDependencies (cd6b52a)
• smart-tags: enable using Smart Tags with @foreignKey and @primaryKey (#586) (b2d8c65)
• utils: only apply condition when specified (#572) (314fce1)
• utils: make makeAddPgTableConditionPlugin work on simple collections (#569) (0a4db65)

Lots of pull requests and documentation improvements from the community in this release! 🙌

First, things to be aware of before you deploy:

• previously the CLI would ignore arguments it didn't understand (dangerous!) now it exits stating the arguments it wasn't expecting
• more improvements have been made to our TypeScript types, and there's more to come, so your builds might need some minor type tweaks

New feature spotlight: explain

In enhanced GraphiQL you can now toggle 'Explain' to view the generated SQL and the query plan of that statement. This is not enabled by default - you have to opt in with --allow-explain, or in library mode you can supply an allowExplain(req) function that determines on a per-request basis if the user may use the explain functionality or not.

New feature spotlight: Smart Tags

No longer do you need to put COMMENT commands in the database ("smart comments") to customise your schema, you can now use a tags file to gather these "smart tags" into one, version controlled, easy to diff, place. Smart comments and smart tags can be used in unison, and both will be supported going forward so you can pick whichever works best for your team. In library mode you can manage smart tags however you like, and it's possible to pull smart tags from multiple sources and they will be automatically combined. Find out more about smart tags here: graphile.org/postgraphile/smart-tags/.

Community member @singingwolfboy has drafted a JSON schema definition that may help editors such as VSCode to help you when editing the default postgraphile.tags.json5 file. We've not upstreamed it yet, but hopefully will do so in the coming months.

New video

Team Graphile went to ReactiveConf in Prague last month; check out Benjie's talk Increasing Velocity with GraphQL and PostgreSQL.

🙏 HUGE THANKS TO NEW, EXISTING AND PREVIOUS SPONSORS! 🙏

We now have 84 sponsors across GitHub and Patreon and that means we're funded to spend an average of nearly 2 days per week on Open Source; this is brilliant!

Don't forget GitHub are matching sponsorship currently - so do sign up to be a sponsor if you haven't already - the more time we can put into open source, the faster we can build awesome tools for you to build epic software with!

Changes

Features

• graphiql: add 'explain' button (#1179) (1a065ab)
• jwt: support lazy public key loading for verification (#1167) (d27aaf9); thanks @ab-pm
• tags: add postgraphile.tags.json5 support (#1177) (7da3c7f), closes graphile/graphile-engine#529
• jwt: add asymmetric JWT signing and verifying support (#1089) (b4730b7); thanks @speller
• graphiql: save headers to localStorage (#1174) (37abcd3); thanks @phryneas
• connections: expose totalCount on custom connections (#529) (b6c08cf); thanks @mattbretl
• pg: add partial index detection to introspection (#535) (360e5e0); thanks @hansololai
• pg: add support for cidr and macaddr types (#520) (676c3f2) - opt in with pgUseCustomNetworkScalars; thanks @higherorderfunctor
• QueryBuilder: new methods for managing QB children (#537) (1a8a0bc); thanks @singingwolfboy
• utils: @pgQuery support for scalars (#534) (49259c2); thanks @phryneas/Mayflower
• utils: @pgQuery.source can be function (#555) (907c8e6)
• utils: add makePgSmartTagsPlugin (#541) (40a7bfa)
• utils: makeExtendSchemaPlugin supports enums and default values (#562) (2a23aee)
• types: various improvements to the TypeScript typings, including making Middleware generic
• export: only write schema if it differs (#1180) (6334897)

Bug Fixes

• cli: abort if given unused arguments (#1181) (3e7381d)
• jwt: allow JWT exp to be bigint (#542) (69c7e8e)
• omit: if you omit update on all columns don't throw (#531) (b5d9e99)
• pagination: fix bug in cursor pagination for PL/pgSQL SETOF… (#559) (0089a07)
• types: correct tuples to arrays in pgIntrospectionPlugin (#530) (6488d5c); thanks @hansololai
• types: export more types inc PgIntrospectionResultByKind (#532) (1689f66); thanks @hansololai
• types: minor TypeScript fixes (#545) (0170064); thanks @benhjames
• types: use jwt.Secret type in PostGraphileCoreOptions (#546) (be18000); thanks @ab-pm
• watch: don't built schema twice in watch mode (#558) (0a36f7b)
• graphiql: fix operation detection on multi-op documents (#1191) (49b2176)
• utils: make makeAddPgTableConditionPlugin work on simple collections (#569) (0a4db65)

We're no-longer listing chore-level items, but there have been a lot of them. Special thanks to @singingwolfboy for helping me to keep the codebase tidy.

General maintenance release.

Features:

• Add experimental plugin generators for adding conditions, orders (https://github.com/graphile/graphile-engine/pull/517)
• readCache can now pass an object to be used as the cache (@garcianavalon, https://github.com/graphile/graphile-engine/pull/479)

Fixes:

• Fixed a 3 year old bug in the introspection query (means correct CRUD mutations are generated for views with triggers) (@rudism, https://github.com/graphile/graphile-engine/pull/508)
• Improved the error message when orderBy is not unique and before/after are attempted (@soutot, https://github.com/graphile/graphile-engine/pull/515)
• Improved error messages for smart comments (https://github.com/graphile/graphile-engine/pull/525)
• Remove sortable/filterable from functions that require args (@mattbretl, https://github.com/graphile/graphile-engine/pull/519)
• Ensure X-GraphQL-Event-Stream is domain relative (@mathroc, https://github.com/graphile/postgraphile/pull/1148)
• Recommend using --init with Docker; turn off progress bars

Chores:

• Updated to latest GraphQL, so @types/graphql is no longer required (@none23, https://github.com/graphile/graphile-engine/pull/511)
• Updated to latest Flow (@none23, https://github.com/graphile/graphile-engine/pull/514)
• Standardise database setup instructions (@ab-pm, https://github.com/graphile/graphile-engine/pull/512, https://github.com/graphile/postgraphile/pull/1145)
• Move from TSLint to ESLint (https://github.com/graphile/graphile-engine/pull/526)

makeExtendSchemaPlugin in the last release disabled the built-in directives @include and @skip; this hotfix restores them.

Benjie has been approved for GitHub Sponsors and for a limited time GitHub are match-funding, so there has never been a better time to support development of this software!

Talking of sponsorship, please check out our new featured sponsor, Timescale!

This is mostly a maintenance release, no major new features.

Features:

• updated to the latest version of GraphiQL explorer (see their release post)
• you can now pass jwtSignOptions to PostGraphile, thanks to @speller
• makeExtendSchemaPlugin now supports defining unions, directives and scalars (required to support Apollo Federation, which you can try out with @graphile/federation); unions only work in certain places and are currently undocumented (and thus unsupported)
• new hideIndexWarnings option for when you have ignoreIndexes: false thanks to @tinymarsracing
• various code has been tidied/fixed/modernised thanks to @singingwolfboy
• auto-coerce numeric field names to begin with an underscore (shouldn't affect existing users)

Fixes:

• node identifiers have been made safer:
  • If you have identically named tables in different schemas and you use relay global object identifiers (on by default) you'll be warned, and encouraged to disable the PgNodeAliasPostGraphile plugin to solve it
  • If you use bigint or bigserial in your primary key, values greater than 9 quadrillion (technically > 9,007,199,254,740,991) are now treated as strings in the node identifier, so nodeId is now valid for these
  • 🚨 BREAKING: if you use money, or decimal/numeric or some other weird numeric type in your primary keys these will now also be represented as a string within the base64-encoded node IDs, so your node IDs will change. If this affects you (unlikely?) please get in touch with Benjie (to be clear: int, int2, int4, float, float4 and float8 are unaffected; and int8/bigint only changes node IDs for values over 9 quadrillion)
• fix issue with default values for orderBy argument on edge fields on mutation payloads when printing the schema
• mark fake constraints (e.g. @foreignKey smart comment) as indexed so it works nicer with ignoreIndexes: false
• @graphile/pg-pubsub now uses exponential back-off when server shuts down, rather than giving up after 9 attempts
• more validation is applied to cursors in connections
• fix misleading description of queryCacheMaxSize
• fix docs for jwtRole, thanks to @bidoubiwa

The main feature of this release is significant performance improvements — enjoy!

We also overhauled how Docker builds work, so they're now tagged in a more sensible manner. Almost all previous tags have been deleted. From now onwards we have versioned Docker images:

• graphile/postgraphile:4 will give you the latest stable in the "v4.x.x" line (no alphas, betas, rcs); this is the recommended version to use
• Every new vX.Y.Z git tag (i.e. no alpha/beta/rc) will automatically release graphile/postgraphile:X-Y and graphile/postgraphile:X-Y-Z
• graphile/postgraphile:latest will give you the latest stable (but beware of major version bumps!)
• graphile/postgraphile:next will give you the equivalent of what's on master right now (i.e. pre-release/bleeding edge/nightly)

We're currently in a teething period for this, so there may be some bumpiness - if you face any issues, please let me know via GitHub issues or discord.

NOTE: this only applies to future releases; we are not back-filling previous releases, so there's not many tags to choose from right now.

Other changes:

• update various dependencies
• significant performance improvements
• fix a bug with standalone LDS server announcements for insert/update (thanks @pepijnverburg)
• export more TypeScript interfaces from graphile-utils
• add missing dependencies (thanks @michaelbeaumont)
• respect externalUrlBase for websockets (thanks @DvdGiessen)
• typo fixes (thanks @angelosarto, @ludwigbacklund)
• add support for PGHOSTADDR envvar if PGHOST is not present (thanks @encima)
• 🚨 Remove invalid fields from payloads for SETOF function mutations (these fields were never valid, so any client using them would already be broken, thus I am not classing this as a breaking change).

Please sponsor development (anything from $1/mo) or take out a support contract to help fund ongoing development on the project. PostGraphile is liberally licensed and relies on crowd-funding to advance.

Thanks to the continuing sponsorship from PostGraphile's community, we've added to PostGraphile core what you've all been waiting for - GraphQL Subscriptions, and Live Queries!

GraphQL Subscriptions

We've enhanced PostGraphile with subscriptions / websockets functionality, including adding subscriptions support to our built in GraphiQL IDE (no more need to test with external GraphQL clients!). To get this you have to opt-in via the --subscriptions flag (library: subscriptions: true).

You can use our simple subscriptions listen endpoint, or easily write your own subscription endpoints using makeExtendSchemaPlugin - it's all documented on our website. PostGraphile subscriptions can use Postgres' LISTEN/NOTIFY, or any other source of realtime data — you decide what makes sense for your application.

Subscriptions are the recommended way for adding realtime features to PostGraphile.

PostGraphile Live Queries

More experimental and much heavier on the database is our live queries support — suitable for use in internal tooling within your company, but perhaps not for the internet at large. You can opt-in via the --live flag.

We've built into the core of PostGraphile the ability to track when collections/records are referenced (and the filters that apply to them, such as foreign key constraints and conditions); you can then combine this with one or more realtime provider plugins which inform PostGraphile when these tracked resources change, triggering the query to be re-executed and the result sent to the user.

This feature is exposed over standard GraphQL subscription operations so you should be able to just switch out query with subscription at the beginning of your GraphQL document to make it live. No need for specific client support — it supports all clients that support subscriptions. (We plan to support the @live directive optimisation available in Apollo Client in a future release, should demand be sufficient.)

We recommend using simple request documents with live queries because each time a relevant row is changed the entire document is recalculated and sent to the user: more complex queries will consume more resources when recalculated and will likely be triggered more frequently, leading to non-linear performance costs. (Note: we throttle updates to prevent overwhelming the client or the server, and this throttle period is configurable.)

Our first live queries provider plugin, @graphile/subscriptions-lds uses PostgreSQL's extremely efficient logical decoding functionality to stream changes out of the database using the replication interface. It requires you to tweak a couple of settings in postgresql.conf but is otherwise simple to set up - see the documentation on the website which also includes instructions for Amazon RDS.

Note that live queries are still experimental, and have not been performance optimised yet - please let us know of any issues you face!

Other features

Docker compose/kubernetes users may appreciate the new --retry-on-init-fail flag that means PostGraphile will keep trying to rebuild the initial schema, so with this flag it can be started before the database is ready. (Uses exponential backoff with a 30s cap.)

We've increased performance for queries that use large offset values (so long as the relevant table is not using column-level select grants, which are not recommended with PostGraphile).

makeExtendSchemaPlugin now has support for re-using existing Relay Connections; it can also be used with the @pgQuery directive to add connections deeper into the schema. The documentation has been updated with more details.

You can now add your own aggregates to connections using our new aggregates infrastructure. totalCount on connections has been re-written to use this, and there are more examples (e.g. exposing SUM(...)) in the PR description: https://github.com/graphile/graphile-engine/pull/415; if you require certain aggregates please get in touch.

Thanks to @dijam we now accept Buffer objects as jwtSecret in addition to strings.

build.scopeByType was added to enable plugin authors to get from a GraphQL type the scope it was created with - useful for finding the PostgreSQL table associated with a GraphQL object type, for example.

Plugins now have a dependency ordering system, so we can move to using --append-plugins for everything and have hooks register their own positions. This system is not yet documented (or final) so is not officially supported yet, but it's a good way to easily enable features that previously involved a complex setup.

Many more tests were added.

--owner-connection / ownerConnectionString setting added, to give PostGraphile access to a privileged Postgres account. It is needed for logical decoding, but it's now also used (if present) to install watch fixtures and avoid the "Failed to setup watch fixtures in Postgres database" error. It is recommended in development for the watch schema, but only recommended in production if you are using live queries.

Newly introduced @simpleCollections smart comment enables you to override the simpleCollections setting on a per-table, per-relation and per-function basis. I.e. you can now opt-in to using the list interface (rather than Relay connection interface) in certain places without affecting the rest of your schema.

Filterable, filter-by-able, sortable and sort-by-able functions support was introduced in 4.3.1.

GraphiQL Explorer support added in 4.3.2;

🚨 Breaking fixes

These are fixes that might break you schema if you were relying on the broken behaviour (please don't do that!). We've added flags to some of them so you can maintain the old (broken) behaviour should you need to.

• Fixed issues with arrays of certain types (interval, etc) incorrectly having a String input type (opt out with disableIssue390Fix - ref https://github.com/graphile/graphile-engine/pull/405)
• If you're using --simple-collections only we still used to add Relay edges to mutation payloads (these edges are pointless without the connections they applied to). We've corrected this oversight by removing them, but you can add them back with the disableIssue397Fix flag - ref https://github.com/graphile/graphile-engine/pull/408)
• graphile-utils: if you were using makeExtendSchemaPlugin to add a field returning a Connection type, this will not have been working correctly. Instead of returning return {data: await selectGraphQLResultFromTable(...)} from your custom resolver you should now just return the result of selectGraphQLResultFromTable directly: return await selectGraphQLResultFromTable(...), and then pageInfo and the rest will work correctly. The makeExtendSchemaPlugin docs have been updated, worth a re-read. If you're affected by this and don't make this change, you'll see errors like TypeError: data.data.map is not a function.

Fixes

• PostGraphile handles PostgreSQL server restart much more gracefully
• Improved error messages when no values were deleted/updated because of RLS
• Fully qualify reference to hstore to handle issues in search_path
• Lots of improvements to TypeScript typings
• Domains with defaults now exposed as nullable (thanks @mattbretl)
• Fixed an issue with relations on custom mutation payloads when the custom mutation returned null without an error
• Fixed an issue with an entire record being returned as null when you only request nullable columns. The fix requires you to provide --subscriptions or --live flags as it requires you to have granted select to at least the primary keys of the tables you expose
• makeWrapResolversPlugin can now replace the arguments that are pass to PostgreSQL function calls for root-level custom queries and mutations.
• totalCount is now non-nullable because I couldn't find any justification for it being nullable and no issues came up during the beta and RC phase
• Fixed a bug in the times generated by the PostGraphile logs
• Exposed the X-GraphQL-Event-Stream header (thanks @imolorhe)
• Stricter pool validation
• Fixed an issue with HTTP2 support in Fastify
• Fixed hasVersion to allow pre-releases
• Include namespaceName in introspection for extensions

Fixes an issue one of the PostGraphile sponsors had where sharing the PgPool between their own code and PostGraphile, using pgPool.query, and setting DEBUG with the SQL-outputting debug variables caused an error to be produced. https://github.com/graphile/postgraphile/pull/987

The lovely folks over at OneGraph sent a PR to integrate their GraphiQL Explorer into PostGraphile — this awesome feature really helps users get started with GraphQL. Make sure you're using --enhance-graphiql to use it! #981

Additionally @mlipscombe discovered an issue where your PgPool could become exhausted if an enough errors were thrown on COMMIT, and sent over a PR to fix: #978

Important note: pgInflection should not appear anywhere in your code or that of your plugins; see below. (If it does, you'll get some warning messages, but things should continue to work for the time being.)

The main feature in this release is you can now opt-in to filtering and sorting function results (so long as they return setof table type), and enabling you to filter-by and sort-by scalar computed columns. This is opt-in behaviour on a per-function basis using smart comments because if used incautiously it could result in significant performance woes (basically: in many cases database functions are black boxes to PostgreSQL, so the full function result may have to be calculated before it can then be sorted, and if it returns millions of rows that might take a moment).

Also in this release are a number of small fixes and enhancements detailed below. See the 🚨 for a fix that may impact your schema if you were relying on broken behaviour.

PostGraphile is crowd-funded, we ask the individuals and businesses that use PostGraphile to please sponsor ongoing maintenance and development.

• functions can now be opted into filtering and sorting via @filterable and @sortable smart comments; you can also mark the result as non-nullable via @notNull smart comment (https://github.com/graphile/graphile-engine/pull/378)
• makeWrapResolversPlugin has been enhanced to allow wrapping all resolvers that match a filter function
• makeAddInflectorsPlugin has been enhanced to allow you to access previous inflectors (e.g. if you only want to override them in certain circumstances)
• yet more things are named via the inflector (and thus can have their names customised) including Query, Mutation and Subscription - just override the inflection.builtin(name) inflector
• more server plugin hooks added, enabling custom logging and tweaking GraphiQL's HTML (e.g. to add dark mode)
• accidentally passing undefined as any of PostGraphile's options now throws an error to help you more rapidly spot issues in your code (thanks @marshall007); the PostGraphile call signature has not changed
• adds compatibility with intarray PostgreSQL extension
• fixes formatting of PostgreSQL ranges, ranges that require extra processing (arbitrary precision numeric, bigint, timestamps) are now processed correctly (thanks @mathroc); 🚨 if you were using the broken ranges, please test related code
• fixed typo where the CRUD plugins used pgInflection where they meant pgIntrospection; have kept the old name too to prevent this being a breaking change, but please update your plugins to use the correct name
• the ancient inflection option to PostGraphile (which became pgInflection internally) that was deprecated in 4.0.0-beta.6 now generates warning messages if you use it, which you should not. Instead migrate to the plugin-capable inflection system
• added additional index information to introspection in case your plugin needs that (@mlipscombe 😉 )
• doc fixes (thanks @petetnt, @SiM07)
• support for Windows CRLF line-breaks in smart comments

4.3.0 was never promoted to @latest due to a couple of issues:

• more people (specifically, plugins) were using the long-deprecated pgInflector argument than expected; this has been restored in 4.3.1: https://github.com/graphile/graphile-engine/pull/381
• a small issue was introduced when implementing @sortable that broke a plugin; this is also resolved in 4.3.1: https://github.com/graphile/graphile-engine/pull/386
• too many new inflectors were introduced (all taking zero arguments); this has been replaced with a single builtin inflector: https://github.com/graphile/graphile-engine/pull/387

We're going to look into extending the release tests to running against some popular community plugins to ensure future releases don't introduce backwards-incompatible changes. If you'd like your plugin to be included in this effort, please get in touch.

Thanks to sponsorship from ULTA.io, this release introduces support for defining constraints (e.g. foreign keys, primary keys, etc) via "smart comments". This means that VIEWs and MATERIALIZED VIEWs can now act a lot more like regular tables when viewed by PostGraphile - you can define a @primaryKey for your view, or have a @foreignKey that references another table (or another view!). You can also mark fields as @notNull For more information, see the documentation:

Smart Comment Constraints

The other change in this release is that we now surface a warning message if a foreign key constraint is skipped because it lacks an index and you're using --no-ignore-indexes or ignoreIndexes: false.

Wow, this is a big release! If you have any questions about this release, please come ask in the discord chat: http://discord.gg/graphile

PostGraphile is crowd-funded open source. We use the MIT license to give you freedom in how you use it, but you should support its development by sponsoring us: https://www.graphile.org/sponsor/

View announcement for a less technical summary!

Lets jump straight in:

🚨 IMPORTANT

When updating to this version, IF you use any third-party plugins, you MUST update them too and test your application - some PostGraphile internals have changed, and although they are undocumented (and thus do not constitute a breaking change) depending on the complexity of the plugins you use they may be affected. (See below for more info.)

You should also pin your GraphQL version as this release increases the supported GraphQL version range to include v14.x which has some breaking changes.

Massively improved serverless support

Thanks to funding from Connecting Good, running PostGraphile in serverless is a lot lower latency. It's now possible to webpack up PostGraphile nice and tight, resulting is much smaller .zip files to upload to Lambda (1/10th of the previous size); massively improved unzip time (milliseconds instead of seconds); and significantly reduced I/O time during startup, leading to sub-0.5s cold-starts when combined with our caching functionality.

Instructions and a demo on how to use this are available here:

https://github.com/graphile/postgraphile-lambda-example

A documentation article should be compiled in the coming months (when someone gets time...)

Massively improved PostgreSQL function support (thanks @mattbretl!)

Thanks to a Herculean effort from @mattbretl, we now have support for many more function shapes, including IN / OUT / INOUT parameters, and the RETURNS TABLE(...) return type.

This was a massive (MASSIVE!) pull request, with a tonne of back-and-forth, and an incredibly large number of edge cases; so please do pop onto the Discord chat and congratulate Matt on a job well done!

If for some bizarre reason you don't want this awesome new functionality, Matt has even added a way for you to opt out via the --legacy-functions-only CLI flag.

--no-ignore-indexes

Following on from --no-ignore-rbac; you can now opt in to --no-ignore-indexes. If you saw my talk at GraphQL Finland you'll understand that it's very important that we only expose what the server can fulfil efficiently; this option helps you to adhere to this by not exposing relations or filters that don't have associated indexes.

It's also nice for just tidying up your GraphQL schema - you don't really want to be able to do a condition on a JSON column do you? 😁

Enhanced PostGraphiQL (header editing, prettier GraphQL, links, logo!)

Run PostGraphile with --enhance-graphiql (or enhanceGraphiql: true) and you'll get a few enhancements to GraphiQL:

• The "Prettify" button now uses prettier under the hood, leading to much nicer GraphQL formatting
• New "Headers" button allows you to modify the headers (e.g. to set a JWT!)
• Links to PostGraphile docs and examples
• Most importantly: we have a logo now, and the favicon has been updated 😂

New Plugins

Easily wrap a resolver:

module.exports = makeWrapResolversPlugin({
  User: {
    async email(resolve, source, args, context, resolveInfo) {
      const result = await resolve();
      return result.toLowerCase();
    }
  }
});

Easily change the nullability (true = nullable, false = non-nullable) of fields in your GraphQL:

module.exports = makeChangeNullabilityPlugin({
  User: {
    email: true,
  },
})

Process your entire GraphQL schema via a plugin; great for adding third-party enhancements such as graphql-shield.

module.exports = makeProcessSchemaPlugin(schema => {
  return addThirdPartyEnhancementsToSchema(schema);
});

GraphQL v14 support

We've split PostGraphiQL from the rest of PostGraphile, which has allowed us to add support for GraphQL v14 whilst still using GraphQL v0.13 with GraphiQL. GraphQL v14 has a number of breaking changes; so...

🚨 ...we recommend that you keep GraphQL pinned at whatever the current version is that you're using, but still upgrade PostGraphile.

🚨 The latest GraphQL spec changes how errors are handled. PostGraphile has embraced this, and error from --extended-errors are now located in error.extensions.exception. In order to maintain backwards compatibility (as this is only a minor release) we still expose these properties in the old location too, but version 5 will only expose the new interface (error.extensions.*) so it's advised that you move your client code over to the new format ASAP. (Even if we remove the old format, you'll still be able to add it back via a handleErrors callback, but you should probably follow the GraphQL spec too!)

Mounting PostGraphile middleware under a subpath

This isn't officially supported; however it should work a lot better now. If you're mounting under a subpath in express then app.use("/path/to", postgraphile()) should work automatically without requiring any options. If you're using an external proxy then you must supply the base URL so that PostGraphile knows where to tell the browser the assets are located. This is all so that PostGraphile can reference different parts of itself correctly, such as the watch stream to put in the header, or the GraphQL endpoint for GraphiQL to connect to.

e.g.:

// Assuming you combine both Express subpath AND an external
// proxy which mounts your express app at `/myproxypath`, you
// should provide options like this:
app.use('/path/to', postgraphile(db, schemas, {
  externalUrlBase: '/myproxypath/path/to',
  graphqlRoute: '/graphql',
  graphiql: true,
  graphiqlRoute: '/graphiql',
}));
// Then you can load GraphiQL at `/myproxypath/path/to/graphiql`
// and it will know to connect to GraphQL at
// `/myproxypath/path/to/graphql`

Edge-case fix

Amazingly @tim-field discovered an issue that has never come up in the year of testing PostGraphile went through, which has required a little bit of restructuring of PostGraphile internals - we've mostly removed the recurseDataGeneratorsForField internal API. This has meant that the generated SQL queries are now a little differently structured, particularly when it comes to connections and mutations; as such, some third-party plugins might need some minor tweaks. If you have a plugin affected by this, please reach out to me on Discord and I'll do my best to guide you through fixing it: http://discord.gg/graphile

🚨 We've mostly removed the recurseDataGeneratorsForField internal API.

Plugins, such as filter plugins, that merely adjust the where clause should be unaffected.

Plugins implemented via makeExtendSchemaPlugin following the documentation should be safe in most cases, however if you use the @recurseDataGenerators directive then you should change your plugin to follow the new documentation to avoid a warning message (namely: change the @recurseDataGenerators directive to @pgField, and return the data property from your resolver). If your makeExtendSchemaPlugin does not use @recurseDataGenerators then you should be fine.

🚨 Plugins that wrap existing resolvers and either depend on or change the resulting data will probably need testing as the structure of the data returned from these has changed slightly.

Other changes in this release

• Minor performance improvements
• Massively improved SQL debugging
• New DEBUG="postgraphile:postgres:notice" envvar for outputting notices from your PostgreSQL functions (thanks @arshadkazmi42!)
• Better error messages when fields clash
• "JWT expired" errors now output "401 authorization error" in the server log to help you figure out what went wrong
• Now possible to pass true as the second argument to makeAddInflectorsPlugin in order to replace existing inflectors
• You no longer need to list three plugins to skip the node interface, --skip-plugins graphile-build:NodePlugin should be sufficient
• Lots of typo and similar fixes from the community (thanks @V1shvesh, @Dargmuesli )
• Fix a dependency issue (thanks @leoschweizer)
• Fix an issue in error handling in the generated pg.Pool when the PostgreSQL connection drops.
• Moved /_postgraphile/stream to ${graphqlRoute}/stream (i.e. /graphql/stream); but don't hard-code this - use the X-GraphQL-Event-Stream header.
• pgSkipInstallingWatchFixtures Graphile Engine setting to allow you to skip the warning if you're using PostGraphile in the recommended way (i.e. NOT using a superuser account!)
• Overriding how nodeIds are formed is now possible thanks to a refactor PR from @alexppxela
• Plugins can now check for other plugins and version ranges (thanks to @mattbretl)
• Now support overriding NULLS FIRST / NULLS LAST when ordering engine #332 (thanks to @mattbretl)
• @deprecated smart-comment support has been extended to tables, functions and constraints engine #340 (thanks to @mattbretl)
• graphile-utils now merges its helpers into resolveInfo (immutably) to avoid adding an extra argument
• Fixed a possible TypeScript issue with graphql-parse-resolve-info
• Added a couple headers to help you avoid click-jacking attacks
• Now feature a random sponsor each time the PostGraphile CLI is executed! 🙏 Thanks sponsors!
• Added tests for using PostGraphile with Fastify server
• Improved startup time
• Fixes an issues with unique orderings not being detected and causing performance woes
• Enhances the formatting of SQL queries in debug output
• Fixes an issue where the nullability of elements in nodes list and the edges.node entry did not match for functions which return a set of scalars (e.g. RETURNS SETOF int)

Main feature in this release is added support for logging PG notices and improved support for logging PG errors - including additional metadata. Thanks to @arshadkazmi42 for working with me on this! Examples:

ERROR[ERR12]: Error Message Here! | WHERE: PL/pgSQL function a.generate_error(text) line 1 at RAISE | HINT: Help!
NOTICE[NOT23]: This is a notice. | WHERE: PL/pgSQL function a.generate_notice(text) line 1 at RAISE | HINT: Help!

To enable this, make sure you are using the debug envvars: export DEBUG="postgraphile:postgres:error,postgraphile:postgres:notice"; postgraphile ...

Also in this release is a tiny patch enabling plugin authors to reference the "parent" query builder from "child" query builders. This, for example, allows them to check a column from a parent record to decide which children to include. This is necessary for the @graphile-contrib/pg-omit-archived soft deletion plugin's INHERIT option.

This release also introduces another helper to graphile-utils: makePluginByCombiningPlugins - enabling you to bundle multiple plugins into one (particularly useful for combining makeAddInflectorsPlugin and makeExtendSchemaPlugin plugins with raw Graphile Engine plugins).

Finally it makes the terminology used more consistent - "Graphile Engine schema plugins" and "PostGraphile server plugins".

After many months of development, testing and iteration it is my great pleasure to announce that PostGraphile v4 is officially available! All PostGraphile and PostGraphQL users are recommended to update to this version at their earliest convenience. A migration guide is available for PostGraphQL (v3), most users should find the upgrade fairly painless. A full feature guide is available detailing the various enhancements incorporated into PostGraphile v4.

A lot has changed in PostGraphile v4 (though it's still broadly compatible with version 3); here are some of the features I'm most excited about:

• Incredible performance gains - up to 55× more requests per second, up to 92% RAM usage reduction, and up to 94% reduction in request latency
• Much tidier GraphQL schemas
  • PostgreSQL extension resources omitted by default
  • with --no-ignore-rbac, types and fields you cannot access (according to PostgreSQL GRANTs) are removed automatically
  • new smart comments feature enables you to manually omit tables, columns and functions you don't want in your GraphQL schema (alternatively rename or deprecate them)
• Plugins plugins plugins!
  • The entire PostGraphile schema is now generated from plugins
  • You can add, remove or replace plugins
  • We've written some helpers for common plugin desires:
    • Mix new features into your GraphQL schema easily with makeExtendSchemaPlugin
    • Change how things are named with makeAddInflectorsPlugin
  • Enhance your schema's functionality with some of the community's plugins, including new powerful filtering capabilities
• Massively improved error messages (please file issues if you think we can improve these further!)
• Cleaner support for one-to-one relationships
• GraphQL query batching

The biggest change in v4 is that the entire GraphQL schema generation has been re-built from the ground up to be both highly performant and highly customisable. This has been enabled with the help of the plugin-based Graphile GraphQL Engine. A few members of the community have already written some interesting plugins for PostGraphile, and we're keen to see what others come up with in the coming months!

We've also fixed a huge number of issues that affected V3, updated various dependencies, added support for PG10 features and PG11, added support for query batching, added support for a cluster mode to better make use of your many server cores, added simplified collections so you can bypass edges/nodes if you want to, greatly improved support for PostgreSQL functions, made watch mode even more reliable and useful, added a --no-server option for schema export scripts, added cache functionality to skip database introspection on startup, configuration file support, better support for common environmental variables, bundled TypeScript typings and much much more!

Check out the v4 feature guide for a full list.

The biggest issue people tend to face when getting started with PostGraphile are name collisions - where something in your database causes the same name for a type or a field to be generated twice in the GraphQL schema PostGraphile generates, leading to a failure to start. Errors generated previously were pretty obtuse, we now output much more information when this happens, including what the source of the two conflicting names were, and even hinting how it might be possible to fix it using smart comments:

Error: A naming conflict has occurred - two entities have tried to define the same key 'query'.

  The first entity was:

    Default field included in newWithHooks call for 'Query'. graphile-build built-in (root query type)

  The second entity was:

    Adding row by globally unique identifier field for table "public"."query". You can rename this table via:

      COMMENT ON TABLE "public"."query" IS E'@name newNameHere';

These errors can clearly be enhanced further - if this is something that interests you please get in touch!

We've also squashed a few remaining bugs, and even added a new introspection template system so we can more easily support different PostgreSQL versions (thanks @mattbretl!).

Improvements:

• Massively improved name collision errors (graphile/graphile-engine#292)
• PG10 identity column support (and preliminary PG11 support) thanks to @mattbretl (graphile/graphile-engine#294)
• Multi-column relations (foreign key (col_a, col_b) references other_table(col_1, col_2)) where the column spec ((col_a, col_b)) has a unique constraint now result in a one-to-one reference instead of a connection. (The connection still exists, but it's deprecated, so this is not a breaking change.) (graphile/graphile-engine#298)
• Added --skip-plugins option to the CLI, and documented it in the middleware thanks to @mattbretl (graphile/postgraphile#853)

Fixes:

• When paginating backwards using a before cursor combined with last option over a connection without a unique ordering constraint (such as a function, or a table with no primary key) the hasNextPage entry in pageInfo would incorrectly return false; this is now fixed. (graphile/graphile-engine#297)
• Fixes an issue that can lead to memory exhaustion
• Passing -A '' to postgraphile now allows you to disable JWT audience validation (as the documentation claims). (graphile/postgraphile#848)

🙏 Sponsor PostGraphile Development 🙏

A recent influx of Patreon support has enabled me to spend an extra day on PostGraphile this month, so this release contains more enhancements than expected! Thanks so much, Patreon supporters!

The biggest change in this release is to the TypeScript support - if you use PostGraphile in a TypeScript project then please remove any custom declarations you may have written for postgraphile, postgraphile-core, graphile-build, graphile-build-pg, graphile-utils, pg-sql2 and graphql-parse-resolve-info - all of these now come with their own built in TypeScript type definitions! 🎊

• GraphQL 0.13.x support! 🎉 (We were limited to 0.12.x before) - this should hopefully help people get started a lot easier due to fewer graphql module conflicts!

• Better TypeScript support

  • We export more types for you to use
  • postgraphile-core, graphile-utils and graphql-parse-resolve-info have been ported to TypeScript
  • graphile-build and graphile-build-pg now export .d.ts files so they should automatically work with TypeScript (ultimately we plan to move these to TypeScript too)
  • Note TypeScript support is currently experimental - please get in touch if you have any TypeScript woes!

• graphile-utils enhancements

  • enum support thanks to @bradleyayers
  • newly added fields can require that other columns on the parent table are fetched via @requires(columns: [...]) directive

• support for a couple more PG types:

  • hstore support
  • inet support thanks to @syndesis

• More information in some places for plugins to use

  • jwtClaims is now available on the GraphQL context, so your plugins can reference them (thanks to @hyperparsa)
  • nested QueryBuilder instances now have a reference to parentQueryBuilder

• Better errors in a number of places

• Improved CLI documentation / messages

• Smart comments:

  • now lets you replace the GraphQL description on foreign key constraints: comment on constraint person_secret_person_id_fkey on c.person_secret is E'@forwardDescription The `Person` this `PersonSecret` belongs to.\n@backwardDescription This `Person`''s `PersonSecret`.';
  • lets you set a unique key for views, which enables more efficient cursor pagination

• Many fixes, including:

  • enable update/delete mutations for tables lacking primary keys but which have unique constraints (note that a unique index is not sufficient, it must be a unique constraint)
  • fix bug in introspection query that could in some very rare circumstances cause tables or functions to be omitted from the generated schema
  • fixing a template string that accidentally had straight quotes (thanks @mathroc)
  • more useful error message when using legacy graphql versions with graphile-utils
  • fix bug in regex for validating long aliases
  • --watch mode now watches more things
  • --body-size-limit option now applies to all body types (previously they defaulted to 100kB across the board, and only JSON was overridden with this option)

• We now accept the X-Apollo-Tracing header which means you should be able to use hosted GraphQL Playground with a PostGraphile schema (this was causing CORS issues before)