Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@dataplan/pg

graphile18.6kMIT0.0.1-beta.32TypeScript support: included

PostgreSQL step classes for Grafast

graphile, graphql, grafast, postgresql, postgres, pg, dataplan, build, extension, graphite

readme

🔮 Graphile's Crystal Monorepo

GitHub Sponsors Patreon sponsor button Discord chat room Follow

At Graphile we love GraphQL so much we named ourself for our love of it! This repository houses many of the Graphile packages that relate to GraphQL (or relate to the packages that relate to GraphQL, or relate to those package...); the two headline projects are Grafast and PostGraphile but there's many other packages, a fair few of which can be used independently - see below for more details.

Grafast: A cutting-edge planning and execution engine for GraphQL.js ─ use this as a drop-in replacement for the execute method from GraphQL.js and by moving from traditional resolvers to Grafast "plan resolvers" you'll be able to leverage the declarative nature of GraphQL requests to execute your business logic in the most efficient way, leading to reduced server load and happier customers. Use this if you're building your own GraphQL schemas and want the best performance and efficiency without having to put much extra effort in.

PostGraphile: An incredibly low-effort way to build a well structured and high-performance GraphQL API backed primarily by a PostgreSQL database. Our main focusses are performance, automatic best-practices and customisability/extensibility. Use this if you have a PostgreSQL database and you want to use it as the "source of truth" for an auto-generated GraphQL API (which you can still make significant changes to). NOTE: thanks to graphile-export you can also use this as a starting point for an API that you then manage yourself.

➡️ For PostGraphile V4 see the legacy branch

Project summaries

Here's a rough breakdown of the main packages:

  • grafast - standalone cutting-edge planning and execution engine for GraphQL; see above for full description.
  • graphile-export - a package that can (under the right circumstances) export an in-memory dynamically-constructed GraphQL schema to raw JavaScript source code that can be imported and executed
  • jest-serializer-graphql-schema - a simple Jest serializer that understands GraphQL schemas and thus does not fill snapshots with \"\"\" etc.
  • graphile-config - a module that handles the plugins, presets and configuration files for Graphile software - a universal configuration layer.
  • graphile-build - a system for building a GraphQL.js schema from "plugins", particularly useful for auto-generated GraphQL APIs (e.g. PostGraphile uses this) but also useful for hand-rolled schemas that have a lot of modular but widely-used concerns such as connections, naming, etc.
    • graphile-build-pg - plugins for graphile-build that understand @dataplan/pg (i.e. PostgreSQL) services and can generate types, relations, mutations, etc for these database resources.
  • @graphile/lru - an obsessively performant least-recently-used cache (possibly the fastest general purpose LRU cache in Node.js) with a ridiculously tiny feature set; you almost certainly want @isaacs' lru-cache instead of this.
  • pg-sql2 - a library for building highly dynamic SQL-injection-proof PostgreSQL queries using tagged template literals.
  • pg-introspection - a strongly typed introspection library for PostgreSQL, generated from the PostgreSQL documentation to provide up-to-date details of each introspection field.
  • postgraphile - pulls most of the above technologies together; see above for full description.

Crowd-funded open-source software

To help us develop this software sustainably, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship.

Click here to find out more about sponsors and sponsorship.

And please give some love to our featured sponsors 🤩:

The Guild
The Guild
*
Steelhead
Steelhead
*

* Sponsors the entire Graphile suite

Why the "crystal" monorepo?

Originally what is now Grafast (and was previously DataPlanner) was known by the codename "Graphile Crystal." This lead us to use the 🔮 emoji to represent the project in secret before we announced it publicly, as a codeword for those in the know. Now that Grafast is the name for our planning and execution engine and we needed a name for the monorepo that wasn't too GraphQL specific (since there are things in here that aren't strictly related to GraphQL) and we figured that calling it the Crystal monorepo would honour our original nickname for the project. Rumours that the name was inspired by the maintainers' crystal wedding anniversary are greatly exaggerated.

changelog

@dataplan/pg

0.0.1-beta.32

Patch Changes

0.0.1-beta.31

Patch Changes

0.0.1-beta.30

Patch Changes

0.0.1-beta.29

Patch Changes

0.0.1-beta.28

Patch Changes

0.0.1-beta.27

Patch Changes

0.0.1-beta.26

Patch Changes

0.0.1-beta.25

Patch Changes

0.0.1-beta.24

Patch Changes

  • #2132 807650035 Thanks @benjie! - Fix issue where planning errors occurring after side-effects would result in GrafastInternalError being thrown. Further, fix issue causing $step.hasSideEffects=true to throw a planning error if $step had created other steps (as dependencies) during its construction. (Notably, withPgClient suffered from this.) Thanks to @purge for reporting the issue and creating a reproduction.
  • Updated dependencies [807650035]:

0.0.1-beta.23

Patch Changes

  • #2121 8bdc553b7 Thanks @benjie! - Add support for accepting poolConfig via makePgService

  • #2128 4e102b1a1 Thanks @adamni21! - Reduce planning cost of large input object trees by evaluating keys up front (thanks to @adamni21).

  • #2121 1cabbd311 Thanks @benjie! - Superuser connection now uses superuserPoolConfig rather than poolConfig when creating a pool.

  • #2091 590b6fdf5 Thanks @benjie! - Allow PgClassExpressionStep instances to be embedded directly into SQL expressions.

  • #1985 d6102714e Thanks @hannesj! - 🚨 PostgreSQL adaptor is no longer loaded via string value; instead you must pass the adaptor instance directly. If you have adaptor: "@dataplan/pg/adaptors/pg" then replace it with adaptor: await import("@dataplan/pg/adaptors/pg"). (This shouldn't cause you issues because you should be using makePgService to construct your pgServices rather than building raw objects.)

    🚨 If you've implemented a custom PgAdaptor, talk to Benjie about how to port it. (Should be straightforward, but no point me figuring it out if no-one has done it yet 🤷)

    This change improves bundle-ability by reducing the number of dynamic imports.

    Also: PgAdaptorOptions has been renamed to PgAdaptorSettings, so please do a global find and replace for that.

  • #2120 925123497 Thanks @benjie! - Internal refactoring of pg adaptor.

  • #2119 aa0474755 Thanks @benjie! - Reflect in types that pgSettings object keys may be undefined.

  • Updated dependencies [1bd50b61e, 4e102b1a1, 7bb1573ba, 18addb385, 6ed615e55, b25cc539c, 867f33136, cf535c210, acf99b190, 4967a197f, 1908e1ba1, 084d80be6]:

0.0.1-beta.22

Patch Changes

  • #2071 582bd768f Thanks @benjie! - GrafastExecutionArgs now accepts resolvedPreset and requestContext directly; passing these through additional arguments is now deprecated and support will be removed in a future revision. This affects:

    • grafast()
    • execute()
    • subscribe()
    • hookArgs()

    graphile-config has gained a middleware system which is more powerful than it's AsyncHooks system. Old hooks can be emulated through the middleware system safely since middleware is a superset of hooks' capabilities. applyHooks has been renamed to orderedApply (because it applies to more than just hooks), calling applyHooks will still work but is deprecated.

    🚨 grafast no longer automatically reads your graphile.config.ts or similar; you must do that yourself and pass the resolvedPreset to grafast via the args. This is to aid in bundling of grafast since it should not need to read from filesystem or dynamically load modules.

    grafast no longer outputs performance warning when you set GRAPHILE_ENV=development.

    🚨 plugin.grafast.hooks.args is now plugin.grafast.middleware.prepareArgs, and the signature has changed - you must be sure to call the next() function and ctx/resolvedPreset can be extracted directly from args:

     const plugin = {
       grafast: {
    -    hooks: {
    +    middleware: {
    -      args({ args, ctx, resolvedPreset }) {
    +      prepareArgs(next, { args }) {
    +        const { requestContext: ctx, resolvedPreset } = args;
             // ...
    +        return next();
           }
         }
       }
     }

    Many more middleware have been added; use TypeScript's autocomplete to see what's available until we have proper documentation for them.

    plugin.grafserv.hooks.* are still supported but deprecated; instead use middleware plugin.grafserv.middleware.* (note that call signatures have changed slightly, similar to the diff above):

    • hooks.init -> middleware.setPreset
    • hooks.processGraphQLRequestBody -> middleware.processGraphQLRequestBody
    • hooks.ruruHTMLParts -> middleware.ruruHTMLParts

    A few TypeScript types related to Hooks have been renamed, but their old names are still available, just deprecated. They will be removed in a future update:

    • HookObject -> FunctionalityObject
    • PluginHook -> CallbackOrDescriptor
    • PluginHookObject -> CallbackDescriptor
    • PluginHookCallback -> UnwrapCallback
  • Updated dependencies [582bd768f]:

0.0.1-beta.21

Patch Changes

0.0.1-beta.20

Patch Changes

0.0.1-beta.19

Patch Changes

0.0.1-beta.18

Patch Changes

0.0.1-beta.17

Patch Changes

0.0.1-beta.16

Patch Changes

0.0.1-beta.15

Patch Changes

0.0.1-beta.14

Patch Changes

0.0.1-beta.13

Patch Changes

0.0.1-beta.12

Patch Changes

0.0.1-beta.11

Patch Changes

0.0.1-beta.10

Patch Changes

0.0.1-beta.9

Patch Changes

0.0.1-beta.8

Patch Changes

0.0.1-beta.7

Patch Changes

0.0.1-beta.6

Patch Changes

0.0.1-beta.5

Patch Changes

0.0.1-beta.4

Patch Changes

  • #462 53f0488b1 Thanks @benjie! - Allow 'null' to be passed to withPgClient/withPgClientTransaction

  • #464 00d026409 Thanks @benjie! - @dataplan/pg/adaptors/pg now adds rawClient property which is the underlying Postgres client for use with pgTyped, zapatos, and other libraries that can use a raw postgres client. This is exposed via NodePostgresPgClient interface which is a subtype of PgClient.

  • Updated dependencies [f9cc88dc4]:

0.0.1-beta.3

Patch Changes

0.0.1-beta.2

Patch Changes

0.0.1-beta.1

Patch Changes

0.0.1-alpha.17

Patch Changes

0.0.1-alpha.16

Patch Changes

0.0.1-alpha.15

Patch Changes

0.0.1-alpha.14

Patch Changes

0.0.1-alpha.13

Patch Changes

0.0.1-alpha.12

Patch Changes

0.0.1-alpha.11

Patch Changes

0.0.1-alpha.10

Patch Changes

0.0.1-alpha.9

Patch Changes

0.0.1-alpha.8

Patch Changes

0.0.1-alpha.7

Patch Changes

0.0.1-alpha.6

Patch Changes

0.0.1-alpha.5

Patch Changes

0.0.1-alpha.4

Patch Changes

0.0.1-alpha.3

Patch Changes

0.0.1-alpha.2

Patch Changes

0.0.1-alpha.1

Patch Changes

0.0.1-1.3

Patch Changes

0.0.1-1.2

Patch Changes

0.0.1-1.1

Patch Changes

  • #279 2df36c5a1 Thanks @benjie! - description moved out of extensions to live directly on all the relevant entities.

  • #279 a73f9c709 Thanks @benjie! - PgConnectionArgFirstLastBeforeAfterPlugin is now PgFirstLastBeforeAfterArgsPlugin (because it applies to lists as well as connections). PgInsertStep/pgInsert()/PgUpdateStep/pgUpdate()/PgDeleteStep/pgDelete() are now PgInsertSingleStep/pgInsertSingle()/PgUpdateSingleStep/pgUpdateSingle()/PgDeleteSingleStep/pgDeleteSingle() (to make space to add a future bulk API if we want to). config.schema.orderByNullsLast is now config.schema.pgOrderByNullsLast for consistency (V4 preset users are unaffected). Lots of field scopes in graphile-build-pg have been updated to incorporate field into their names.

  • #270 ef42d717c Thanks @benjie! - SQL is now generated in a slightly different way, helping PostgreSQL to optimize queries that have a batch size of 1. Also removes internal mapping code as we now simply append placeholder values rather than search and replacing a symbol (eradicates queryValuesSymbol and related hacks). If you manually issue queries through PgExecutor (extremely unlikely!) then you'll want to check out PR #270 to see the differences.

  • #260 d5312e6b9 Thanks @benjie! - TypeScript v5 is now required

  • #265 22ec50e36 Thanks @benjie! - 'extensions.graphile' is now 'extensions.grafast'

  • #259 c22dcde7b Thanks @benjie! - Renamed recordType codec factory to recordCodec. recordCodec() now only accepts a single object argument. Renamed enumType codec factory to enumCodec. enumCodec() now only accepts a single object argument. Rename listOfType to listOfCodec.

    Massive overhaul of PgTypeCodec, PgTypeColumn and PgTypeColumns generics - types should be passed through much deeper now, but if you reference any of these types directly you'll need to update your code.

  • #285 bd37be707 Thanks @benjie! - Single table inheritance no longer exposes non-shared columns via condition/order, and also only exposes the relationships on the types where they are appropriate.

  • #270 f8954fb17 Thanks @benjie! - EXPLAIN ANALYZE (for SELECT) and EXPLAIN (for other operations) support added. Currently requires DEBUG="datasource:pg:PgExecutor:explain" to be set. Publish this through all the way to Ruru.

  • #260 96b0bd14e Thanks @benjie! - PgSource has been renamed to PgResource, PgTypeCodec to PgCodec, PgEnumTypeCodec to PgEnumCodec, PgTypeColumn to PgCodecAttribute (and similar for related types/interfaces). source has been replaced by resource in various of the APIs where it relates to a PgResource.

    PgSourceBuilder is no more, instead being replaced with PgResourceOptions and being built into the final PgResource via the new makeRegistryBuilder/makeRegistry functions.

    build.input no longer contains the pgSources directly, instead build.input.pgRegistry.pgResources should be used.

    The new registry system also means that various of the hooks in the gather phase have been renamed/replaced, there's a new PgRegistryPlugin plugin in the default preset. The only plugin that uses the main method in the gather phase is now PgRegistryPlugin - if you are using the main function for Postgres-related behaviors you should consider moving your logic to hooks instead.

    Plugin ordering has changed and thus the shape of the final schema is likely to change (please use lexicographicSortSchema on your before/after schemas when comparing).

    Relationships are now from a codec to a resource, rather than from resource to resource, so all the relationship inflectors (singleRelation, singleRelationBackwards, _manyRelation, manyRelationConnection, manyRelationList) now accept different parameters ({registry, codec, relationName} instead of {source, relationaName}).

    Significant type overhaul, most generic types no longer require generics to be explicitly passed in many circumstances. PgSelectStep, PgSelectSingleStep, PgInsertStep, PgUpdateStep and PgDeleteStep now all accept the resource as their single type parameter rather than accepting the 4 generics they did previously. PgClassExpressionStep now accepts just a codec and a resource as generics. PgResource and PgCodec have gained a new TName extends string generic at the very front that is used by the registry system to massively improve continuity of the types through all the various APIs.

    Fixed various issues in schema exporting, and detect more potential issues/oversights automatically.

    Fixes an RBAC bug when using superuser role for introspection.

  • #279 fbf1da26a Thanks @benjie! - listOfCodec type signature changed: all parameters after the first are now a single config object: listOfCodec(listedCodec, extensions, typeDelim, identifier) -> listOfCodec(listedCodec, { extensions, typeDelim, identifier }).

  • #270 c564825f3 Thanks @benjie! - set jit = 'off' replaced with set jit_optimize_above_cost = -1 so that JIT can still be used but heavy optimization costs are not incurred.

  • #271 261eb520b Thanks @benjie! - 🚨 RENAME ALL THE THINGS

    The term 'source' was overloaded, and 'configs' was too vague, and 'databaseName' was misleading, and 'source' behaviours actually applied to resources, and more. So, we've renamed lots of things as part of the API stabilization work. You're probably only affected by the first 2 bullet points.

    • pgConfigs -> pgServices (also applies to related pgConfig terms such as makePgConfig -> makePgService, MakePgConfigOptions -> MakePgServiceOptions, etc) - see your graphile.config.ts or equivalent file
    • All *:source:* behaviors are now *:resource:* behaviors (use regexp /:source\b|\bsource:[a-z$]/ to find the places that need updating)
    • PgDatabaseConfiguration -> PgServiceConfiguration
    • databaseName -> serviceName (because it's not the name of the database, it's the name of the pgServices (which was pgConfigs) entry)
    • PgResourceConfig::source -> PgResourceConfig.from ('source' is overloaded, so use a more direct term)
    • PgResource::source -> PgResource.from
    • PgSelectPlanJoin::source -> PgSelectPlanJoin.from
    • helpers.pgIntrospection.getDatabase -> helpers.pgIntrospection.getService
    • helpers.pgIntrospection.getExecutorForDatabase -> helpers.pgIntrospection.getExecutorForService
  • #266 395b4a2dd Thanks @benjie! - The Grafast step class 'execute' and 'stream' methods now have a new additional first argument count which indicates how many results they must return. This means we don't need to rely on the values[0].length trick to determine how many results to return, and thus we can pass through an empty tuple to steps that have no dependencies.

  • Updated dependencies [ae304b33c, d5312e6b9, 22ec50e36, 0f4709356, f93c79b94, 53e164cbc, 395b4a2dd]:

0.0.1-0.28

Patch Changes

0.0.1-0.27

Patch Changes

0.0.1-0.26

Patch Changes

0.0.1-0.25

Patch Changes

0.0.1-0.24

Patch Changes

0.0.1-0.23

Patch Changes

0.0.1-0.22

Patch Changes

0.0.1-0.21

Patch Changes

0.0.1-0.20

Patch Changes

0.0.1-0.19

Patch Changes

0.0.1-0.18

Patch Changes

0.0.1-0.17

Patch Changes

0.0.1-0.16

Patch Changes

0.0.1-0.15

Patch Changes

  • 0ab95d0b1 - Update sponsors.

  • #196 af9bc38c8 Thanks @benjie! - Allow passing pool directly to makePgConfig.

  • #190 652cf1073 Thanks @benjie! - 🚨 Breaking changes around types and postgres configuration:

    • GraphileBuild.GraphileResolverContext renamed to Grafast.Context
    • GraphileConfig.GraphQLRequestContext renamed to Grafast.RequestContext
    • Grafast.PgDatabaseAdaptorOptions renaed to GraphileConfig.PgDatabaseAdaptorOptions
    • @dataplan/pg/adaptors/node-postgres is now @dataplan/pg/adaptors/pg due to the bizarre naming of PostgreSQL clients on npm - we've decided to use the module name as the unique identifier
    • makePgConfigs:
      • is now makePgConfig (singular) - so you'll need to wrap it in an array where you use it
      • no longer exported by @dataplan/pg (because it depended on pg) - instead each adaptor exposes this helper - so import from @dataplan/pg/adaptors/node-postgres
      • accepts an object parameter containing {connectionString, schemas, superuserConnectionString}, rather than multiple string parameters
    • makeNodePostgresWithPgClient -> makePgAdaptorWithPgClient
    • postgraphile CLI will now try and respect the adaptor stated in your preset when overriding connection arguments
    • Removed Grafast.RequestContext.httpRequest and instead use Grafast.RequestContext.node.req/res; all server adaptors should implement this if appropriate
  • #192 80091a8e0 Thanks @benjie! - - Conflicts in pgConfigs (e.g. multiple sources using the same 'name') now detected and output

    • Fix defaults for pgSettingsKey and withPgClientKey based on config name
    • makePgConfig now allows passing pgSettings callback and pgSettingsForIntrospection config object
    • Multiple postgres sources now works nicely with multiple makePgConfig calls
  • Updated dependencies [0ab95d0b1, 4783bdd7c, 652cf1073]:

0.0.1-0.14

Patch Changes

0.0.1-0.13

Patch Changes

0.0.1-0.12

Patch Changes

0.0.1-0.11

Patch Changes

  • 0e440a862 Thanks @benjie! - Add new --superuser-connection option to allow installing watch fixtures as superuser.

0.0.1-0.10

Patch Changes

0.0.1-0.9

Patch Changes

  • c4213e91d - Add pgl.getResolvedPreset() API; fix Ruru respecting graphqlPath setting; replace 'instance' with 'pgl'/'serv' as appropriate; forbid subscriptions on GET

0.0.1-0.8

Patch Changes

0.0.1-0.7

Patch Changes

0.0.1-0.6

Patch Changes

0.0.1-0.5

Patch Changes

  • 9ebe3d860 - Fix issue with webpack bundling adaptor

0.0.1-0.4

Patch Changes

0.0.1-0.3

Patch Changes

0.0.1-0.2

Patch Changes

0.0.1-0.1

Patch Changes

0.0.1-0.0

Patch Changes