v4.7.0

• Look for jwtSecret in process.env.JWT_SECRET (#1236, @AxelUlmestig)
• Update supported pg version range to support Node 14 (#1270)
• Expose parseTags, withPgClient and getPgClientAndReleaserFromConfig from graphile-build-pg (engine#601, @enisdenjo)
• Don't query roles when ignoring RBAC (engine#598, @jnbarlow) - reduces introspection time on databases with a very large number of database roles
• Fix index signature of JSONPgSmartTags (engine#618, @LeoBakerHytch)
• Various other docs and code maintenance events

If you're using self-signed certificates for your PostgreSQL database, either keep your pg version pinned to whatever it is currently, or read: https://node-postgres.com/announcements#2020-02-25.

Please note that we do not consider widening the range of a supported module to be a breaking change. You should use a lockfile and only upgrade the dependencies you intend to. Read more in our versioning policy.

v4.6.0

The main features in this release are:

• smart-tags: ability to @omit many from foreign key constraints (graphile/graphile-engine#565; thanks @ab-pm)
• graphql: support non-scalar value ranges (graphile/graphile-engine#591; thanks @singingwolfboy)
• pg-pubsub: the @pgSubscription directive now supports a filter argument (#596; thanks @enisdenjo)

We also did an amount of housekeeping including adding a couple minor TypeScript types, improving our snapshot tests, and adding more tests on the built project.

IMPORTANT: we released a preliminary 4.6.0-alpha.0 which completed conversion of the entire project to TypeScript (finally removing Flow from its last places) but unfortunately the type churn was too high for this to be included in a non-breaking update (even though it was only the types that changed) so we decided to move the release of TypeScript conversion until v5 of PostGraphile. Effectively we're going to pretent v4.6.0-alpha.0 never happened.

v4.5.5

Additional fix to smart tags; be sure to update graphile-utils to 4.5.6 too!

v4.5.4 - Smart Tags fixes

(v4.5.1-v4.5.3 were skipped)

Fixes some Smart Tags teething problems (specifically related to fake constraints).

Features

• utils: makeExtendSchemaPlugin accepts typeDef array (#574) (82ff872) thanks @jkantr

Bug Fixes

• utils: fix smart tags for attributes (324f066)
• utils: to match early enough, we need build to be passed (9aa5565)
• deps: bump graphile-utils peerDependencies (cd6b52a)
• smart-tags: enable using Smart Tags with @foreignKey and @primaryKey (#586) (b2d8c65)
• utils: only apply condition when specified (#572) (314fce1)
• utils: make makeAddPgTableConditionPlugin work on simple collections (#569) (0a4db65)

v4.5.0 - Explain and Smart Tags

Lots of pull requests and documentation improvements from the community in this release! 🙌

First, things to be aware of before you deploy:

• previously the CLI would ignore arguments it didn't understand (dangerous!) now it exits stating the arguments it wasn't expecting
• more improvements have been made to our TypeScript types, and there's more to come, so your builds might need some minor type tweaks

New feature spotlight: explain

In enhanced GraphiQL you can now toggle 'Explain' to view the generated SQL and the query plan of that statement. This is not enabled by default - you have to opt in with --allow-explain, or in library mode you can supply an allowExplain(req) function that determines on a per-request basis if the user may use the explain functionality or not.

New feature spotlight: Smart Tags

No longer do you need to put COMMENT commands in the database ("smart comments") to customise your schema, you can now use a tags file to gather these "smart tags" into one, version controlled, easy to diff, place. Smart comments and smart tags can be used in unison, and both will be supported going forward so you can pick whichever works best for your team. In library mode you can manage smart tags however you like, and it's possible to pull smart tags from multiple sources and they will be automatically combined. Find out more about smart tags here: graphile.org/postgraphile/smart-tags/.

Community member @singingwolfboy has drafted a JSON schema definition that may help editors such as VSCode to help you when editing the default postgraphile.tags.json5 file. We've not upstreamed it yet, but hopefully will do so in the coming months.

New video

Team Graphile went to ReactiveConf in Prague last month; check out Benjie's talk Increasing Velocity with GraphQL and PostgreSQL.

🙏 HUGE THANKS TO NEW, EXISTING AND PREVIOUS SPONSORS! 🙏

We now have 84 sponsors across GitHub and Patreon and that means we're funded to spend an average of nearly 2 days per week on Open Source; this is brilliant!

Don't forget GitHub are matching sponsorship currently - so do sign up to be a sponsor if you haven't already - the more time we can put into open source, the faster we can build awesome tools for you to build epic software with!

Changes

Features

• graphiql: add 'explain' button (#1179) (1a065ab)
• jwt: support lazy public key loading for verification (#1167) (d27aaf9); thanks @ab-pm
• tags: add postgraphile.tags.json5 support (#1177) (7da3c7f), closes graphile/graphile-engine#529
• jwt: add asymmetric JWT signing and verifying support (#1089) (b4730b7); thanks @speller
• graphiql: save headers to localStorage (#1174) (37abcd3); thanks @phryneas
• connections: expose totalCount on custom connections (#529) (b6c08cf); thanks @mattbretl
• pg: add partial index detection to introspection (#535) (360e5e0); thanks @hansololai
• pg: add support for cidr and macaddr types (#520) (676c3f2) - opt in with pgUseCustomNetworkScalars; thanks @higherorderfunctor
• QueryBuilder: new methods for managing QB children (#537) (1a8a0bc); thanks @singingwolfboy
• utils: @pgQuery support for scalars (#534) (49259c2); thanks @phryneas/Mayflower
• utils: @pgQuery.source can be function (#555) (907c8e6)
• utils: add makePgSmartTagsPlugin (#541) (40a7bfa)
• utils: makeExtendSchemaPlugin supports enums and default values (#562) (2a23aee)
• types: various improvements to the TypeScript typings, including making Middleware generic
• export: only write schema if it differs (#1180) (6334897)

Bug Fixes

• cli: abort if given unused arguments (#1181) (3e7381d)
• jwt: allow JWT exp to be bigint (#542) (69c7e8e)
• omit: if you omit update on all columns don't throw (#531) (b5d9e99)
• pagination: fix bug in cursor pagination for PL/pgSQL SETOF… (#559) (0089a07)
• types: correct tuples to arrays in pgIntrospectionPlugin (#530) (6488d5c); thanks @hansololai
• types: export more types inc PgIntrospectionResultByKind (#532) (1689f66); thanks @hansololai
• types: minor TypeScript fixes (#545) (0170064); thanks @benhjames
• types: use jwt.Secret type in PostGraphileCoreOptions (#546) (be18000); thanks @ab-pm
• watch: don't built schema twice in watch mode (#558) (0a36f7b)
• graphiql: fix operation detection on multi-op documents (#1191) (49b2176)
• utils: make makeAddPgTableConditionPlugin work on simple collections (#569) (0a4db65)

We're no-longer listing chore-level items, but there have been a lot of them. Special thanks to @singingwolfboy for helping me to keep the codebase tidy.

4.4.4 - maintenance release

General maintenance release.

Features:

• Add experimental plugin generators for adding conditions, orders (graphile/graphile-engine#517)
• readCache can now pass an object to be used as the cache (@garcianavalon, graphile/graphile-engine#479)

Fixes:

• Fixed a 3 year old bug in the introspection query (means correct CRUD mutations are generated for views with triggers) (@rudism, graphile/graphile-engine#508)
• Improved the error message when orderBy is not unique and before/after are attempted (@soutot, graphile/graphile-engine#515)
• Improved error messages for smart comments (graphile/graphile-engine#525)
• Remove sortable/filterable from functions that require args (@mattbretl, graphile/graphile-engine#519)
• Ensure X-GraphQL-Event-Stream is domain relative (@mathroc, #1148)
• Recommend using --init with Docker; turn off progress bars

Chores:

• Updated to latest GraphQL, so @types/graphql is no longer required (@none23, graphile/graphile-engine#511)
• Updated to latest Flow (@none23, graphile/graphile-engine#514)
• Standardise database setup instructions (@ab-pm, graphile/graphile-engine#512, #1145)
• Move from TSLint to ESLint (graphile/graphile-engine#526)

4.4.3 - directives hotfix

makeExtendSchemaPlugin in the last release disabled the built-in directives @include and @skip; this hotfix restores them.

v4.4.2 - various fixes

Benjie has been approved for GitHub Sponsors and for a limited time GitHub are match-funding, so there has never been a better time to support development of this software!

Talking of sponsorship, please check out our new featured sponsor, Timescale!

This is mostly a maintenance release, no major new features.

Features:

• updated to the latest version of GraphiQL explorer (see their release post)
• you can now pass jwtSignOptions to PostGraphile, thanks to @speller
• makeExtendSchemaPlugin now supports defining unions, directives and scalars (required to support Apollo Federation, which you can try out with @graphile/federation); unions only work in certain places and are currently undocumented (and thus unsupported)
• new hideIndexWarnings option for when you have ignoreIndexes: false thanks to @tinymarsracing
• various code has been tidied/fixed/modernised thanks to @singingwolfboy
• auto-coerce numeric field names to begin with an underscore (shouldn't affect existing users)

Fixes:

• node identifiers have been made safer:
  • If you have identically named tables in different schemas and you use relay global object identifiers (on by default) you'll be warned, and encouraged to disable the PgNodeAliasPostGraphile plugin to solve it
  • If you use bigint or bigserial in your primary key, values greater than 9 quadrillion (technically > 9,007,199,254,740,991) are now treated as strings in the node identifier, so nodeId is now valid for these
  • 🚨 BREAKING: if you use money, or decimal/numeric or some other weird numeric type in your primary keys these will now also be represented as a string within the base64-encoded node IDs, so your node IDs will change. If this affects you (unlikely?) please get in touch with Benjie (to be clear: int, int2, int4, float, float4 and float8 are unaffected; and int8/bigint only changes node IDs for values over 9 quadrillion)
• fix issue with default values for orderBy argument on edge fields on mutation payloads when printing the schema
• mark fake constraints (e.g. @foreignKey smart comment) as indexed so it works nicer with ignoreIndexes: false
• @graphile/pg-pubsub now uses exponential back-off when server shuts down, rather than giving up after 9 attempts
• more validation is applied to cursors in connections
• fix misleading description of queryCacheMaxSize
• fix docs for jwtRole, thanks to @bidoubiwa

v4.4.1 - Performance improvements, versioned docker tags

The main feature of this release is significant performance improvements — enjoy!

We also overhauled how Docker builds work, so they're now tagged in a more sensible manner. Almost all previous tags have been deleted. From now onwards we have versioned Docker images:

• graphile/postgraphile:4 will give you the latest stable in the "v4.x.x" line (no alphas, betas, rcs); this is the recommended version to use
• Every new vX.Y.Z git tag (i.e. no alpha/beta/rc) will automatically release graphile/postgraphile:X-Y and graphile/postgraphile:X-Y-Z
• graphile/postgraphile:latest will give you the latest stable (but beware of major version bumps!)
• graphile/postgraphile:next will give you the equivalent of what's on master right now (i.e. pre-release/bleeding edge/nightly)

We're currently in a teething period for this, so there may be some bumpiness - if you face any issues, please let me know via GitHub issues or discord.

NOTE: this only applies to future releases; we are not back-filling previous releases, so there's not many tags to choose from right now.

Other changes:

• update various dependencies
• significant performance improvements
• fix a bug with standalone LDS server announcements for insert/update (thanks @pepijnverburg)
• export more TypeScript interfaces from graphile-utils
• add missing dependencies (thanks @michaelbeaumont)
• respect externalUrlBase for websockets (thanks @DvdGiessen)
• typo fixes (thanks @angelosarto, @ludwigbacklund)
• add support for PGHOSTADDR envvar if PGHOST is not present (thanks @encima)
• 🚨 Remove invalid fields from payloads for SETOF function mutations (these fields were never valid, so any client using them would already be broken, thus I am not classing this as a breaking change).

v4.4.0 - Subscriptions and Live Queries now OSS 🎉

Please sponsor development (anything from $1/mo) or take out a support contract to help fund ongoing development on the project. PostGraphile is liberally licensed and relies on crowd-funding to advance.

Thanks to the continuing sponsorship from PostGraphile's community, we've added to PostGraphile core what you've all been waiting for - GraphQL Subscriptions, and Live Queries!

GraphQL Subscriptions

We've enhanced PostGraphile with subscriptions / websockets functionality, including adding subscriptions support to our built in GraphiQL IDE (no more need to test with external GraphQL clients!). To get this you have to opt-in via the --subscriptions flag (library: subscriptions: true).

You can use our simple subscriptions listen endpoint, or easily write your own subscription endpoints using makeExtendSchemaPlugin - it's all documented on our website. PostGraphile subscriptions can use Postgres' LISTEN/NOTIFY, or any other source of realtime data — you decide what makes sense for your application.

Subscriptions are the recommended way for adding realtime features to PostGraphile.

PostGraphile Live Queries

More experimental and much heavier on the database is our live queries support — suitable for use in internal tooling within your company, but perhaps not for the internet at large. You can opt-in via the --live flag.

We've built into the core of PostGraphile the ability to track when collections/records are referenced (and the filters that apply to them, such as foreign key constraints and conditions); you can then combine this with one or more realtime provider plugins which inform PostGraphile when these tracked resources change, triggering the query to be re-executed and the result sent to the user.

This feature is exposed over standard GraphQL subscription operations so you should be able to just switch out query with subscription at the beginning of your GraphQL document to make it live. No need for specific client support — it supports all clients that support subscriptions. (We plan to support the @live directive optimisation available in Apollo Client in a future release, should demand be sufficient.)

We recommend using simple request documents with live queries because each time a relevant row is changed the entire document is recalculated and sent to the user: more complex queries will consume more resources when recalculated and will likely be triggered more frequently, leading to non-linear performance costs. (Note: we throttle updates to prevent overwhelming the client or the server, and this throttle period is configurable.)

Our first live queries provider plugin, @graphile/subscriptions-lds uses PostgreSQL's extremely efficient logical decoding functionality to stream changes out of the database using the replication interface. It requires you to tweak a couple of settings in postgresql.conf but is otherwise simple to set up - see the documentation on the website which also includes instructions for Amazon RDS.

Note that live queries are still experimental, and have not been performance optimised yet - please let us know of any issues you face!

Other features

Docker compose/kubernetes users may appreciate the new --retry-on-init-fail flag that means PostGraphile will keep trying to rebuild the initial schema, so with this flag it can be started before the database is ready. (Uses exponential backoff with a 30s cap.)

We've increased performance for queries that use large offset values (so long as the relevant table is not using column-level select grants, which are not recommended with PostGraphile).

makeExtendSchemaPlugin now has support for re-using existing Relay Connections; it can also be used with the @pgQuery directive to add connections deeper into the schema. The documentation has been updated with more details.

You can now add your own aggregates to connections using our new aggregates infrastructure. totalCount on connections has been re-written to use this, and there are more examples (e.g. exposing SUM(...)) in the PR description: graphile/graphile-engine#415; if you require certain aggregates please get in touch.

Thanks to @dijam we now accept Buffer objects as jwtSecret in addition to strings.

build.scopeByType was added to enable plugin authors to get from a GraphQL type the scope it was created with - useful for finding the PostgreSQL table associated with a GraphQL object type, for example.

Plugins now have a dependency ordering system, so we can move to using --append-plugins for everything and have hooks register their own positions. This system is not yet documented (or final) so is not officially supported yet, but it's a good way to easily enable features that previously involved a complex setup.

Many more tests were added.

--owner-connection / ownerConnectionString setting added, to give PostGraphile access to a privileged Postgres account. It is needed for logical decoding, but it's now also used (if present) to install watch fixtures and avoid the "Failed to setup watch fixtures in Postgres database" error. It is recommended in development for the watch schema, but only recommended in production if you are using live queries.

Newly introduced @simpleCollections smart comment enables you to override the simpleCollections setting on a per-table, per-relation and per-function basis. I.e. you can now opt-in to using the list interface (rather than Relay connection interface) in certain places without affecting the rest of your schema.

Filterable, filter-by-able, sortable and sort-by-able functions support was introduced in 4.3.1.

GraphiQL Explorer support added in 4.3.2;

🚨 Breaking fixes

These are fixes that might break you schema if you were relying on the broken behaviour (please don't do that!). We've added flags to some of them so you can maintain the old (broken) behaviour should you need to.

• Fixed issues with arrays of certain types (interval, etc) incorrectly having a String input type (opt out with disableIssue390Fix - ref graphile/graphile-engine#405)
• If you're using --simple-collections only we still used to add Relay edges to mutation payloads (these edges are pointless without the connections they applied to). We've corrected this oversight by removing them, but you can add them back with the disableIssue397Fix flag - ref graphile/graphile-engine#408)
• graphile-utils: if you were using makeExtendSchemaPlugin to add a field returning a Connection type, this will not have been working correctly. Instead of returning return {data: await selectGraphQLResultFromTable(...)} from your custom resolver you should now just return the result of selectGraphQLResultFromTable directly: return await selectGraphQLResultFromTable(...), and then pageInfo and the rest will work correctly. The makeExtendSchemaPlugin docs have been updated, worth a re-read. If you're affected by this and don't make this change, you'll see errors like TypeError: data.data.map is not a function.

Fixes

• PostGraphile handles PostgreSQL server restart much more gracefully
• Improved error messages when no values were deleted/updated because of RLS
• Fully qualify reference to hstore to handle issues in search_path
• Lots of improvements to TypeScript typings
• Domains with defaults now exposed as nullable (thanks @mattbretl)
• Fixed an issue with relations on custom mutation payloads when the custom mutation returned null without an error
• Fixed an issue with an entire record being returned as null when you only request nullable columns. The fix requires you to provide --subscriptions or --live flags as it requires you to have granted select to at least the primary keys of the tables you expose
• makeWrapResolversPlugin can now replace the arguments that are pass to PostgreSQL function calls for root-level custom queries and mutations.
• totalCount is now non-nullable because I couldn't find any justification for it being nullable and no issues came up during the beta and RC phase
• Fixed a bug in the times generated by the PostGraphile logs
• Exposed the X-GraphQL-Event-Stream header (thanks @imolorhe)
• Stricter pool validation
• Fixed an issue with HTTP2 support in Fastify
• Fixed hasVersion to allow pre-releases
• Include namespaceName in introspection for extensions