Skip to content

PostGraphQL 2.0.0
Compare
Choose a tag to compare
@calebmer calebmer released this 17 Oct 12:44
· 9955 commits to main since this release
v2.0.0
c3d8aab

With this release, we are very excited to announce the release of PostGraphQL 2 🎉

Get it now and start playing around by running (make sure you have a database running on postgres://localhost:5432):

npm install -g postgraphql
postgraphql

PostGraphQL 2 fixes a number of long standing bugs, makes some breaking changes to reflect emerging GraphQL best practices, and sets a foundation which can be used to do truly amazing things in the future (most popularly MySQL support). To understand more of the vision behind PostGraphQL 2, read “#87 My vision for the future of PostGraphQL.”

A number of breaking changes were made in PostGraphQL 2. We hate making breaking changes, especially given that GraphQL itself is designed to be change-tolerant, but we felt these were (in most cases) necessary small fixes that would be best for PostGraphQL’s feature. While this PostGraphQL 2 release does add a lot of things, remember that its real purpose is to create a strong base on which to build a data interfacing platform. Therefore, it felt like breaking changes made sense. If you disagree with any breaking changes, let me know! We would be more than happy to add a flag to provide backwards compatibility where possible. We are hoping most breaking changes are small enough to not be a big deal, and perhaps even be desired changes. Most are inspired by dialog with the community.

New Stuff

  • Friendly console UI. Now when you run PostGraphQL it has colors and a much more useful request logger. See a preview image in this tweet.
  • Easy to use CLI. PostGraphQL can now be run without a single option! Just run postgraphql and we will automatically connect to your local database running at postgres://localhost:5432 and the public schema. So easy you have to try 😉
  • Authentication. For a while PostGraphQL supported authorization so users could only see their data, but not authentication which meant you would need to build a small service to issue JSON Web Tokens. In PostGraphQL 2.0.0, this is no longer required. I’ll be writing up an authentication tutorial before the final release.
  • Better Postgres types support, including compound types. PostGraphQL now uses ISO 8601 for dates and times (#107), custom handling of interval types, better support for Postgres ranges (#90), correct handling for all array types, and support for dynamic JSON with the --dynamic-json flag (#102). Compound type support means now you can create nested objects in your schemas, input or output.
  • No rowId fields by default. By default, PostGraphQL no longer renames id columns to rowId. This was a controversial decision made in PostGraphQL 1 to support Relay 1, as Relay 1 requires the id field to be a special global id. However, it would appear that the GraphQL team is moving towards a standard global field name in __id. This new field name makes a lot of sense for PostGraphQL so now all global ids are named __id by default. However, this does not mean PostGraphQL no longer supports Relay 1! You could use the Relay 1 fork that supports __id, or you could pass the option --classic-ids to PostGraphQL which will use the original behavior. If you prefer the classic behavior, all power to you!
  • Related tables included in mutations. If you are using Relay 1, it may be helpful to have access to related rows from mutations at the payload level (#110, #114, #115). In PostGraphQL 2, such rows are included in the mutation payload for create, update, delete, and procedure mutations.
  • Mutations using any unique identifier. With PostGraphQL 2 you can execute update and delete mutations using the global Node identifier. The row’s primary key, or a unique constraint (#126).
  • Cursor pagination by offset. The “correct” way to implement cursor pagination in GraphQL does not involve using SQL limits and offsets. Rather PostGraphQL must control the columns and the ordering. This makes using custom orderings incredibly difficult. Whether you had a view that was already ordered or a connection procedure that defined an order. Now that offset cursor pagination is implemented, we can support natural ordering as well as the “correct” method. Offset ordering has a few gotchas, but they aren’t bad enough to warrant not having this feature.
  • Better field names. It has been annoying to many that the top level method of selecting rows has been named {tableName}Nodes, as in personNodes or postNodes. This was originally because I was against bringing in a pluralization package, mainly because it may have been awkward for non-English speakers. However, as PostGraphQL aims to be more and more extensible, it isn’t hard to change/add pluralization rules. So in PostGraphQL 2, names are not pluralized and read like allPeople or allPosts. This feels like much more natural and may always be configured.
  • Introspection of multiple schemas. In PostGraphQL 1, you could only introspect a single schema. In 2 you can introspect as many as you would like.

Other Breaking Changes

  • No more --development flag. Instead all of the features in --development have been broken out into their own flags. The reason this was done is because sometimes a GraphiQL interface in production makes since. GraphiQL is now also enabled by default, use --disable-graphiql to disable it.
  • GraphQL and GraphiQL live on different routes. In PostGraphQL 1 if you went to the /graphql route with a browser, you would see GraphiQL. This turns out to not be a best practice as it tightly couples GraphiQL to the GraphQL endpoint. If we wanted to add features to GraphiQL like a headers editor, or a SQL terminal it would be much more difficult if the routes were not separated. Whenever you start PostGraphQL you will be told the exact URL GraphiQL is served on so you won’t be confused.
  • “Insert” mutations renamed to “Create.” This is to better reflect the industry standard CRUD acronym which stands for: create, read, update delete. “Insert” was initially chosen to feel more like SQL.
  • No more “new” prefix in update mutation (#125). The “new” prefix in PostGraphQL 1 has gotten some understandable complaints as it has made updating rows without first renaming the fields impossible. The types for update mutations have been refactored so that now there is one patch object whose fields correspond to the object’s fields.
  • Removed the descending argument in connection fields, instead descending information is contained in the orderBy enum. So instead of configuring orderBy: NAME, descending: true, you would instead just write: orderBy: NAME_DESC or orderBy: NAME_ASC.
  • The root level viewer field has been renamed to query in PostGraphQL 2. The root level viewer field is a hack for Relay 1 to workaround some of Relay 1’s limitations when it comes to top level fields (such limitations should be gone in Relay 2). However, the viewer field could also have some semantic meaning such as the literal “viewer,“ or “current user” of the schema. By naming this root field viewer, PostGraphQL 1 disallowed users to add their own implementation for viewer. In PostGraphQL 2, the field still exists, but it has been renamed to query. It can be used in the exact same way, just now with a better name 😉
  • Connection conditions moved from top level arguments to a condition object. This change declutters your connection argument list, avoids naming collisions with connection arguments, and allows us to make exciting new enhancements to conditions in the future.

What Comes Next?

So what’s the plan after PostGraphQL 2.0.0 is released? We’ll continue with the rough timeline as proposed in #87, but here it is again with a few extra things.

  • Documentation/marketing website. We really need this…
  • Performance. Experiment with different ways of executing queries to make PostGraphQL as fast as possible.
  • Extensibility. This is a big one. Being able to extend PostGraphQL in Node.js is important to the future of the project.
  • CMS?

Please try out PostGraphQL 2 and tell us what you think! It’s as easy as:

npm install -g postgraphql
postgraphql
Assets 2