postgraphile-core

postgraphile-core

This module implements a compatibility layer between PostGraphQL v4 and graphile-build, loading the relevant graphile-build-pg plugins and setting the correct inflector depending on the PostGraphQL options provided.

It's also suitable for usage in your own application, but please be aware you need to bring your own security in the form of an authenticated pgClient (see below).

For more information about graphile-build-pg please see the documentation at graphile.org.

createPostGraphQLSchema(pgConfig, schemas, options)

This is the function you're most likely to use in production, it will return a promise to a GraphQL schema. You are responsible in the calling code for implementing security by passing a pre-authenticated pgClient on context.

Example:

const schema = await createPostGraphQLSchema(
  process.env.DATABASE_URL,
  ['users_schema', 'posts_schema'],
  {
    dynamicJson: true,
    pgJwtSecret: process.env.JWT_SECRET,
    pgJwtTypeIdentifier: 'users_schema.jwt_type',
  }
);

Full example:

const { createPostGraphQLSchema } = require('graphile-build-pg');
const pg = require('pg');

// Create a postgres pool for efficiency
const pgPool = new pg.Pool(process.env.DATABASE_URL);

async function runQuery(query, variables) {

  // Generate our schema using the default plugins against DATABASE_URL,
  // introspecting the two schemas specified with the options provided.
  //
  // Normally for performance you'd only do this once for your entire
  // application run, not once per query as it is here.
  const schema = await createPostGraphQLSchema(
    process.env.DATABASE_URL,
    ['users_schema', 'posts_schema'],
    {
      dynamicJson: true,
      pgJwtSecret: process.env.JWT_SECRET,
      pgJwtTypeIdentifier: 'users_schema.jwt_type',
    }
  );

  // Fetch a postgres client from the pool
  const pgClient = await pgPool.connect();

  // Start a transaction so we can apply settings local to the transaction
  await pgClient.query("begin");

  try {
    // The following statement is equivalent to (but faster than):
    //    await pgClient.query("set local role to 'postgraphql_user'");
    //    await pgClient.query("set local jwt.claims.user_id to '27'");
    await pgClient.query(`select
      set_config('role', 'postgraphql_user', true),
      set_config('jwt.claims.user_id', '27', true)
    `);
    return await graphql(
      schema,
      query,
      null,
      /* CONTEXT > */ {
        pgClient: pgClient,
      }, /* < CONTEXT */
      variables
    );
  } finally {
    // commit the transaction (or rollback if there was an error) to clear the local settings
    await pgClient.query("commit");

    // Release the pgClient back to the pool.
    await pgClient.release();
  }
}

// Normally you'd execute a query in response to an HTTP request or similar
runQuery(
  // This query obviously depends on your database schema
  "query MyQuery { allPosts { nodes { id, title, author: userByAuthorId { username } } } }"
).then(result => {
  console.dir(result);
  pgPool.release();
}).catch(e => {
  console.error(e);
  process.exit(1);
});

TODO: ensure this example works.

To see how this works in a real application, check out withPostGraphQLContext in PostGraphQL

watchPostGraphQLSchema(pgConfig, schemas, options, onNewSchema)

This function is useful in development; it returns a promise that resolves to a release function that you can call to stop watching. The onNewSchema callback will be called every time a new schema is generated, and it is guaranteed to be called before the returned promise resolves. Other than the additional onNewSchema option, the options are identical to that of createPostGraphQLSchema above.

Changelog

0.1.0-alpha.27 (2017-08-23)

Bug Fixes

• errors: tweaks to errors/logs/etc (#56) (74654d5)

Features

• export case utils (#58) (8531671)
• graphile-build-pg: export case-altering functions (#54) (fd5fe1c)