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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
extendSchema
✓ import { extendSchema } from 'graphile-utils';
✗ const { extendSchema } = require('graphile-utils');
Graphile v5 and its utilities are primarily ESM-first. While some CJS compatibility exists, direct ESM imports are preferred and safer.
gql
✓ import { gql } from 'graphile-utils';
✗ import gql from 'graphql-tag';
The `gql` export from `graphile-utils` is distinct from `graphql-tag` and includes advanced interpolation features like `embed` for dynamic schema generation within Graphile plugins.
changeNullability
✓ import { changeNullability } from 'graphile-utils';
✗ const changeNullability = require('graphile-utils').changeNullability;
Used as a plugin to modify field nullability; direct ESM import is standard.
This quickstart demonstrates how to create a custom Graphile plugin using `extendSchema` to add a new `Random` type and field to the `Query` type, providing random float and integer generation.
import { extendSchema } from 'graphile-utils';
import type { GraphileConfig } from 'graphile-config';
const MyRandomPlugin: GraphileConfig.Plugin = extendSchema((build) => {
const {
grafast: { constant, lambda },
} = build;
return {
typeDefs: /* GraphQL */ `
type Random {
float: Float!
number(min: Int!, max: Int!): Int!
}
extend type Query {
random: Random
}
`,
objects: {
Query: {
plans: {
random() {
return constant({});
},
},
},
Random: {
plans: {
float() {
return lambda(null, () => Math.random());
},
number(_parent, { $min, $max }) {
return lambda(
[$min, $max],
([min, max]) => min + Math.floor(Math.random() * (max - min + 1)),
);
},
},
},
},
};
});
// To use this plugin, you would typically add it to your GraphileConfig:
// const config: GraphileConfig.ResolvedPreset = {
// extends: [require('postgraphile/presets/v4')],
// plugins: [MyRandomPlugin],
// };
// export default config;
console.log('MyRandomPlugin defined successfully, ready for GraphileConfig.');
Debug
Known issues
breaking`graphile-utils` is part of the Graphile v5 ecosystem, which mandates Node.js version 22 or higher. Deployments on older Node.js versions will fail.fixUpgrade your Node.js environment to version 22 or newer to ensure compatibility with Graphile v5 packages.
affects: >=5.0.0
breakingMigration from Graphile v4 to v5 (Crystal) involves significant architectural changes. Plugins built with v4 `graphile-utils` will require substantial refactoring due to changes in the build object, plan system (Grafast), and configuration structure.fixConsult the official Graphile v5 migration guides and documentation. Specifically, review changes to the `build` object, `grafast` integration, and plugin API.
affects: >=5.0.0
gotchaThe `gql` tagged template literal provided by `graphile-utils` is a powerful, custom implementation distinct from `graphql-tag`. It supports advanced features like dynamic field naming and `embed` for injecting raw values, which means it will not behave identically to `graphql-tag`.fixFamiliarize yourself with the `graphile-utils` `gql` documentation. Do not assume `graphql-tag` patterns will work without modification, especially for dynamic schema generation.
affects: >=5.0.0
breakingEarly release candidates of Graphile v5 removed or changed access paths for certain `pg-sql2` constants like `sql.TRUE`, `sql.FALSE`, and `sql.NULL`. While `graphile-utils@5.0.1` and `pg-sql2@5.0.1` have restored these, older v5 RCs might lack them.fixEnsure you are using `graphile-utils@5.0.1` (or higher) and `pg-sql2@5.0.1` (or higher) to access these specific SQL constants. If on an older RC, update your package versions.
affects: >=5.0.0-rc.0 <5.0.1
breakingFor backward compatibility with PostGraphile v4 presets in v5, `build.pgSql` was re-added as an alias for `build.sql`. This implies that `build.sql` is the canonical reference in v5, and reliance on `build.pgSql` directly may be deprecated in future versions or only exist for specific presets.fixPrefer using `build.sql` directly for SQL query building within your plugins to ensure future compatibility and align with the v5 conventions.
affects: >=5.0.0
Errors
Common errors & fixes
Error: Cannot find module '@dataplan/pg' or its corresponding type declarations.
A peer dependency of `graphile-utils` is missing from your project's `node_modules`.
fixInstall all peer dependencies listed in `graphile-utils`'s `package.json`, e.g., `npm install @dataplan/pg grafast graphile-build graphile-build-pg graphile-config graphql tamedevil`.
TypeError: extendSchema is not a function
Attempting to use `extendSchema` with CommonJS `require()` syntax in an ESM-only context, or incorrect named import.
fixEnsure your project is configured for ESM and use `import { extendSchema } from 'graphile-utils';`. If using CommonJS, verify your environment supports it or adjust imports accordingly, though ESM is preferred for Graphile v5. Error: Invalid 'gql' interpolation: expected a GraphQL AST node or a string, received [object Object]
Incorrectly interpolating values into the `gql` tagged template literal from `graphile-utils`, especially when expecting behavior similar to `graphql-tag`.
fixWhen interpolating complex objects or non-string values into `gql`, use the `embed` helper provided by `graphile-utils` (e.g., `gql`...${embed(someValue)}...). For dynamic field names or types, ensure correct string interpolation. Error: The plugin passed to processSchema must be a function that accepts 'schema' as an argument.
`processSchema` was not correctly implemented as a plugin or its argument signature is incorrect.
fixEnsure your `processSchema` implementation adheres to the expected plugin signature, accepting the `schema` object as its first argument, as shown in the Graphile documentation.
Audit
Dependencies
@dataplan/pgrequiredCore data planning layer for PostgreSQL, essential for database interactions within Graphile v5 plugins.
grafastrequiredThe Graphile 'fast' execution engine, providing core GraphQL execution capabilities for v5.
graphile-buildrequiredThe foundational schema building toolkit that graphile-utils plugins extend and interact with.
graphile-build-pgrequiredPostgreSQL-specific build extensions for graphile-build, used when building a schema from a PostgreSQL database.
graphile-configrequiredConfiguration system for the Graphile v5 ecosystem, defining how plugins are loaded and applied.
graphqlrequiredThe primary GraphQL.js library, providing core GraphQL types and utilities.
tamedevilrequiredA utility for safely evaluating JavaScript code strings, used internally by some Graphile components.