graphile/crystal v4.0.0-rc.2

RC2, aka Leaner Schema

on GitHub

A plea: if you or your company want to see more documentation, more tests, and/or faster progress (or just want to ensure the maintainer doesn't burn out 😅) then please give generously to my Patreon or get in touch to discuss sponsorship. Ask your boss! Your financial support will enable me to take time off consulting and spend it working on the project, which would make me happy and should benefit you and your business too!

Huge thanks to my new and existing Patreon supporters; you've enabled me to spend more time on PostGraphile recently. 🙏

RC1 went down very well, no major bugs were discovered 🎉 However one of the major issues in PostGraphile has always been including too much in your generated GraphQL schema. This release helps to address this in two ways:

1. PostgreSQL extensions are now omitted by default which should significantly improve people's first impressions of PostGraphile. If you've followed the examples and best practices and use a schema other than public this should likely have no impact on you, but if you haven't then this is technically a breaking change. You may opt out via --include-extension-resources, but I am not aware of anyone using the functionality that has been removed, most likely it's just an annoyance.
2. Previously we ignored RBAC (i.e. GRANT statements) and exposed all operations and all tables/columns/functions in the schemas you tell us to. Well we still do this by default (because this would be a breaking change for a lot of people) but we now have the --no-ignore-rbac CLI flag (or ignoreRBAC: false library option) which will automatically remove fields from your schema that you're not granted access to. This goes as far as to remove fields from the create/update input objects separately based on INSERT/UPDATE column permission grants and honours the EXECUTE permissions on functions. I strongly recommend you give it a try, and let me know how you get on! This will be the default in version 5 of PostGraphile.

Another significant change that has been made is the internals of the plugin system now supports type modifiers (e.g. decimal(5, 2) was previously just seen as decimal), this means that PLUGIN AUTHORS AND USERS: some internals have changed, I've put backwards-compatible methods in to auto-port things to the new interface which should work fine, but you'll need to use the new interfaces to benefit from the new functionality (e.g. support for type modifiers).

A potentially breaking change for a very small number of applications is that if PostGraphile doesn't understand a type argument for a function then it will no longer expose it as a string, instead it will skip the function entirely. If this affects your application, please get in touch with me via electronic mail (benjie | graphile · org) or gitter and we should be able to knock up a plugin that adds back support.

Please let me know how you get on with RC2 via electronic mail (benjie | graphile · org) or gitter - your feedback is vital to the release process!

Full changes in RC2 vs RC1:

• Generated GraphQL schema can be much simpler!
  • introspects extensions, automatically ignores tables and functions that were installed by extensions - if you want these for some reason then you can disable this filtering via --include-extension-resources or includeExtensionResources: true
  • recommended: new --no-ignore-rbac CLI option (or ignoreRBAC: false library option) enables RBAC (GRANT/REVOKE) permission introspection and only exposes tables/fields/queries/mutations/functions that can be accessed by the connection string database user (or one of the roles it can change into)
• Koa support massively improved
  • no longer hangs when bodyParser() middleware is used
  • now is compatible with many more common Koa middlewares
  • now supports server-sent events, so Koa users get GraphiQL schema hot-replacement too!
  • no longer requires koa-connect compatibility layer (suggest you remove this!)
  • please file issues for any problems you face with Koa support
• PostGraphile's built in GraphiQL improved
  • auto-reinspects the GraphQL endpoint when the server-sent events connection re-establishes (e.g. when the PostGraphile server restarts)
  • handles changes to the GraphQL schema more gracefully - fixes a crash, and doesn't jump you all the way to root if it doesn't have to
• Functions (custom queries, mutations and computed columns)
  • New *BaseInput type added for tables, includes all columns, made nullable (like previous 'Patch' input type) - this is because the two existing types (Input and Patch) will be used for create and update mutations respectively, which now support RBAC, and your custom functions might require more fields. You won't find this in your schema unless you use the variant smart comments detailed below
  • New @omit category: 'base' for these *BaseInput types, so you can exclude columns from them also
  • Functions can now declare, via smart comment, which type of GraphQL table input they'd like to use via @arg0variant patch or @arg0variant base (replacing 0 with the zero-based index of the argument); if unspecified they will continue to use the standard *Input type, the one used for create* mutations. v5 might default to using *BaseInput for functions.
  • Functions no longer default to string if they can't find the correct input type for their arguments - they are now skipped instead. This should not affect many users.
• JWT support improved
  • bools are supported in JWTs again
  • fix an issue with audience verification
  • reminder that non-scalars in JWTs have changed - they're now handled via JSON.stringify(...) rather than String(...) - they were never officially supported - so if you were splitting a string coming from an array you're going to have to update that code.
• For plugin developers
  • Various PG helpers are now available on Build, so plugins can use them without having to declare graphile-build-pg as a dependency. Note that these methods are undocumented and thus may change in future versions without being a breaking change.
    • pgQueryFromResolveData
    • pgAddStartEndCursor
    • pgOmit
    • pgMakeProcField
    • pgViaTemporaryTable
    • pgParseIdentifier
  • pgGetGqlTypeByTypeId deprecated in favour of pgGetGqlTypeByTypeIdAndModifier - this allows us to support more complex types such as decimal(12,3) or geography(point, 4326) - see graphile/graphile-engine#233 for more
  • pgOmit now respects RBAC, so fields/types that don't have relevant permissions granted will no longer be exposed (disable via --ignore-rbac) - please update to using pgOmit from Build rather than importing omit from graphile-build-pg
  • attributes is now available directly on class introspection results - no need for a second lookup any more
  • graphile-build-pg no longer has dependencies on graphql - instead using the graphql passed from graphile-build
    • You can do the same in your plugins
  • Introspection now contains information about RBAC and extensions
  • you should not have to require graphql, graphile-build or graphile-build-pg in any plugins - if you do then please get in touch and we can figure out a better way
• Dev
  • Graphile tests now run against PG9.6 rather than PG9.4 (because wanted to use current_setting(text, boolean) in the tests, which was added in PG9.6) - PG9.4 should continue to work but note that officially we only support PG9.6+
  • Some light refactoring

Please support my Patreon: https://www.patreon.com/benjie Any amount helps, [Jimmy Wales voice] "if everyone using PostGraphile gave $10/mo right now..."