Registry / database / graphile-build-pg

graphile-build-pg

JSON →
library5.0.1jsnpmunverified

`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-pg
INSTALL
IMPORT
SIG · GRAPHILE-BUILD-PG
G
graphile-build-pg
databasejavascriptv5.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sql
import { sql } from 'graphile-build-pg';
const { sql } = require('graphile-build-pg');
The `sql` tag from `pg-sql2` is re-exported by `graphile-build-pg` (since v5.0.1) and is crucial for writing type-safe SQL queries within custom plugins or resolvers. It's often consumed via `import { sql } from 'postgraphile/graphile-build-pg';` when using PostGraphile's unified exports.
SQL
import { SQL } from 'graphile-build-pg';
import { SQL } from 'pg-sql2'; // Direct import of underlying dependency is discouraged
The `SQL` type from `pg-sql2` is re-exported by `graphile-build-pg` (since v5.0.1) for type-checking SQL fragments. Best practice is to import it through `graphile-build-pg` or `postgraphile/graphile-build-pg`.
defaultPlugins
import { defaultPlugins } from 'graphile-build-pg';
import { plugins } from 'graphile-build-pg';
This export provides the core array of PostgreSQL-specific Graphile Build plugins. It's used when manually assembling a `graphile-config` preset for a `graphile-build` schema, rather than relying on `postgraphile`'s integrated presets.

Demonstrates how to build a GraphQL schema from a PostgreSQL database using `graphile-build-pg`'s capabilities via a `postgraphile` preset and `makeSchema`.

import { makeSchema } from 'postgraphile'; import { defaultPreset } from 'postgraphile'; import { makePgSources } from '@dataplan/pg'; import { printSchema } from 'graphql'; // Ensure you have a PostgreSQL database running and DATABASE_URL set. // Example: export DATABASE_URL="postgres://user:password@localhost:5432/mydb" const DATABASE_URL = process.env.DATABASE_URL ?? 'postgres://postgres:password@localhost:5432/postgres'; async function buildPostgresSchema() { if (!DATABASE_URL) { throw new Error('DATABASE_URL environment variable is not set.'); } // makePgSources defines how to connect to your PostgreSQL database // and what schemas to introspect. const pgSources = [await makePgSources({ connection: DATABASE_URL, schemas: ['public'], })]; // The `defaultPreset` from `postgraphile` already includes the // `graphile-build-pg` plugins. We add our database sources to it. const preset = { ...defaultPreset, extends: [ ...(defaultPreset.extends || []), { // Add the PostgreSQL sources to the preset plugins: [], // No extra plugins from this block needed schema: { pgSources, }, }, ], }; // Build the GraphQL schema using the configured preset. const { schema } = await makeSchema(preset); console.log('Successfully built GraphQL schema from PostgreSQL database:\n'); console.log(printSchema(schema)); } buildPostgresSchema().catch(console.error);
Debug
Known issues
breakingGraphile V5 (Crystal) represents a complete rewrite of the PostGraphile and Graphile Build ecosystem. It replaces the V4 'lookahead' engine with 'Grafast' for query planning and introduces a new unified plugin and configuration system via `graphile-config`. This means V4 plugins, `SchemaBuilder` APIs, and configuration options are largely incompatible.
fix
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.
affects: >=5.0.0
breakingThe minimum Node.js version requirement for `graphile-build-pg` and the entire Graphile V5 ecosystem has been raised to Node.js `>=22`.
fix
Upgrade your Node.js runtime environment to version 22 or higher to ensure compatibility and leverage modern JavaScript features.
affects: >=5.0.0
gotchaMany core Graphile packages, including `graphile-build-pg`, are often re-exported directly from the `postgraphile` package itself (e.g., `import { sql } from 'postgraphile/graphile-build-pg';`). Directly importing from `graphile-build-pg` might lead to module resolution issues or unexpected behavior if not consistently applied within a PostGraphile V5 project.
fix
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.
affects: >=5.0.0
gotchaWhile `graphile-build-pg` automatically generates an efficient schema using `Grafast`, bypassing `Grafast`'s planning capabilities with hand-written GraphQL resolvers can reintroduce N+1 query problems, negating the performance benefits.
fix
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.
affects: >=5.0.0
Errors
Common errors & fixes
Cannot find module 'graphile-build-pg' or its corresponding type declarations.
Attempting to import `graphile-build-pg` directly when it is expected to be consumed via `postgraphile`'s re-exports, or a CJS/ESM module mismatch.
fix
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.
Error: `DATABASE_URL` environment variable is not set.
The application attempts to connect to a PostgreSQL database using an environment variable that is missing or empty.
fix
Set the `DATABASE_URL` environment variable, for example: `export DATABASE_URL="postgres://user:password@localhost:5432/mydb"` before running your application.
Error: `makePgSources` must be called with an object `pgConfig` or a function `getPgConfig`
Incorrect configuration passed to `makePgSources`, a core function for defining PostgreSQL data sources for `graphile-build-pg`.
fix
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'] })`.
Upgrade
Version history
5.0.1latest on npm
Audit
Dependencies
@dataplan/pgrequiredCore library for data planning and PostgreSQL interaction within the Grafast ecosystem.
grafastrequiredThe declarative, strongly-typed GraphQL query planning and execution engine that powers the performance optimizations.
graphile-buildrequiredThe foundational plugin system for building GraphQL schemas, which `graphile-build-pg` extends.
graphile-configrequiredThe unified configuration system used across the Graphile v5 suite for managing plugins and presets.
graphqlrequiredThe reference implementation of GraphQL.js, essential for defining the schema.
pgrequiredThe official PostgreSQL client for Node.js, used for database interaction.
pg-sql2requiredA type-safe SQL query builder used for constructing optimized database queries within the plugins.
tamedevilrequiredA utility package used within the Graphile ecosystem.
Agent activity
4 hits · last 30 days
node
4
Resources
graphile-build-pg — npm install graphile-build-pg · libregistry