Improvements to SQL function handling

Beta.7 was pulled because it introduced some regressions around certain rarer functions (e.g. computed column functions which return arrays of scalars, custom query functions which return sets of complex scalars such as interval).

This beta.8 fixes all the above, adds a load more tests to avoid regressions, and also fixes additional edge-cases relating to functions - particularly in the handling of mutation functions that return null table types.

Please refer to the beta.7 release notes for the other advances!

I'd welcome PRs which expand the tests to cover more situations to avoid regressions in future!

GraphQL Customization Through Smart Comments

UPDATE: Do not use this release, it breaks handling of certain functions, use beta.8 instead.

---

There's a lot of stuff in this release, but the main thing by far is the ability to customise your generated GraphQL schema by adding comments to tables, columns, functions, relations, etc within your PostgreSQL database. These changes can be as simple as renaming something (via @name newNameHere) or can allow you to omit things from your GraphQL schema with quite a lot of granularity. For example, @omit update on a table would prevent the table from having an update-related functionality whilst maintaining queries, create and delete. @omit update on a column would prevent the column appearing in the Patch type, so it cannot be updated (but can still be created) via GraphQL.

This functionality has been documented by Jem here:

https://www.graphile.org/postgraphile/smart-comments/

As part of this I've completely overhauled how the inflector works; if you use the old inflector you should remove it ASAP - it will not be supported going forward. The new methodology allows the inflector to be customised easily with plugins, and moves it to graphile-build from graphile-build-pg so it can be used in all APIs - we no longer pass it in as an argument.

We also gain support for batched queries with this release - this functionality is experimental so you can try it out with --enable-query-batching. Unlike the rest of the system, this functionality has no tests - so do treat it as experimental, it may change in a future release.

There's loads of fixes and other minor fixes in this release too, and I've some exciting stuff on the horizon.

Huge thanks as ever to the 12 supporters on my Patreon who help make this work possible. And thanks also to the people who've been reporting issues, the bug reports have been particularly good recently - I appreciate it! 👍

Major features:

• @omit and @name (and ilk) smart comments enable you to remove and rename fields/types in your GraphQL schema
• The inflector is now pluggable (old interface is deprecated, stop using it ASAP!) and uses a slightly different API than before so it can pull information from comments/etc
• Experimental support for batched queries via --enable-query-batching

Major fixes:

• Solve issues where @skip / @include directives still resulted in the database being queried
• Solve issues with using variables in JSON subfields
• Solve issues where rows were returned as null if you only requested nodeId/id (node identifier) but not the primary key
• Solve issues handling procedures that return an array of custom types
• Remove babel-runtime and a number of other unnecessary dependencies

Other changes:

• Throttle watch re-introspection
• Introspection now pulls down constraint comments too (useful for smart comments)
• (For plugin authors) export parseIdentifier and resolveNode (experimental) functions
• (For plugin authors) add pgFieldIntrospection to GraphQLInputObjectType:fields:field scope
• (For plugin authors) enable extend to merge fields that have also been extended
• Solve stale comments from pg_upgrade issue faced by at least one user
• Added an experimental (undocumented) plugin interface, more on this soon...
• Refactoring
• Changed the dev script to make my life easier 😉

Ability to override how errors are handled with 'handleErrors'

The handleErrors middleware option now allows you to write your own formatters for any GraphQLErrors thrown during GraphQL execution; this overrides extendedErrors and showErrorStack - you get full control over the errors, including the ability to add or remove errors should you so desire (not recommended!).

The handleErrors option is a function that receives 3 parameters:

1. the list of GraphQLErrors
2. the req object
3. the res object

It must return the array of errors to be added to the JSON HTTP response.

You could use this to add extra detail to the errors, handle translations based on request headers, set the response statusCode based on any errors, track errors via your error tracking service of choice, and much more.

This feature is thanks to @pyramation 🙏

This release also adds the X-GraphQL-Event-Stream header to /graphql responses when --watch mode is enabled, allowing tools to subscribe to the event stream for changes.

Fix introspecting PostgreSQL with legacy configuration

Since PostgreSQL 9.1 standard_conforming_strings has defaulted to on; this minor release fixes introspection if you have this configuration parameter set to off (not recommended!)

PostGraphile v4 Beta 🎉

Thanks everyone for your feedback and support during the alpha phase - I'm proud to announce that PostGraphile beta is finally here!

The beta is the final testing phase before we produce the release candidates and ultimately the official version of v4. All of the anticipated breaking changes have been completed during the alpha phase, so the beta should be safe for general usage, including usage in production! Breaking changes from now on will have to be extremely well justified and should only be added in the case of show-stopping issues.

Sign up for announcements here: http://eepurl.com/cYwzUr

I've prepared a full v4 Feature Guide and a v3 → v4 Migration Guide - I encourage everyone to check them out - particularly people coming from PostGraphQL v3.

Aside: I take time off from my paid freelance work to advance the PostGraphile project - I'd love to work on it more, and if you'd like that too why not join my awesome Patreon supporters in contributing to the sustainability of this project!

For those of you who've been using the v4 alpha, the headline changes in this release are below. Please also note that postgraphql@next will not be receiving any more updates so anyone using that should upgrade to postgraphile ASAP.

Breaking changes since the last alpha:

• Requires Node v8.6+
• Internals have been renamed to postgraphile rather than postgraphql, so you may need to scan your codebase if you've been using the non-public interfaces (exports are aliased to their old names); there's also these related changes:
  • JWTs now have an audience of 'postgraphile' rather than 'postgraphql'
  • Watch schema is now postgraphile_watch rather than postgraphql_watch
  • DEBUG envvar now responds to postgraphile rather than postgraphql

New features over the latest alpha:

• --legacy-relations CLI flag for v3 compatibility (see docs)
• --legacy-json-uuid CLI flag for v3 compatibility (see docs)
• --no-server CLI flag (see docs)
• --cluster-workers highly experimental CLI flag (see docs)
• Much faster SQL building performance thanks to a lot of micro-optimisations in pg-sql2
• Config file support (experimental, undocumented)
• More JWT verification options
• Error message improvements
• Some GraphQL field descriptions have been improved

Docs: https://www.graphile.org/postgraphile/introduction/

The belated merges release

• upgrade jsonwebtoken to work around security issue in dependency (if this breaks your app you need to submit an issue so we have better tests)
• duck-typing pg in more places
• add experimental support for .postgraphilerc.js
• if no connection string is specified, connect via standard envvar DATABASE_URL before falling back on postgresql envvars (⚠️ if you already have DATABASE_URL available in your environment and you don't use the connection string option then ensure this does what you expect! ⚠️ )
• add support for PGUSER and PGPASSWORD envvars
• doc tweaks

Thanks to everyone who has been patient about me merging their pull requests!

Anyone using postgraphql@next - please switch to using postgraphile as I will not be keeping postgraphql@next up to date soon.

Lots of fixes

This will be the LAST RELEASE OF postgraphql@next - future releases will all go out under the postgraphile moniker because managing both is absorbing too much time. If this is a problem for you, please get in touch. You should be able to switch out postgraphql@next for postgraphile without any issues.

v4 beta is not far away now, my list of remaining tasks has diminished radically:

https://trello.com/b/x4xS0bVG/postgraphile-v4-remaining-tasks

Changelog:

• Fix bigint/bigfloat precision loss
• Fix (remove) incorrect 'pagination' comments on mutation procedures
• Fix null cursors on edges on mutations
• Cursors on edges on mutations now support array of orderBy (potentially breaking change, but given it wasn't working I doubt you're relying on it...)
• Enums with asterisks in are better supported (potentially breaking change if your enums already have asterisks in)
• Better error messages when fields clash
• pg@7 support
• duck-type pg to avoid being told your config is invalid
• Warn when a schema is missing
• Autorename tables that end with input(s) or patch(s) so they don't cause conflicts (potentially breaking change if you have any tables named like this (which I deem unlikely))
• Performance: reduce redundancy in the SQL

Thanks for this release goes to all my Patreon supporters 🙏

Introspection cache

This includes the last major feature required to replace v3 - caching the introspection results to disk (see #632). This is particularly important to anyone using PostGraphile on AWS Lambda or similar environments where startup time is at a premium.

• ✨ --write-cache <path> command line option enables you to write introspection results (and anything else that the various plugins, including your own, decide to cache) to a JSON file
• ✨ --read-cache <path> command line option reads the cache back from disk allowing plugins to skip certain time-consuming tasks like introspection

You should use --write-cache during the build phase, and then --read-cache when running in production. Please note that the cache does not get invalidated, so if you edit your database schema you will need to rebuild the cache otherwise things may get... interesting.

Use of this feature is not advised unless you understand the ramifications.

---

I really appreciate the support of the 7 patrons on my Patreon ❤️ Please consider joining them: https://www.patreon.com/benjie

---

We're so close to v4 beta now I can taste it! There's just one more breaking change I want to introduce - and that's #432, an improvement to create table bar (foo_id int primary key references foo, col text)-style one-to-one relations, so that you can query fooById(id: 7) { id barByFooId { col } } rather than what is currently fooById(id: 7) { id barsByFooId { edges { nodes { col } } } } - i.e. it removes a level of indirection. I hope to add an option to allow you to disable this if you need to restore backwards compatibility, the breaking change will be the change in default behaviour.

(Sidenote: if you're using PostGraphile on AWS Lambda, please allocate at least 512MB of memory or you may risk significantly larger response times according to @jmparsons on gitter - we have not optimised PostGraphile for memory usage yet).

Fix auto-complete in GraphiQL, more error details from Postgres

The codemirror-graphql module now supports graphql@0.11.x which resolves the GraphiQL auto-complete issues that we've been experiencing; this release includes this updated dependency.

It's now possible to use --extended-errors to pass through even more keys from the pg error message, we advise you exercise caution when using this feature.

Upgraded send

v3.5.2

3.5.2