crystal

This release of PostGraphQL provides some new features like configuration options for body-parser’s limit with bodySizeLimit, the ability to add custom settings to a PostGraphQL transaction with pgSettings, and a fresh new version of GraphiQL that comes with some nice enhancements to search and GraphQL field rendering.

This release also fixes a few bugs including a major regression introduced in 3.0.1 which was reported in https://github.com/postgraphql/postgraphql/pull/409.

For a full list of features and bugfixes along with their associated pull requests, see the list below.

Features

• Add option so that you may inject custom settings into the database. (https://github.com/postgraphql/postgraphql/pull/399)
• Add option to configure the limit for body-parser. (https://github.com/postgraphql/postgraphql/issues/372)
• Update GraphQL and GraphiQL to 0.9.3 and 0.9.1 respectively. (https://github.com/postgraphql/postgraphql/pull/377 and https://github.com/postgraphql/postgraphql/pull/410)

Fixes

• Remove columns from insert unless those columns have a defined value. (https://github.com/postgraphql/postgraphql/pull/367)
• Fix new GraphiQL implementation so that it works with koa. (https://github.com/postgraphql/postgraphql/pull/370)
• Fix incorrect return type coercion for computed columns that return a composite type. (https://github.com/postgraphql/postgraphql/pull/409)
• Use array literal syntax for empty arrays. (https://github.com/postgraphql/postgraphql/pull/407)

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 https://github.com/facebook/graphql/pull/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 https://github.com/calebmer/postgraphql/pull/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 https://github.com/calebmer/postgraphql/issues/302 and https://github.com/calebmer/postgraphql/pull/328.

With this release PostGraphQL is no longer published as ES6 to the npm registry. Before we were building PostGraphQL to ES6 with TypeScript to take advantage of the latest work in browser engines, so the package published to npm had native classes and object destructuring. Now that people are looking to use PostGraphQL in new environments like AWS Lambda and Meteor which use Node.js v4 we build the project to target ES5. Some standard library features like Map and Promise may still need to be polyfilled in ES5 environments, but there will be no syntax errors.

This release also allows you to pass a PgCatalog object instead of a schema name. This was implemented by @rentrop in https://github.com/calebmer/postgraphql/pull/306 and it helps if you want to prebuild your catalog so PostGraphQL doesn’t introspect your schema at startup. This is especially useful for deploying to AWS Lambda. Hopefully we’ll be adding documentation for deploying to PostGraphQL as more community members have positive experiences deploying there.

By default PostGraphQL gives you basic create, update, and delete mutations to offer complete CRUD functionality. However, sometimes it may be useful to disable these default mutations and only use custom Postgres procedures to mutate your data.

If you only ever use custom procedures you may not run into as many naming conflicts and you can restrict mutations that can be made by the client.

Of course individual default mutations will still be disabled if no user can use them given the Postgres grant system.

Thanks to @grncdr in https://github.com/calebmer/postgraphql/pull/180 for adding the functionality!

This release adds watch functionality to PostGraphQL 🎉

When developing PostGraphQL, it’s nice to have a fast feedback cycle. Being able to open PostGraphQL in one window and a Postgres query input in the other while PostGraphQL automatically updates is a great way to develop rapidly.

To use just pass in --watch and/or watchPg: true (depending on if you are using the CLI or the middleware). PostGraphQL will add an event trigger to your database (can only be done if you start PostGraphQL as a superuser), and whenever it gets a notification from that trigger PostGraphQL will automatically rebuild the schema. See a demonstration below:

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

When building an authentication system on top of PostGraphQL, you’ll need to add an anonymous role for all requests that don’t assert their own role in a JWT. Before, the anonymous role was the same as the role you would use to authenticate with the database, now that default can be overridden with the --anonymous-role command line option! Just do the following:

postgraphql postgres://auth_user@localhost:5432/mydb --anonymous-role anonymous_role

For more information about roles in PostgreSQL and their “role” in PostGraphQL read the documentation article titled “The Anonymous Role”.

Bugfixes

PostGraphQL has also had a number of patch releases since the last minor release.

• Fix interval and the handling of other types (#89).
• Fix pagination bugs when using non-unique cursors (#95).
• Add missing dependency in some environments.

Before PostGraphQL didn’t have appropriate CORS headers making it difficult to use in the browser or without a reverse proxy. With this release CORS headers were added. To see the exact CORS used see the custom middleware here.

This release adds two new helpful features. The first being unique column constraint fields, and the second being the hiding of mutations for non-updatable views.

Unique column constraint fields adds a feature a lot of people have been wanting. Selection by the raw rowId field. In the forum example, for instance, you can now use this new fields:

{
  userByRowId(rowId: 1) {
    id
    rowId
    givenName
    familyName
  }
}

Instead of needing to use the obfuscated global ID. But this method also extends to tables with a unique compound constraint. So for example if table foo had columns bar and buz which had a unique constraint, you could query a single row of such a table like such:

{
  fooByBarAndBuz(bar: 1, buz: 2) {
    ...
  }
}

In addition, this release is able to detect which views are updatable and which are not and exclude/include insert, update, and delete mutations accordingly. This means views which may not be mutated will not be falsely represented in your schema now. This should have been the functionality all along, therefore it is considered a bug fix and not a breaking change.

Commits

• https://github.com/calebmer/postgraphql/commit/091b111e830ce52c6d29e15c5c5fa739ecde8ea0 Only show mutations for types that are updatable (#73, @pvdvreede)
• https://github.com/calebmer/postgraphql/commit/dc4a97088037ae75f791aec68e9d71ffb4bf49f7 Add fields based on unique constraints (#70, @calebmer)

This release adds better PostGraphQL support for Relay mutations. In the past, PostGraphQL didn’t always include all of the fields Relay would want in its mutations payloads, this release adds fields to the mutation payload that benefit Relay and non-Relay users alike.

The new payload types from the person table in the forum example look like so:

type InsertPersonPayload {
  person: Person
  personEdge(orderBy: PersonOrdering): PersonEdge
  clientMutationId: String
  viewer: Viewer!
}

type UpdatePersonPayload {
  person: Person
  clientMutationId: String
  viewer: Viewer!
}

type DeletePersonPayload {
  person: Person
  deletedPersonId: ID
  clientMutationId: String
  viewer: Viewer!
}

express-graphql Update

Another exciting feature of this release is the upgrade of a bunch of dependencies, most notably express-graphql! This brings a new version of GraphiQL which fixes a couple of bugs and now also hides GraphiQL from search engines.

With this update you can now also use PostGraphQL as Connect middleware and not just Express middleware.

Bugfixes

• Single item resolver correctly checks for null or empty columns—@ferdinandsalis (#65)
• Server now correctly throws error for malformed Authorization headers—@calebmer (#71)
• Server also now returns the correct status codes for bad JWT tokens—@calebmer (#71)

Thanks to @ferdinandsalis and @prevostc for the bugfixes in this release!

• Fixed a bug where tables with array columns couldn’t be used with computed columns—@ferdinandsalis (#58).
• Added missing support for user defined domain types—@prevostc (#64).

The Relay standard viewer field has been added to PostGraphQL. Now Relay users can query root PostGraphQL fields without worrying about the Relay imposed limitations for root fields defined in https://github.com/facebook/relay/issues/112. For an example of how the viewer field works see the following:

{
  thing(id: "dGhpbmc6NQ==") { ...thing }

  viewer {
    id
    thing(id: "dGhpbmc6NQ==") { ...thing }
  }

  node(id: "viewer") {
    id
    ... on Viewer {
      thing(id: "dGhpbmc6NQ==") { ...thing }
    }
  }
}

fragment thing on Thing {
  id
  note
}

The viewer field simply returns all of the fields in the root query just nested one level deeper. This is very helpful for Relay applications and other frameworks that put limitations on what can be included in a root field. The Viewer type (returned by the viewer field) also implements the Node interface with a non-opaque ID of simply “viewer” making it re-fetchable by Relay.

The viewer field is also included in all mutation payloads now which can be helpful for Relay and non-Relay users alike as now you can query your entire data domain from the scope of a mutation payload.

Non-Relay users needn’t worry as this addition does not affect you at all. It provides a great benefit to Relay users which makes it worth including in PostGraphQL.

Finally, if you were using the viewer field name in your application with a procedure to return the authorized user object, you can still use standard field names like me or game.

Bugfixes

This release also contains a few bugfixes. Notably:

• Falsey values can now be used in the update mutation instead of being discarded with a falsey check—@ferdinandsalis in https://github.com/calebmer/postgraphql/commit/ac15f8e8ab16acc7a2d56b3b513ba7d55e519bde

Because PostGraphQL is written in Node.JS, it has the great advantage of being integratable with standing Node.JS applications. This release aims to make this goal even easier by enhancing PostGraphQL’s abilities as a library.

To use PostGraphQL in this way you now just need to do the following:

import express from 'express'
import postgraphql from 'postgraphql'

const app = express()

app.use(postgraphql('postgres://localhost:5432'))

app.listen(3000)

To learn more about all of the options available when using PostGraphQL as a library, read the documentation article here.

This release is pretty exciting for me as it adds support for PostgreSQL procedures. To see more check out PR #41.

Procedures in PostgreSQL are powerful for writing business logic in your database schema, and PostGraphQL allows you to access those procedures through a GraphQL interface. Create a custom mutation, write an advanced SQL query, or even extend your tables with computed columns! Procedures allow you to write logic for your app in SQL instead of in the client all while being accessible through the GraphQL interface.

So a search query could be written like this:

create function search_posts(search text) returns setof post as $$
  select *
  from post
  where
    headline ilike ('%' || search || '%') or
    body ilike ('%' || search || '%')
$$ language sql stable;

And queried through GraphQL like this:

{
  searchPosts(search: "Hello world", first: 5) {
    pageInfo {
      hasNextPage
    }
    totalCount
    nodes {
      headline
      body
    }
  }
}

For more information, check out our procedure documentation and our advanced queries documentation.