v4.12.3

Fixed a bug in parsing the PostgreSQL port number from the CLI.

v4.12.2

Fixes a TypeScript bug in v4.12.1 relating to shutdownActions; no JS changed.

v4.12.1 - awesome aggregates

We've finally taken our proof of concept aggregation plugin and fleshed it out with some very significant features: calculating aggregates across connections, grouped aggregates, applying conditions to grouped aggregates, ordering by relational aggregates, filtering by the results of aggregates on related connections, etc.

For more details check out the plugin: https://github.com/graphile/pg-aggregates

This release also includes a few small fixes and some other minor features that enable greater community expansion of PostGraphile. We love seeing your plugins - do share them in our #i-made-this channel on Discord and/or add them to the list on the website!

Features

• middleware: add a release() function (experimental) (#1396) (818dad6)
• utils: support for NULLS FIRST/LAST in orderByAscDesc (#737) (99b1a8e)
• pg: connections can use named queries (#715) (352dab3)
• pg: makeProcField can be used to construct aggregates (#714) (8e0102b)
• pg: procFieldDetails helper (#717) (59a07a2)
• export pgSmartTagRulesFromJSON (#722) (48e07cd)
• hooks: add postgraphile:liveSubscribe:executionResult hook (#1483) (73fe801)

Bug Fixes

• explain: fix 'unhandled' promise rejection (#1442) (716efb0)
• order: fix order by computed column SQL item bug (#741) (0635ecb)
• uniqueKey/pgViewUniqueKey applies to views (#739) (b715f6d)

v4.11.0 - wonderful websockets

Thanks to help from the author @enisdenjo, this release adds support for the new graphql-ws websocket transport module to replace Apollo's unmaintained subscriptions-transport-ws. It's advised that anyone using websockets with GraphQL move to this new module and protocol. You can also now perform queries and mutations over the websocket transport if you opt into this; when doing so you should be very very careful of security implications (particularly CORS/cross-site request forgery issues, since websockets behave differently in this way).

We've also extended support for "enum tables" to views and given graphile-utils' makeExtendSchemaPlugin support for defining and extending interfaces.

There was a bug in watch mode (which is not intended for production usage) which could result in pool exhaustion if your PostgreSQL connection keeps being unexpectedly terminated (e.g. PostgreSQL restarting or pg_terminate_backend being called); this is now resolved.

One major change in this release is that we now validate the GraphQL schema that's built. Apparently we've not done that over the last 3 years (!!). Fortunately the schema that PostGraphile defines is already valid, but this at least means that bugs in third-party plugins will be caught before the server goes live.

We also have a minor performance enhancement to pg-sql2 that allows re-use of sql.value nodes for improved PostgreSQL query planning and marginally more efficient queries.

The special GRAPHILE_TURBO environmental variable, if you use it, is only valid on the latest LTS release of Node. This is now Node 14; so this release notes you can no longer use GRAPHILE_TURBO with Node 12 (rather than just giving you a weird crash when you try to do so).

We've also updated GraphiQL, which now contains my enhancements to the "Merge" functionality - we can now merge things more deeply by using schema type information.

❤️ THANK YOU SPONSORS 🙏

Bug Fixes

• graphql: ensure buildSchema fails on invalid GraphQL schema (engine#695) (c837e09)
• pg-sql2: use same placeholder for same sql.value node (engine#705) (969d923)
• turbo: warn users that Node v14 is required (#1411) (36481db)
• docker: remove GRAPHILE_TURBO (#1407) (af39c3d)
• ws: fix missing websockets config on CLI (#1417) (4e58a0e)
• watch: fix pool leak on unexpected connection termination (engine#711) (b2fbc21)

Features

• enum: enum views (engine#704) (d2770a5)
• utils: makeExtendSchemaPlugin interfaces support (engine#696) (8af9ed5)
• subscriptions: support graphql-ws and all operations over websockets (#1338) (c04d670) - thanks @enisdenjo

v4.10.0 - Framework Friends

Pretty big release, so let's get straight to it:

Improved Framework Support

The major feature in this release is much more solid support for various Node.js webserver frameworks: Node itself, Connect, Express, Koa, Fastify (v2 and v3 🆕), and Restify 🆕. This also fixes some long-standing compatibility issues with certain Koa plugins 😉

To accomplish this we've split the middleware into separate route handlers for each of our routes, and you can either use the middleware to delegate to these (where the framework allows), or you can add the route handlers directly. You can find documentation in our library usage page and can see examples in our new server examples folder: https://github.com/graphile/postgraphile/tree/v4/examples/servers

Along with this we get some new server hooks that you can use in place of (or in addition to) postgraphile:http:handler that are only called on the relevant routes: postgraphile:http:eventStreamRouteHandler, postgraphile:http:faviconRouteHandler, postgraphile:http:graphiqlRouteHandler and postgraphile:http:graphqlRouteHandler.

Upgraded PostGraphiQL

We've upgraded GraphiQL and GraphiQL Explorer.

With the GraphiQL upgrade we now get a dedicated headers editor panel next to the variables editor, so no more hacky sidebar 🎉 It also adds new "Merge Query" and "Copy Query" buttons to the enhanced GraphiQL which may ease you development or debugging flows.

GraphiQL Explorer is now smoother and better looking.

@eddiewang also added the ability to configure credentials for GraphiQL.

Thank you

PostGraphile wouldn't be where it is today without the support of the community; as always I want to say a huge THANK YOU to all our sponsors and contributors that make this possible.

GraphQL v15

I've had many (many) requests for GraphQL v15 compatibility; this has finally been added. You should review the GraphQL v15 changes for yourself, and if you deem them to be breaking for your workflows then you should pin GraphQL v14 in your projects which PostGraphile continues to support.

Domain constrained composite types

@jcgsville has added a tweak so that domain constrained composite types (CREATE DOMAIN my_domain AS my_composite_type ..., where my_composite_type is a type with multiple attributes) are now supported.

MaxListenersExceededWarning fix

If you've ever been greeted with:

MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 graphql:... listeners added to [EventEmitter]. Use emitter.setMaxListeners() to increase limit

because you use @graphile/pg-pubsub, you can now opt-out of this by passing a sufficiently large subscriptionEventEmitterMaxListeners option to PostGraphile. Thanks @xvaara!

Features

• HTTP server overhaul, improved framework support (#1361) (317aa40)
• allow access to Fastify request from Node request (#1385) (a3cd8b8)
• hooks for route handlers (#1389) (aeb41de)
• upgrade GraphiQL/GraphiQL Explorer (#1377) (0152244)
• graphiql: add configurable credentials behavior (#1388) (61da7e3) (thanks @eddiewang)
• deps: support for GraphQL v15 (graphile/graphile-engine#689) (3e7f98f) and (#1393) (eb1d1a6)
• pg: support domain constrained composite types (graphile/graphile-engine#615) (215f5cf) (thanks @jcgsville)
• pubsub: add maxListeners to subscription eventEmitter (graphile/graphile-engine#688) (576177f) (thanks @xvaara)
• cli: add Node version info and clarify enhance-graphiql (#1401) (aa7f4f9)

PostgreSQL schema review

If you'd like to give your schema a checkup right now, take pgRITA for a spin! We also offer one-on-one consultancy over Zoom screen sharing; if that's of interest you can book a call at https://benjie.dev or email jem @ our website domain (there's no www 😉) to enquire as to other options. Thanks for your support!

v4.10.0-alpha.0

(See v4.10.0 release notes)

v4.9.2

Fixes an issue where @unique (introduced in 4.9.1) is applied more than once to the same table (previously it would incorrectly set the fields non-nullable); also fixes an issue with enum tables where columns referencing enum tables were not usable in custom mutations.

Features

• perf: overhaul postgres interval code (graphile/graphile-engine#679) (graphile/graphile-engine#683) (upstreamed in bendrucker/postgres-interval#34)

Fixes

• tags: fix non-null for multiple @unique tags (graphile/graphile-engine#681) (0747562)
• types: fix enum tables when used in custom mutations (graphile/graphile-engine#680) (graphile/graphile-engine#682) (ed75ce2)

Thank you, sponsors ❤️

v4.9.1

Features

• smart-tags: add support for '@unique' fake constraints (#673) (5cd51b6)

Bug Fixes

• types: fix parsing interval to support fractional seconds (#678) (79017c5) (hat tip @keithlayne)
• types: domains over array types now correctly apply "tweaks" (#672) (99259f4)
• types: add more numeric casting exceptions (#661) (ea8480e) (thanks @wesselvdv)
• proc: fix output of record/table returning functions (#667) (7182d92)
• utils: selectGraphQLResultFromTable now debugs SQL (#668) (04a996a)
• utils: load makeAddPgTableConditionPlugins before PgConnectionArgOrderBy (#658) (16d7b30)

---

We seriously appreciate your support through these troubling times; thank you, sponsors, for helping us to keep producing OSS! ❤️

Graphile's pgRITA has found a number of important issues in customer's databases; you should check it out! A $25/mo pgRITA subscription helps to keep issues out of your database, and also help to fund Graphile's OSS endeavours 💪

v4.9.0

Help Us Keep Making Open Source!

Join the ranks of our awesome sponsors so we can spend more time developing and advancing the software your business/charity/side-project depends on. 💖

Private Advisor: have Benjie join your company's Slack and GitHub organizations and answer your questions privately with this new sponsorship tier.

pgRITA is a new service from Graphile: it scans your databases and lets you know of any issues it finds. Set it up on your CI today, free, and never risk forgetting to enable row-level security on a table!

Bug Fixes

• 🚨 BREAKING FIX: root level custom query connection fields now nullable (#653) (131c6ac)
• types: update next function for Express compatability (#1343) (0420c95) (thanks @purge)

🚨 The above "breaking fix" will affect you if you have any custom queries that return SETOF and result in a connection. These should always have been nullable according to our documentation and GraphQL best practices, however they were incorrectly marked as non-nullable. This has been fixed, but it means you may now receive field-level nulls where previously the entire operation would have been invalidated if an error occurs, so you may need to adjust your code to match. If you're using graphql-code-generator, like in Graphile Starter, then tracking these down should be just a case of working through the TypeScript errors, replacing data?.myFunction.nodes with data?.myFunction?.nodes (and similar for edges, pageInfo, totalCount and any other fields you have on connections).

For details of how to opt-out of this breaking fix and why it's not treated as a semver-major change, please see #653.

Enhancements

• allow overriding init fail handling (#1342) (b06142a)
• intervals now return zeros instead of nulls (#656) (2739f79)
• improve error when cannot read from enum table (#651) (dbafe55)
• add UUID validation so errors are raised earlier (#652) (9265262)
• upgraded a load of dependencies

If you run multiple PostGraphile instances in one Node instance, this first enhancement might be something you've been hoping for for a while. It gives you a way to handle "fatal errors" that occur whilst building the initial GraphQL schema; you can specify a callback that gets called in these cases and choose how to handle it: exit the process, retry after a custom delay, give up and unmount this instance. For more details, see #1342.

Another common request is previously interval types returned null for fields that weren't used in the interval:

{
  "days": null,
  "hours": null,
  "minutes": null,
  "months": null,
  "seconds": 12,
  "years": null,
}

In 4.9.0 we now use zeros instead (as you'd probably expect), thanks to an update to the postgres-interval module:

{
  "days": 0,
  "hours": 0,
  "minutes": 0,
  "months": 0,
  "seconds": 12,
  "years": 0,
}

Thanks Sponsors!

We love you 💖

v4.8.0

Announcements

Dear Sponsors: we love you! Thanks so much for continuing to support us during these difficult times, the progress below, across the other Graphile projects, and of course toward V5 would not be possible without your support ❤️

PostGraphile Development: work on version 5 is underway, for more details see #dev-postgraphile channel on our Discord: https://discord.gg/graphile

pgRITA: if you've ever thought "I'd love to have the Graphile maintainer checking over my database schema design," then we're extremely excited to share our news with you! We've built a service (using Graphile Starter 💪 ) that will analyze your database design against a list of rules we've compiled over the last few years of consultancy and support, explains any detected issues, and in many cases provides tailored SQL fixes to inspire your next migration. Income from this service will help fund Graphile's OSS endeavours, and what's more, it has a free plan with some essential rules that pair beautifully with PostGraphile. Sign up today, no credit card necessary: https://pgrita.com/

Other projects: in case you've not previously heard of Graphile Starter, Graphile Worker or Graphile Migrate you should check them out. Worker in particular pairs beautifully with PostGraphile projects, and is currently downloaded over 15k times per week!

Features

Enum Tables

PostGraphile now supports "enum tables"; for years I've recommended against using PostgreSQL enums iff the enums are ever likely to change after creation, specifically because PostgreSQL enums cannot be added to within a transaction, and cannot ever have a value removed. Instead, I recommend creating a table where the enum value is the primary key, and using foreign key constraints to reference this value. I've now written this functionality up inside of PostGraphile (this is the first thing in introspection that queries actual user tables rather than just the system catalog, so you may need to revisit your database permissions if you wish to use this functionality - don't worry, it only queries the table if it sees the @enum smart comment).

An enum table must have a text (or varchar or char) primary key, and may have other columns. It must have the @enum smart comment, and this must be done via a smart comment (and not a smart tag file or plugin) due to the way in which PostGraphile v4's introspection engine works.

Example:

create table abcd (
  letter text primary key,
  description text
);
insert into abcd (letter, description) values
  ('A', 'The letter A'),
  ('B', 'The letter B'),
  ('C', 'The letter C'),
  ('D', 'The letter D');
comment on table abcd is E'@enum';

If one of the columns of an enum table is named 'description' or has the smart comment (NOT smart tag) @enumDescription then its contents will be used as the description of the enum value in GraphiQL.

The enum table will not show up in your GraphQL schema, it's automatically omitted. (Don't bypass this with a smart tags plugin, bad things will occur.) To use a value from another table, use a foreign key constraint:

create table letter_descriptions (
  id serial primary key,
  letter text not null REFERENCES abcd, -- < This
  description text
);

PostGraphile will represent this field as if it were an enum rather than text. This works for queries, mutations, conditions and ordering.

NOTE: we currently don't have an official way to mark function input/output parameters as enum-table enums, so they will remain as text.

NOTE: --watch won't monitor for new enum values being added.

NOTE: makeExtendSchemaPlugin should work with these enums, but has not yet been tested.

Docs: http://graphile.org/postgraphile/enums/

Geometric types

We already had support for the point type in PostgreSQL; but this release extends to all of Postgres' built-in Geometric Types: Line, LineSegment, Box, Path, Polygon and Circle.

Since these types were already supported via the String type, we could not simply replace them, so you need to opt in to this feature; currently this is done with a graphileBuildOptions flag:

app.use(postgraphile(DATABASE_URL, SCHEMAS, {
  // ...
  graphileBuildOptions: {
    pgGeometricTypes: true,
  },
}));

For CLI users, you can use a .postgraphilerc.js with the following contents:

module.exports = {
  options: {
    graphileBuildOptions: {
      pgGeometricTypes: true,
    },
  },
};

pgSubscriptions initial events

The @pgSubscription directive now accepts an initialEvent argument allowing you to guarantee data freshness by emitting an event which triggers the related resolver as soon as the user subscribes.

import { makeExtendSchemaPlugin, gql, embed } from 'graphile-utils';

function buildInitialEvent(args) {
  // the `topic` value will be injected in the returning event
  return { subject: args.id };
}

export const FileSubscriptionPlugin = makeExtendSchemaPlugin(({ pgSql: sql }) => ({
  typeDefs: gql`
    type FileChangedPayload {
      event: String!
      file: File!
    }

    extend type Subscription {
      fileChanged(id: UUID!): FileChangedPayload!
        @pgSubscription(
          topic: ${embed((args) => `fileChanged:${args.id}`)}
          initialEvent: ${embed(buildInitialEvent)} # < THIS
        )
    }
  `,
  // ...
}));

All new features

• Add support for "enum tables" (engine #635) (e6bde66)
• Add support for geometric types (engine #637) (419ec87)
• Warn early if placeholders will be exhausted (engine #632) (5c22e41)
• @pgSubscription directive now supports initial events (engine #612, @enisdenjo) (e862aad)

Fixes

• Fixed an issue where --watch would stop working if an error occurred and --retry-on-init-fail was specified (engine #624) (4ef1b7b)
• Fixed an issue where a single (i.e. unique) "backwards" relationship was not watched via live queries (engine #625) (7f0225e)
• Fixed a regression with queryCacheMaxSize due to our new LRU implementation (#1312, @zacherkkila)
• Type fixes for addPgTableOrderByPlugin (engine #629, @hansololai) (91dbf6f)
• Fixed an error message typo (001de88)
• Added tslib to all the TypeScript packages
• Fix issue where jwtSignOptions went undocumented and omitted from the TypeScript types (#1324)