PostGraphQL 2 Beta

[calebmer]

PostGraphQL 2 Beta

With this PR, I’m very excited to announce PostGraphQL 2 is now in beta 🎉

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

npm install -g postgraphql@next
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 theory behind PostGraphQL 2, read “#87 My vision for the future of PostGraphQL.”

A number of breaking changes were made in PostGraphQL 2. I hate making breaking changes, especially given that GraphQL itself is designed to be change-tolerant, but I 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! I would be more than happy to add a flag to provide backwards compatibility where possible. I’m 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. Before the release a --demo flag will also be added which will connect you to a database running in the cloud. 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 (Would it be better if dates used ISO8601? #107), custom handling of interval types, better support for Postgres ranges (Use pg-range library #90), correct handling for all array types, and support for dynamic JSON with the --dynamic-json flag (Add JSON type #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 (Stored Procedure is not Relay compliant #110, Mutation Payloads and Relations #114, Make mutations in Relay easier by including related tables  #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 (Support mutations by global ID #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 (Rationale of using "new" prefix in mutation input #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 😉

Steps To Release

The core codebase for PostGraphQL 2.0.0 is done and ready for production use. The reason it isn’t going straight to a release is that there are a few extra things that need to be done.

Also, I wanted to add a period of time to allow for feedback. Once we hit 2.0.0, I don’t want to make any breaking changes for as long as possible, so now would be the time to make those breaking changes!

The list of things that need to get done before we can release are as follows.

• Improve forum example schema. I want to add the concept of likes to the forum example schema and a full authorization/authentication example.
• Write documentation article explaining how authentication and authorization works.
• Deploy a demo database and demo PostGraphQL instance to enable starting PostGraphQL with postgraphql --demo.
• Upgrade some existing apps using PostGraphQL 1. Including the Relay example (feat(graphql): add relay example #66).

What Comes Next?

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

• Documentation/marketing website. We really need this…
• GitHub GraphQL API equivalence. GitHub recently announced their GraphQL API. How awesome would it be if we could make a PostGraphQL implementation of that API 😉
• Extensibility. This is a big one. Being able to extend PostGraphQL in Node.js is important to the future of the project.
• Performance. Experiment with different ways of executing queries to make PostGraphQL as fast as possible.
• CMS?

---

Please try out PostGraphQL 2 and tell me what you think! It’s as easy as (if you have a Postgres database running on postgres://localhost:5432):

npm install -g postgraphql@next
postgraphql

[calebmer]

I’ve just published a documentation article detailing the entire process of creating a PostGraphQL schema. It also in detail describes authentication and authorization, some of which is new in PostGraphQL 2.

The last thing I need to do is setup a demo database to enable people running postgraphql --demo to get started then PostGraphQL 2 will be out of beta 🎉

Any last requests for breaking changes as I hope to not break anything for a while after this.

[benjie]

Excellent work, @calebmer! I was reading through the first half of the tutorial and have a few tweaks to suggest:

Postgres permissions work as a whitelist and not a blacklist, so therefore no one has more access then you explicitly give them

then -> than

The word strict just means that this function will not accept null input. That is password cannot be null or first_name cannot be null.

The way this reads is a little misleading, I think - strict means if you give it null input it'll give null output. I'm not sure how postgraphql 2 handles this, but v1 would just return null (and no error).

Make sure that when you create a function with security definer there are no ‘holes’ a user could use to see or mutate more data than they are allowed to.

Missing "not"

Other than these minor niggles, it seems great so far!

[calebmer]

Ok, looks like we’re good, seems like all that’s left is bug fixes. I feel we got most of the major regressions so I’ll merge today and do the final 2.0.0 release tomorrow 🎈

[benjie]

🎉 Congrats!