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)
@pgSubscriptiondirective now supports initial events (engine #612, @enisdenjo) (e862aad)
Fixes
- Fixed an issue where
--watchwould stop working if an error occurred and--retry-on-init-failwas 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
queryCacheMaxSizedue 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
jwtSignOptionswent undocumented and omitted from the TypeScript types (#1324)