PostGraphile

https://postgraphile.org/postgraphile/5
Admin
PostGraphile is a powerful tool that automatically builds a high-performance, customizable GraphQL...
Tokens:133,368
Snippets:1,577
Trust Score:6.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Manual pgServices Configuration

Source: https://postgraphile.org/postgraphile/5/config/overview

This example demonstrates advanced manual configuration of `pgServices`. It is typically not needed as helper functions like `makePgService` are recommended for most users. Ensure you have the `pg` and `@dataplan/pg/adaptors/pg` modules installed.

```typescript
import * as pg from "pg";
import * as adaptor from "@dataplan/pg/adaptors/pg";

const pgServices = [
  {
    name: "main",
    schemas: ["app_public"],
    pgSettingsKey: "pgSettings",
    withPgClientKey: "withPgClient",
    adaptor,
    adaptorSettings: {
      pool: new pg.Pool({ connectionString: process.env.DATABASE_URL }),
      superuserPool: new pg.Pool({
        connectionString: process.env.SUPERUSER_DATABASE_URL,
      }),
    },
  },
];

```

--------------------------------

### Install PostGraphile with Bun

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Install the PostGraphile module locally using Bun.

```bash
bun add postgraphile
```

--------------------------------

### Install PostGraphile with Bun

Source: https://postgraphile.org/postgraphile/5/usage-cli

Install PostGraphile in your project directory using Bun.

```bash
cd ~/postgraphile
bun add postgraphile  

```

--------------------------------

### Test Docker Installation

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-in-docker

Runs the 'hello-world' Docker image to verify that Docker is installed and functioning correctly.

```bash
docker run hello-world

```

--------------------------------

### Start PostGraphile Server

Source: https://postgraphile.org/postgraphile/5/postgresql-schema-design

Start the PostGraphile server with the specified database connection string.

```bash
postgraphile \
  --connection postgres://forum_example_postgraphile:xyz@localhost/mydb
```

--------------------------------

### PostGraphile Configuration Example

Source: https://postgraphile.org/postgraphile/5/config

This snippet shows a complete PostGraphile configuration using presets, plugins, and database service setup. It's useful for setting up a complex GraphQL API with PostGraphile.

```typescript
// The standard base preset to use, includes the main PostGraphile features  
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";  
  
// More presets you might want to mix in  
import { makeV4Preset } from "postgraphile/presets/v4";  
import { PostGraphileRelayPreset } from "postgraphile/presets/relay";  
  
// Use the 'pg' module to connect to the database  
import { makePgService } from "postgraphile/adaptors/pg";  
  
// A plugin for the system to use for persisted operations support  
import PersistedPlugin from "@grafserv/persisted";  
  
const preset: GraphileConfig.Preset = {  
  extends: [  
    PostGraphileAmberPreset,  
    /* Add more presets here, e.g.: */  
    makeV4Preset({  
      simpleCollections: "both",  
      jwtPgTypeIdentifier: '"b"."jwt_token"',  
      dynamicJson: true,  
      graphiql: true,  
      graphiqlRoute: "/",  
    }),  
    // Uncomment this to opt into a smaller Relay-focussed schema  
    //PostGraphileRelayPreset,  
  ],  
  
  plugins: [  
    /* Add plugins here, e.g.: */  
    PersistedPlugin,  
  ],  
  
  inflection: {  
    /* options for the inflection system */  
  },  
  gather: {  
    /* options for the gather phase, e.g.: */  
    pgStrictFunctions: true,  
    installWatchFixtures: true,  
  },  
  schema: {  
    /* options for the schema build phase, e.g.: */  
    retryOnInitFail: true,  
    exportSchemaSDLPath: `${process.cwd()}/latestSchema.graphql`,  
    exportSchemaIntrospectionResultPath: `${process.cwd()}/latestSchema.json`,  
    sortExport: true,  
  },  
  grafast: {  
    /* options for Grafast, including setting GraphQL context, e.g.: */  
    context: {  
      meaningOfLife: 42,  
    },  
    // explain: true, // DO NOT ENABLE IN PRODUCTION!  
  },  
  grafserv: {  
    /* options for Grafserv, e.g.: */  
    port: 5678,  
    graphqlPath: "/graphql",  
    websockets: true,  
    graphqlOverGET: true,  
    persistedOperationsDirectory: `${process.cwd()}/.persisted_operations`,  
    allowUnpersistedOperation: true,  
  },  
  ruru: {  
    /* options for customizing Ruru, e.g.: */  
    htmlParts: {  
      metaTags: (base) => base + "<!-- HELLO WORLD! -->",  
    },  
  },  
  pgServices: [  
    /* list of PG database configurations, e.g.: */  
    makePgService({  
      // Database connection string, read from an environmental variable:  
      connectionString: process.env.DATABASE_URL,  
  
      // List of database schemas to expose:  
      schemas: ["app_public"],  
  
      // Enable LISTEN/NOTIFY:  
      pubsub: true,  
    }),  
  ],  
};  
  
export default preset;  

```

--------------------------------

### Express Server Setup (server.ts)

Source: https://postgraphile.org/postgraphile/5/usage-library

Set up an Express server to host the PostGraphile GraphQL endpoint. This file integrates PostGraphile with Express and starts the HTTP server.

```typescript
import { createServer } from "node:http";
import express from "express";
import { grafserv } from "postgraphile/grafserv/express/v4";
import preset from "./graphile.config.ts";
import { pgl } from "./pgl.ts";

const serv = pgl.createServ(grafserv);

const app = express();
const server = createServer(app);
server.once("listening", () => {
  server.on("error", (e) => void console.error(e));
});
serv.addTo(app, server).catch((e) => {
  console.error(e);
  process.exit(1);
});

const { host, port } = preset.grafserv;
server.listen(port, host);

console.log(`Server listening at http://${host}:${port}`);

```

--------------------------------

### Run PostGraphile server

Source: https://postgraphile.org/postgraphile/5/usage-library

Command to start the PostGraphile server using the defined npm start script.

```bash
npm start
```

--------------------------------

### Install PostGraphile with pnpm

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Install the PostGraphile module locally using pnpm.

```bash
pnpm add postgraphile
```

--------------------------------

### PostGraphile V5 CLI Example

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

Example of how to run the PostGraphile V5 CLI with common options. The `pgl` command is an alias for `postgraphile`.

```bash
postgraphile -P postgraphile/presets/amber -c postgres:///my_db_name -s public -e  
# or: pgl -P pgl/amber -c postgres:///my_db_name -s public -e  

```

--------------------------------

### Install PostGraphile with npm

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Install the PostGraphile module locally using npm.

```bash
npm install --save postgraphile
```

--------------------------------

### Install PostGraphile and Express with npm

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs the necessary npm packages, 'express' and 'postgraphile', for the project. This command should be run after initializing the Node.js project.

```bash
npm install --save express postgraphile  

```

--------------------------------

### Install PostGraphile with pnpm

Source: https://postgraphile.org/postgraphile/5/usage-cli

Install PostGraphile in your project directory using pnpm.

```bash
cd ~/postgraphile
pnpm add postgraphile  

```

--------------------------------

### Create User Mutation Example

Source: https://postgraphile.org/postgraphile/5/crud-mutations

Example of creating a new user record and retrieving its details, including automatically generated fields like `createdAt`.

```graphql
mutation {
  createUser(
    input: { user: { id: 1, name: "Bilbo Baggins", username: "bilbo" } }
  ) {
    user {
      id
      name
      username
      createdAt
    }
  }
}
```

--------------------------------

### Install PostGraphile with npm

Source: https://postgraphile.org/postgraphile/5/usage-cli

Install PostGraphile in your project directory using npm.

```bash
cd ~/postgraphile
npm install postgraphile  

```

--------------------------------

### Connect to the Created Database

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Connect to the 'mydb' database using psql to get a SQL prompt.

```bash
psql "postgres:///mydb"
```

--------------------------------

### Install PostGraphile with Yarn

Source: https://postgraphile.org/postgraphile/5/usage-cli

Install PostGraphile in your project directory using Yarn.

```bash
cd ~/postgraphile
yarn add postgraphile  

```

--------------------------------

### Install PostGraphile with Yarn

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Install the PostGraphile module locally using Yarn.

```bash
yarn add postgraphile
```

--------------------------------

### Install a Server Extension

Source: https://postgraphile.org/postgraphile/5/plugins

Install a server extension using yarn or npm. This command adds the specified package to your project's dependencies.

```bash
yarn add @grafserv/persisted  

```

--------------------------------

### package.json for Starting the App

Source: https://postgraphile.org/postgraphile/5/deploying-gcp

Defines the script to start the Node.js application using 'node src/index.mjs'.

```json
{
  "scripts": {
    "start": "node src/index.mjs"
  }
}

```

--------------------------------

### Full Example: Node.js HTTP Server Integration

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

This example demonstrates the complete integration of PostGraphile V5 with Node.js' built-in HTTP server, including configuration loading, PostGraphile and Grafserv instance creation, and server startup.

```javascript
import preset from "./graphile.config.js";  
import { postgraphile } from "postgraphile";  
import { grafserv } from "grafserv/node"; // Adaptor for Node's HTTP server  
import { createServer } from "node:http";  
  
// Create an HTTP server (with error handler)  
const server = createServer();  
server.on("error", (e) => console.error(e));  
  
// Create a PostGraphile instance (pgl)  
const pgl = postgraphile(preset);  
// Create a Grafserv (server adaptor) instance for this PostGraphile instance  
const serv = pgl.createServ(grafserv);  
// Attach a request handler to the server  
serv.addTo(server);  
  
// Start the server  
server.listen(preset.grafserv?.port ?? 5678);  
```

--------------------------------

### Run All Containers

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-as-a-library-in-docker

Starts all services defined in the docker-compose.yml file.

```bash
docker-compose up
```

--------------------------------

### Install Dependencies with Bun

Source: https://postgraphile.org/postgraphile/5/jwk-verification

Install the necessary packages for Express JWT verification and JWKS retrieval using Bun.

```bash
bun add express express-jwt jwks-rsa  

```

--------------------------------

### Install dependencies with Bun for TypeScript

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs PostGraphile, Express, and related TypeScript development dependencies using Bun.

```bash
bun add --legacy-peer-deps express postgraphile @graphile/simplify-inflection
bun add --dev typescript @tsconfig/node24 @tsconfig/node-ts @types/express @types/node
```

--------------------------------

### Install PostGraphile and Express with Bun

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs the 'express' and 'postgraphile' packages using Bun. This is a fast, all-in-one JavaScript runtime and package manager.

```bash
bun add express postgraphile  

```

--------------------------------

### Check PostgreSQL Installation

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Attempt to connect to the default PostgreSQL database to confirm installation. A fatal error indicating the database does not exist is a success case.

```bash
psql "postgres:///"
```

--------------------------------

### Install and List Inflectors with Bun

Source: https://postgraphile.org/postgraphile/5/inflection

Install the 'graphile' development dependency and use the 'bun x graphile inflection list' command to view all available inflectors and their documentation.

```bash
npm install --save-dev graphile  
bun x graphile inflection list  

```

--------------------------------

### GraphQL Query Example

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-in-docker

An example GraphQL query to fetch all posts along with their author's username.

```graphql
query {
  allPosts {
    nodes {
      id
      title
      body
      userByAuthorId {
        username
      }
    }
  }
}
```

--------------------------------

### Install Dependencies with npm

Source: https://postgraphile.org/postgraphile/5/jwk-verification

Install the necessary packages for Express JWT verification and JWKS retrieval using npm.

```bash
npm install --save express express-jwt jwks-rsa  

```

--------------------------------

### PostGraphile Test Helper Setup

Source: https://postgraphile.org/postgraphile/5/testing-jest

This TypeScript code sets up a helper for running PostGraphile integration tests. It imports necessary modules, defines types for data masking, and includes a beforeEach hook to reset the mask cache. It also defines a setup function to initialize the PostGraphile instance, schema, and a PostgreSQL connection pool.

```typescript
import { Pool } from "pg";  
import type { PostGraphileInstance } from "postgraphile";  
import { postgraphile } from "postgraphile";  
import { makeWithPgClientViaPgClientAlreadyInTransaction } from "postgraphile/adaptors/pg";  
import { execute, hookArgs } from "postgraphile/grafast";  
import type { PromiseOrDirect } from "postgraphile/grafast";  
import type { ExecutionResult, GraphQLSchema } from "postgraphile/graphql";  
import { parse, validate } from "postgraphile/graphql";  
import preset from "../src/graphile.config.ts";  
  
const MockReq = require("mock-req");  
  
type Maskable = "nodeId" | "id" | "timestamp" | "email" | "username";  
type MaskCache = { counter: number; values: Map<unknown, string> };  

let maskCacheByType: Record<Maskable, MaskCache | undefined> = {};  
// Reset the cache before each test  
beforeEach(() => {
  maskCacheByType = {};
});  
  
/**  
 * Replaces values that are expected to change between test runs with static  
 * placeholders so that our snapshot testing doesn't throw an error  
 * every time we run the tests because time has ticked on in it's inevitable  
 * march toward the future.  
 */  
export function sanitize(json: any): any {  
  /** Maintain stable references whilst dealing with variable values */  
  function mask(value: unknown, type: Maskable) {  
    if (!maskCacheByType[type]) {  
      maskCacheByType[type] = { counter: 0, values: new Map() };  
    }  
    const maskCache = maskCacheByType[type];  
    if (!maskCache.values.has(value)) {  
      maskCache.values.set(value, `[${type}-${++maskCache.counter}]`);  
    }  
    return maskCache.values.get(value);  
  }  
  
  if (Array.isArray(json)) {  
    return json.map((val) => sanitize(val));  
  } else if (json && typeof json === "object") {  
    const result = { ...json };  
    for (const k in result) {  
      if (k === "nodeId" && typeof result[k] === "string") {  
        result[k] = mask(result[k], "nodeId");  
      } else if (  
        k === "id" ||  
        k === "uuid" ||  
        (k.endsWith("Id") &&  
          (typeof json[k] === "number" || typeof json[k] === "string")) ||  
        (k.endsWith("Uuid") && typeof k === "string")  
      ) {  
        result[k] = mask(result[k], "id");  
      } else if (  
        (k.endsWith("At") || k === "datetime") &&  
        typeof json[k] === "string"  
      ) {  
        result[k] = mask(result[k], "timestamp");  
      } else if (  
        k.match(/^deleted[A-Za-z0-9]+Id$/) &&  
        typeof json[k] === "string"  
      ) {  
        result[k] = mask(result[k], "nodeId");  
      } else if (k === "email" && typeof json[k] === "string") {  
        result[k] = mask(result[k], "email");  
      } else if (k === "username" && typeof json[k] === "string") {  
        result[k] = mask(result[k], "username");  
      } else {  
        result[k] = sanitize(json[k]);  
      }  
    }  
    return result;  
  } else {  
    return json;  
  }  
}  
  
function noop() {  
  /* noop */  
}  
  
interface TestContext {  
  pgl: PostGraphileInstance;  
  schema: GraphQLSchema;  
  resolvedPreset: GraphileConfig.ResolvedPreset;  
  pgPool: Pool;  
}  
let ctx: TestContext | null = null;  
  
export const setup = async () => {  
  if (!process.env.TEST_DATABASE_URL) {  
    throw new Error("Cannot run tests without a TEST_DATABASE_URL");  
  }  
  const pgl = postgraphile(preset);  
  const { schema, resolvedPreset } = await pgl.getSchemaResult();  
  
  const pgPool = new Pool({  
    connectionString: process.env.TEST_DATABASE_URL,  
  });  
  pgPool.on("error", noop);  
  pgPool.on("connect", (client) => client.on("error", noop));  
  

```

--------------------------------

### Example package.json with ES Modules

Source: https://postgraphile.org/postgraphile/5/usage-library

Shows the structure of a package.json file configured for ES Modules with PostGraphile and Express.

```json
{
  "name": "postgraphile_express",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.21.2",
    "postgraphile": "^5.0.0-beta.38"
  },
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.js"
  }
}
```

--------------------------------

### Project File Structure

Source: https://postgraphile.org/postgraphile/5/deploying-gcp

Example project structure for a PostGraphile application.

```plaintext
/project
|--package.json
|--/src
   |--index.js

```

--------------------------------

### Install and List Inflectors with npm

Source: https://postgraphile.org/postgraphile/5/inflection

Install the 'graphile' development dependency and use the 'npx graphile inflection list' command to view all available inflectors and their documentation.

```bash
npm install --save-dev graphile  
npx graphile inflection list  

```

--------------------------------

### Connect PostGraphile with Role

Source: https://postgraphile.org/postgraphile/5/postgresql-schema-design

Start PostGraphile using the connection string that includes the dedicated PostGraphile role and its password.

```bash
postgraphile -c postgres://forum_example_postgraphile:xyz@localhost/mydb
```

--------------------------------

### Package.json Scripts and Dependencies

Source: https://postgraphile.org/postgraphile/5/usage-library

Configure package.json with necessary dependencies and scripts for starting, building, and running the application in development and production.

```json
{
  "name": "postgraphile_express_typescript",
  "scripts": {
    "start": "node --env-file=./.env src/server.ts",
    "build": "tsc",
    "prod": "node dist/server.js"
  },
  "type": "module",
  "private": true,
  "dependencies": {
    "@graphile/simplify-inflection": "^8.0.0-rc.3",
    "express": "^5.2.1",
    "postgraphile": "^5.0.0-rc.4"
  },
  "devDependencies": {
    "@tsconfig/node-ts": "^23.6.2",
    "@tsconfig/node24": "^24.0.4",
    "@types/express": "^5.0.6",
    "@types/node": "^25.0.10",
    "typescript": "^5.9.3"
  }
}

```

--------------------------------

### Example Subscription Plugin

Source: https://postgraphile.org/postgraphile/5/subscriptions

An example PostGraphile plugin that extends the schema to include a `forumMessage` subscription. It uses `pgSubscriber` to listen for new messages on a specific topic and resolves the subscription payload.

```javascript
import { extendSchema } from "postgraphile/utils";
import { context, lambda, listen } from "postgraphile/grafast";
import { jsonParse } from "postgraphile/@dataplan/json";

const MySubscriptionPlugin = extendSchema((build) => {
  const { messages } = build.pgResources;
  return {
    typeDefs: /* GraphQL */ `
      extend type Subscription {
        forumMessage(forumId: Int!): ForumMessageSubscriptionPayload
      }

      type ForumMessageSubscriptionPayload {
        event: String
        message: Message
      }
    `,
    objects: {
      Subscription: {
        plans: {
          forumMessage: {
            subscribePlan(_$root, args) {
              const $pgSubscriber = context().get("pgSubscriber");
              const $forumId = args.get("forumId");
              const $topic = lambda($forumId, (id) => `forum:${id}:message`);
              return listen($pgSubscriber, $topic, jsonParse);
            },
            plan($event) {
              return $event;
            },
          },
        },
      },
      ForumMessageSubscriptionPayload: {
        plans: {
          event($event) {
            return $event.get("event");
          },
          message($event) {
            const $id = $event.get("id");
            return messages.get({ id: $id });
          },
        },
      },
    },
  };
});

```

--------------------------------

### View Available Configuration Options

Source: https://postgraphile.org/postgraphile/5/config/view

Use this command to list all available configuration options based on your current setup, including imported plugins and presets. This is a development aid.

```bash
graphile config options  

```

--------------------------------

### Install and List Inflectors with pnpm

Source: https://postgraphile.org/postgraphile/5/inflection

Install the 'graphile' development dependency and use the 'pnpm dlx graphile inflection list' command to view all available inflectors and their documentation.

```bash
npm install --save-dev graphile  
pnpm dlx graphile inflection list  

```

--------------------------------

### Behavior String Examples

Source: https://postgraphile.org/postgraphile/5/behavior

Illustrates the syntax of behavior strings, which are composed of space-separated fragments. Fragments can optionally start with '+' or '-' to indicate inclusion or exclusion, followed by a scope string.

```text
insert
```

```text
+list -connection -list:filter
```

```text
-insert -update -delete query:*:filter +connection -list
```

--------------------------------

### Example: Logging Mutation Arguments and Payload

Source: https://postgraphile.org/postgraphile/5/wrap-plans

This example demonstrates how to use wrapPlans to log the arguments and payload of root mutations. It filters for root mutations and applies a rule that uses sideEffect to log before and after the mutation plan executes.

```typescript
import { wrapPlans } from "postgraphile/utils";
import { sideEffect } from "postgraphile/grafast";

// Example: log before and after each mutation runs
export default wrapPlans(
  (context) => {
    if (context.scope.isRootMutation) {
      return { scope: context.scope };
    }
    return null;
  },
  ({ scope }) =>
    (plan, _, fieldArgs) => {
      sideEffect(fieldArgs.getRaw(), (args) => {
        console.log(
          `Mutation '${scope.fieldName}' starting with arguments:`,
          args,
        );
      });

      const $payload = plan();

      sideEffect($payload, (payload) => {
        console.log(`Mutation '${scope.fieldName}' payload:`, payload);
      });

      return $payload;
    },
);
```

--------------------------------

### Configuring V5 Presets and Plugins

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

Illustrates the V5 configuration structure where presets are extended and plugins are listed separately. This example shows how to integrate `makeV4Preset` with other presets and plugins.

```typescript
const preset: GraphileConfig.Preset = {
  extends: [
    makeV4Preset({
      /* ... */
    }),
    SomePreset,
  ],
  plugins: [SomePlugin],
};
export default preset;

```

--------------------------------

### Relay Modern Network Layer with JWT

Source: https://postgraphile.org/postgraphile/5/jwt-guide

Implement a custom fetch query function for Relay's network layer to include JWT in the request headers. This setup is documented in the Relay guides.

```javascript
function fetchQuery(operation, variables) {
  const token = getJWTToken();
  return fetch("/graphql", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: token ? `Bearer ${token}` : "",
    },
    body: JSON.stringify({
      query: operation.text,
      variables,
    }),
  }).then((response) => response.json());
}

const environment = new Environment({
  network: Network.create(fetchQuery),
  store: new Store(new RecordSource()),
});

```

--------------------------------

### Using makeV4Preset for V4 to V5 Migration

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

This example demonstrates how to use `makeV4Preset` to convert V4 options into V5 equivalents. It combines the preset with `postgraphile/presets/amber` and configures a PostgreSQL service.

```javascript
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
import { makeV4Preset } from "postgraphile/presets/v4";
import { makePgService } from "postgraphile/adaptors/pg";

/** @type {GraphileConfig.Preset} */
const preset = {
  extends: [
    PostGraphileAmberPreset,
    makeV4Preset({
      /* PUT YOUR V4 OPTIONS HERE, e.g.: */
      simpleCollections: "both",
      jwtPgTypeIdentifier: '"b"."jwt_token"',
    }),
  ],

  pgServices: [
    makePgService({
      connectionString: process.env.DATABASE_URL,
      schemas: ["app_public"],
    }),
  ],
};

export default preset;

```

--------------------------------

### Make HTTP Data Available to Plan Resolvers

Source: https://postgraphile.org/postgraphile/5/config/context

Use the `grafast.context` callback to extract data from the incoming HTTP request and make it accessible in Gra _fast_ schema resolvers. This example shows how to access the request object, user information, and add a helper function to get headers.

```javascript
export default {
  grafast: {
    async context(requestContext, args) {
      const req = requestContext.node?.req;
      // You can perform asynchronous actions here if you need to; for example
      // looking up the current user in the database.

      // Return here things that your resolvers need
      return {
        // Return the current user from Passport.js or similar
        user: req.user,

        // Add a helper to get a header
        getHeader(name) {
          return req?.get(name);
        },

        // Give access to the database-owner PostgreSQL pool, for example to
        // perform privileged actions
        rootPgPool,
      };
    },
  },
};
```

--------------------------------

### Dockerfile for PostGraphile

Source: https://postgraphile.org/postgraphile/5/deploying-docker

This Dockerfile sets up a PostGraphile server, including installing Yarn, focusing workspaces, and setting environment variables.

```dockerfile
RUN ["corepack", "enable"]
RUN ["yarn", "workspaces", "focus", "-A", "--production"]

LABEL description="My PostGraphile-powered server"

ENV HOST="0.0.0.0"
ENV NODE_ENV=$NODE_ENV
ENV GRAPHILE_ENV=$GRAPHILE_ENV
ENTRYPOINT ["yarn", "start:production"]
```

--------------------------------

### Create PostGraphile Instance

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

Instantiate PostGraphile by passing your configuration preset to the `postgraphile` function. The result is a PostGraphile instance (`pgl`) that provides helper methods for server integration.

```javascript
const pgl = postgraphile(preset);  
```

--------------------------------

### Express App Setup with PostGraphile (index.mjs)

Source: https://postgraphile.org/postgraphile/5/deploying-gcp

Sets up an Express application and integrates PostGraphile for API serving. It initializes PostGraphile with the configuration and adds the GraphQL server to the Express app.

```javascript
import express from "express";
import preset from "./graphile.config.mjs";
import { postgraphile } from "postgraphile";
import { grafserv } from "postgraphile/grafserv/express/v4";

const app = express();

const pgl = postgraphile(preset);
const serv = pgl.createServ(grafserv);

await serv.addTo(app);

app.listen(8080);

```

--------------------------------

### Minimal PostGraphile CLI Setup for Heroku

Source: https://postgraphile.org/postgraphile/5/deploying-heroku

Commands to initialize a project, add PostGraphile, configure Heroku remote, set database URL, and deploy using the PostGraphile CLI.

```bash
mkdir project_folder_name
cd project_folder_name && git init
yarn add postgraphile
git add . && git commit -m "Initial commit"
heroku git:remote -a heroku_app_name
heroku config:set RDS_URL="postgres://user:pass@rdshost/dbname?ssl=true" -a heroku_app_name
echo 'web: postgraphile' >> Procfile
git push heroku master
```

--------------------------------

### Safely Get Property with get()

Source: https://postgraphile.org/postgraphile/5/grafast-for-postgraphile-users

Use `get($step, key)` to retrieve a property `key` from `$step`. It safely uses `$step.get(key)` if supported, falling back to `access($step, key)` if not.

```javascript
import { get } from "postgraphile/grafast";

const $userId = get($user, "id");
```

--------------------------------

### Initialize TypeScript Node.js project

Source: https://postgraphile.org/postgraphile/5/usage-library

Creates a new directory, initializes a Node.js project, and sets up the basic project structure.

```bash
mkdir postgraphile_express_typescript
cd postgraphile_express_typescript
npm init -y
```

--------------------------------

### Install Docker CE on Linux

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-in-docker

Installs Docker Community Edition on Debian-based Linux distributions.

```bash
sudo apt-get update
sudo apt-get install docker-ce

```

--------------------------------

### Basic PostGraphile Preset (TypeScript)

Source: https://postgraphile.org/postgraphile/5/config

This example demonstrates a basic PostGraphile configuration preset using TypeScript. It also extends the 'Amber' preset and is suitable for projects that prefer TypeScript.

```typescript
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";

const preset: GraphileConfig.Preset = {
  extends: [PostGraphileAmberPreset],
};

export default preset;

```

--------------------------------

### GraphQL Mutation Example

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-in-docker

An example GraphQL mutation to create a new user with a specified username.

```graphql
mutation {
  createUser(input: { user: { username: "Bob" } }) {
    user {
      id
      username
      createdDate
    }
  }
}
```

--------------------------------

### Plugin with Default Behaviors and Hooks

Source: https://postgraphile.org/postgraphile/5/behavior

This example demonstrates how to define default behaviors for codecs and resources, and how to hook into field creation to act upon specific behaviors.

```javascript
const MyPlugin = {
  name: "MyPlugin",
  version: "0.0.0",

  schema: {
    // Register default behaviors (optional)
    entityBehaviors: {
      // Apply 'myCodecBehavior' by default to _all_ codecs
      pgCodec: "myCodecBehavior",

      // Apply 'myResourceBehavior' to resources with truthy `isUnique` (overrides defaults)
      pgResource(behavior, resource) {
        if (resource.isUnique) {
          return [behavior, "myResourceBehavior"];
        } else {
          return behavior;
        }
      },
    },

    // Do something with behaviors (optional)
    hooks: {
      GraphQLObjectType_fields_field(field, build, context) {
        const codec = context.scope.pgFieldCodec;
        if (
          !codec ||
          !build.behavior.pgCodecMatches(codec, "myCodecBehavior")
        ) {
          return field;
        }

        // Behavior matches! Do stuff here...

        return field;
      },
    },
  },
};

```

--------------------------------

### Connect to Local Database (bun)

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Connects to the 'mydb' database on the local PostgreSQL server using bun.

```bash
bun x postgraphile -P postgraphile/presets/amber -c "postgres:///mydb"
```

--------------------------------

### V5 Configuration Preset with V4 Options

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

This example shows how to extend the PostGraphile V5 Amber preset and incorporate V4 options using `makeV4Preset`. It includes database connection configuration.

```javascript
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
import { makeV4Preset } from "postgraphile/presets/v4";
// Use the 'pg' module to connect to the database
import { makePgService } from "postgraphile/adaptors/pg";

/** @type {GraphileConfig.Preset} */
const preset = {
  extends: [
    // The initial PostGraphile V5 preset
    PostGraphileAmberPreset,

    // Change the options and add/remove plugins based on your V4 configuration:
    makeV4Preset({
      /* PUT YOUR V4 OPTIONS HERE, e.g.: */
      simpleCollections: "both",
      jwtPgTypeIdentifier: '"b"."jwt_token"',
      appendPlugins: [
        /*...*/
      ],
    }),

    // Note some plugins are now "presets", e.g.
    // `@graphile/simplify-inflection`, those should be listed here instead of `appendPlugins`
  ],

  plugins: [
    /*
     * If you were using `pluginHook` before, the relevant plugins will need
     * listing here instead. You can also move the `appendPlugins` list here
     * for consistency if you like.
     */
  ],

  /*
   * PostgreSQL database configuration.
   *
   * If you're using the CLI you can skip this and use the `-c` and `-s`
   * options instead, but we advise configuring it here so all the modes of
   * running PostGraphile can share it.
   */
  pgServices: [
    makePgService({
      // Database connection string:
      connectionString: process.env.DATABASE_URL,
      // List of schemas to expose:
      schemas: ["app_public"],
      // Superuser connection string, only needed if you're using watch mode:
      // superuserConnectionString: process.env.SUPERUSER_DATABASE_URL,
    }),
  ],
};

export default preset;

```

--------------------------------

### Initialize Node.js Project

Source: https://postgraphile.org/postgraphile/5/usage-library

Initializes a new Node.js project using npm. This is a prerequisite step for setting up PostGraphile with Express in a single file.

```bash
mkdir postgraphile_express  
cd postgraphile_express  
npm init -y  

```

--------------------------------

### Install dependencies with pnpm for TypeScript

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs PostGraphile, Express, and related TypeScript development dependencies using pnpm.

```bash
pnpm add --legacy-peer-deps express postgraphile @graphile/simplify-inflection
pnpm add --save-dev typescript @tsconfig/node24 @tsconfig/node-ts @types/express @types/node
```

--------------------------------

### Install dependencies with Yarn for TypeScript

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs PostGraphile, Express, and related TypeScript development dependencies using Yarn.

```bash
yarn add --legacy-peer-deps express postgraphile @graphile/simplify-inflection
yarn add --dev typescript @tsconfig/node24 @tsconfig/node-ts @types/express @types/node
```

--------------------------------

### PostGraphile Configuration with Presets

Source: https://postgraphile.org/postgraphile/5/exporting-schema

This configuration example uses presets for PostGraphile, combining 'amber' and 'minify' presets. It's suitable for production exports in serverless environments where performance is critical.

```typescript
import { PostGraphileAmberPreset } from "postgraphile/presets/amber";
import { PgMinifySchemaPreset } from "postgraphile/presets/minify";

const preset: GraphileConfig.Preset = {
  extends: [PostGraphileAmberPreset, PgMinifySchemaPreset],
  /* ... */
};

export default preset;

```

--------------------------------

### GraphQL Query Test Helper Setup

Source: https://postgraphile.org/postgraphile/5/testing-jest

Initializes the testing context, including the PostGraphile instance, schema, and database pool. This should be called before running tests.

```typescript
import type { PostGraphileOptions } from "postgraphile";
import { postgraphile } from "postgraphile";
import { Pool } from "pg";

interface TestContext {
  pgl: any;
  schema: any;
  resolvedPreset: any;
  pgPool: Pool;
}

let ctx: TestContext | null = null;

export const setup = async (options: PostGraphileOptions = {}) => {
  const pgPool = new Pool({
    database: "graphile_test",
  });
  const pgl = postgraphile(pgPool, [], options);
  const resolvedPreset = await pgl.getResolvedPreset();
  const schema = pgl.getSchema();

  ctx = { pgl, schema, resolvedPreset, pgPool };
}; 
```

--------------------------------

### Install dependencies with npm for TypeScript

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs PostGraphile, Express, and related TypeScript development dependencies using npm.

```bash
npm install --legacy-peer-deps --save express postgraphile @graphile/simplify-inflection
npm install --save-dev typescript @tsconfig/node24 @tsconfig/node-ts @types/express @types/node
```

--------------------------------

### Create and Reference Objects in a Schema

Source: https://postgraphile.org/postgraphile/5/namespaces

Demonstrates how to create tables and functions within a specific schema and how to query them. Prepending the schema name to the object name is required.

```sql
create table app_public.users ( ... );  
create function app_public.best_user() ...;  
  
select * from app_public.users;  
select * from app_public.best_user();  
```

--------------------------------

### Install Dependencies with pnpm

Source: https://postgraphile.org/postgraphile/5/jwk-verification

Install the necessary packages for Express JWT verification and JWKS retrieval using pnpm.

```bash
pnpm add express express-jwt jwks-rsa  

```

--------------------------------

### Run PostGraphile with Configuration (bun)

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Runs PostGraphile using the configuration file, without needing to specify flags on the command line, using bun.

```bash
bun x postgraphile
```

--------------------------------

### Install Dependencies with Yarn

Source: https://postgraphile.org/postgraphile/5/jwk-verification

Install the necessary packages for Express JWT verification and JWKS retrieval using Yarn.

```bash
yarn add express express-jwt jwks-rsa  

```

--------------------------------

### Run PostGraphile with Configuration (npm)

Source: https://postgraphile.org/postgraphile/5/quick-start-guide

Runs PostGraphile using the configuration file, without needing to specify flags on the command line, using npm.

```bash
npx postgraphile
```

--------------------------------

### Install Docker Compose on Linux

Source: https://postgraphile.org/postgraphile/5/running-postgraphile-in-docker

Installs Docker Compose on Debian-based Linux distributions using the apt package manager.

```bash
sudo apt install docker-compose

```

--------------------------------

### Install PostGraphile and Express with Yarn

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs the required 'express' and 'postgraphile' packages using Yarn. This is an alternative to npm for dependency management.

```bash
yarn add express postgraphile  

```

--------------------------------

### Example JWT Structure

Source: https://postgraphile.org/postgraphile/5/postgresql-schema-design

An example of a JWT, which is a base64-encoded JSON object that has been cryptographically signed. The content is readable, but the signature ensures authenticity.

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoxLCJiIjoyLCJjIjozfQ.hxhGCCCmGV9nT1slief1WgEsOsfdnlVizNrODxfh1M8
```

--------------------------------

### Create Product Table

Source: https://postgraphile.org/postgraphile/5/extend-schema

Defines a 'product' table in the database with id, name, and price_in_us_cents columns.

```sql
create table product (
  id uuid primary key,
  name text not null,
  price_in_us_cents integer not null
);

```

--------------------------------

### V5 Grafast Context for pgSettings

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

This example demonstrates how to provide `pgSettings` in V5 by returning them from the `grafast.context` configuration, replacing the V4 `pgSettings` option.

```javascript
const preset = {
  //...
  grafast: {
    context(ctx) {
      // Other servers/transports add different details to `ctx`.
      const { req } = ctx.node ?? {};
      return {
        pgSettings: pgSettings(req);
      };
    },
  },
};

```

--------------------------------

### Install PostGraphile and Express with pnpm

Source: https://postgraphile.org/postgraphile/5/usage-library

Installs the 'express' and 'postgraphile' packages using pnpm. This command is used for projects managed with the pnpm package manager.

```bash
pnpm add express postgraphile  

```

--------------------------------

### Example: PostGraphile with Express

Source: https://postgraphile.org/postgraphile/5/usage-library

Demonstrates setting up a PostGraphile server within an Express application. It uses Grafserv for Express v4 and mounts the service into an HTTP server.

```javascript
import { createServer } from "node:http";  
import express from "express";  
import { grafserv } from "postgraphile/grafserv/express/v4";  
import { pgl } from "./pgl.js";  
  
const serv = pgl.createServ(grafserv);  
  
const app = express();  
const server = createServer(app);  
server.once("listening", () => {  
  server.on("error", (e) => void console.error(e));  
});  
serv.addTo(app, server).catch((e) => {  
  console.error(e);  
  process.exit(1);  
});  
server.listen(5678);  
  
console.log("Server listening at http://localhost:5678");  

```

--------------------------------

### Basic hookArgs Example with PostGraphile

Source: https://postgraphile.org/postgraphile/5/usage-schema

This example shows how to execute a GraphQL query using `hookArgs` for request context. It parses and validates the query before execution.

```typescript
import { postgraphile } from "postgraphile";  
import { parse, validate } from "postgraphile/graphql";  
import { execute, hookArgs, type ErrorBehavior } from "postgraphile/grafast";  
import preset from "./graphile.config.js";  
  
// Build a `pgl` instance, with helpers and schema based on our preset.  
const pgl = postgraphile(preset);  
  
/**  
 * Given a request context `requestContext`, GraphQL query text `source` and  
 * optionally variable values and operation name, execute the given GraphQL  
 * operation against our schema and return the result.  
 */  
export async function executeQuery(  
  requestContext: Partial<Grafast.RequestContext>,  
  source: string,  
  variableValues?: Record<string, unknown> | null,  
  operationName?: string,  
  onError?: ErrorBehavior,  
) {  
  // We might get a newer schema in "watch" mode  
  const { schema, resolvedPreset } = await pgl.getSchemaResult();  
  
  // Parse the GraphQL query text:  
  const document = parse(source);  
  
  // Validate the GraphQL document against the schema:  
  const errors = validate(schema, document);  
  if (errors.length > 0) {  
    return { errors };  
  }  
  
  // Prepare the execution arguments:  
  const args = await hookArgs({  
    schema,  
    document,  
    variableValues,  
    operationName,  
    onError,  
    resolvedPreset,  
    requestContext,  
  });  
  
  // Execute the request using Grafast:  
  return await execute(args);  
}  

```

--------------------------------

### Custom orderByAscDesc Example

Source: https://postgraphile.org/postgraphile/5/add-pg-table-order-by

Example demonstrating how to use orderByAscDesc to create a custom order by clause for movie ratings, handling nulls by placing them last.

```typescript
const customOrderBy = orderByAscDesc(
  "RATING",
  (queryBuilder) => {
    const sqlIdentifier = sql.identifier(Symbol("movie_reviews"));
    return sql`
      select avg(${sqlIdentifier}.rating)
      from app_public.movie_reviews as ${sqlIdentifier}
      where ${sqlIdentifier}.movie_id = ${queryBuilder.alias}.id
    `;
  },
  { nulls: "last" },
);

```

--------------------------------

### Delete User Mutation Example by Username

Source: https://postgraphile.org/postgraphile/5/crud-mutations

Example of deleting a user record using a unique identifier (`username`). It returns the ID of the deleted user.

```graphql
mutation {
  deleteUserByUsername(input: { username: "bilbo" }) {
    deletedUserId
  }
}
```

--------------------------------

### Configure Database Connection and Environment

Source: https://postgraphile.org/postgraphile/5/usage-library

Define database connection details and environment settings in a .env file. Ensure this file is ignored by git.

```dotenv
# Replace the contents of the square brackets with the details of your database  
DATABASE_URL=postgres://[username]:[password]@[host]:[port]/[database]  
GRAPHILE_ENV=development  
```

```bash
echo .env >> .gitignore  
```

--------------------------------

### Configure PostgreSQL Service with `makePgService`

Source: https://postgraphile.org/postgraphile/5/config/overview

Use `makePgService` to define your PostgreSQL service configuration. This is the recommended approach for setting up database connections, schemas, and pub/sub functionality.

```javascript
import { makePgService } from "postgraphile/adaptors/pg";

/** @type {GraphileConfig.Preset} */
const preset = {
  // ...
  pgServices: [
    makePgService({
      // Database connection string:
      connectionString: process.env.DATABASE_URL,

      // List of database schemas:
      schemas: ["app_public"],

      // Enable LISTEN/NOTIFY:
      pubsub: true,

      // Optional: additional pg.Pool configuration
      poolConfig: {
        max: 10,
        idleTimeoutMillis: 30000,
      },

      // Optional, only needed for `--watch` mode:
      superuserConnectionString: process.env.SUPERUSER_DATABASE_URL,

      // Optional: additional superuser pg.Pool configuration
      superuserPoolConfig: {
        max: 2,
      },
    }),
  ],
};

```

--------------------------------

### V4 Plugin Example: Add Query.four Field

Source: https://postgraphile.org/postgraphile/5/migrating-from-v4

Example of how a plugin to add a `Query.four` field would have been written in PostGraphile V4 using builder hooks.

```javascript
// Version 4 example; will not work with V5!
module.exports = (builder) => {
  builder.hook("GraphQLObjectType:fields", (fields, build, context) => {
    const {
      graphql: { GraphQLInt },
    } = build;
    const { Self } = context;
    if (Self.name !== "Query") return fields;
    return build.extend(
      fields,
      {
        four: {
          type: GraphQLInt,
          resolve() {
            return 4;
          },
        },
      },
      "Adding Query.four",
    );
  });
};

```

--------------------------------

### Run PostGraphile with Bun x

Source: https://postgraphile.org/postgraphile/5/usage-cli

Run the PostGraphile CLI using Bun's 'x' command, which executes packages without permanent installation.

```bash
bun x postgraphile -P postgraphile/presets/amber -e -c postgres:///mydb  

```

--------------------------------

### Install and List Inflectors with Yarn

Source: https://postgraphile.org/postgraphile/5/inflection

Install the 'graphile' development dependency and use the 'yarn dlx graphile inflection list' command to view all available inflectors and their documentation.

```bash
npm install --save-dev graphile  
yarn dlx graphile inflection list  

```
Tokens:
Raw