graphile/crystal v4.0.0-beta.7

GraphQL Customization Through Smart Comments

on GitHub

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 😉