graphile/crystal v3.0.0

Schema exports and GraphiQL live schema reloading

on GitHub

This release comes with a few new features that should make the PostGraphQL developer experience much better.

The first feature is support for auto-exporting the PostGraphQL schema by @MaienM. This has been a long-requested feature as GraphQL ecosystem tools like Relay often ask for the user to provide a schema. Now instead of setting up a script to manually pull down the latest PostGraphQL schema into your project with the GraphQL introspection query, you can pass in --export-schema-json [path] or --export-schema-graphql [path] arguments to postgraphql and PostGraphQL will automatically export your schema in a JSON or GraphQL format to the provided path! This feature even works in watch mode, so if you are changing your schema on the fly you will get the latest schema file in your directory.

Another feature that was added in this release to make watch mode even more powerful is live schema reloading in GraphiQL. Before whenever your schema updated you would need to manually reload the GraphiQL browser window you were using to run queries against your database. Well no longer! Now PostGraphQL will let GraphiQL know when there is a new schema, and GraphiQL will live-reload appropriately. Keeping your state in the documentation viewer as well.

Breaking Changes

Unfortunately, this release also contains two breaking changes that were caused by a breaking change in the GraphQL specification.

• When graphql/graphql-spec#244 was merged it meant that PostGraphQL’s usage of the __id field name was now not spec-compliant. Therefore, PostGraphQL had to change the name __id to nodeId to continue being spec-compliant. If you were not using the --classic-ids argument, this will be a breaking change for you. Users how have the --classic-ids argument will not experience a breaking change. We believe nodeId is safe from naming collisions because we already reserve the Node interface name. For a longer explanation of this change see #327.
• Because the range of Postgres big integers is larger than the range of JavaScript numbers and GraphQL Ints big integers now have their own custom type called BigInt which will return a string in the GraphQL JSON output. We knew this may be a problem for a while, but we did not want to make a breaking change unless we had a very good reason. The __id change made for a good reason. For more information see #302 and #328.