`graphile-build-pg` is a crucial component within the Graphile ecosystem, providing a collection of plugins for `graphile-build` that enable the automatic generation of a GraphQL schema directly from a PostgreSQL database. It achieves this by introspecting the database using `pg-introspection` and constructing a `@dataplan/pg` registry. This registry then informs the creation of GraphQL types, fields, and high-performance `grafast` plan resolver functions, ensuring optimal data fetching. The current stable version is 5.0.1, part of the larger Graphile Crystal (v5) release. This package is a cornerstone of PostGraphile v5, offering significant performance advantages over traditional `DataLoader`-based GraphQL solutions by virtually eliminating the N+1 query problem through `grafast`'s advanced query planning. It is designed for modern Node.js environments, requiring `Node.js >=22`.
npm install graphile-build-pgVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to build a GraphQL schema from a PostgreSQL database using `graphile-build-pg`'s capabilities via a `postgraphile` preset and `makeSchema`.
Refer to the PostGraphile V5 migration guide. All custom plugins and configurations need to be rewritten to conform to the new `graphile-config` plugin object structure and `Grafast`'s plan-based resolvers. The `@behavior` system replaces many `@smartTags` from V4.
Upgrade your Node.js runtime environment to version 22 or higher to ensure compatibility and leverage modern JavaScript features.
Prefer importing core Graphile modules via `postgraphile/sub-path` exports (e.g., `postgraphile/graphile-build-pg`) if your project uses PostGraphile directly. Only import from `graphile-build-pg` directly if building a custom `graphile-build` schema without the full `postgraphile` stack.
Ensure all data fetching within your GraphQL schema leverages `Grafast` steps and data plans (`@dataplan/pg`) where possible. For custom logic, integrate with existing `Grafast` steps or define new ones rather than using traditional resolver patterns.
If using PostGraphile, try `import { /* ... */ } from 'postgraphile/graphile-build-pg';`. Ensure your project is configured for ESM (`"type": "module"` in `package.json`) for Node.js >=22. If using CJS in an older Node.js, ensure correct `require()` syntax and package compatibility.Set the `DATABASE_URL` environment variable, for example: `export DATABASE_URL="postgres://user:password@localhost:5432/mydb"` before running your application.
Ensure `makePgSources` is called with an object containing at least `connection` and `schemas` properties, as shown in the quickstart, or a function that returns such an object. Example: `await makePgSources({ connection: process.env.DATABASE_URL, schemas: ['public'] })`.