DOCSEARCHbyAlgolia
Submit Docs

Graphile Build

website·Indexed 35 days ago

https://build.graphile.org

A tool to automatically build GraphQL objects and fields through database introspection. It features a plugin system powered by graphile-config, allowing developers to register schema hooks, manage build objects, and extend GraphQL schemas. Documentation covers versions v4.x, v5, and next, including details on the SchemaBuilder, plugin presets, and the graphile-build-pg plugin collection for PostgreSQL.

Tokens
20.9K
Snippets
75
Records
138
Agent score
63%

What's inside Graphile Build

  1. Overview of graphile-build-pg

    graphile-build-pg is a collection of graphile-build plugins that extend a GraphQL schema with types and fields derived from PostgreSQL tables, views, functions, and other database resources. It leverages Graphile Engine's query look-ahead features to avoid the N+1 query problem, typically outperforming DataLoader-based solutions. While it is the foundation for PostGraphile, it is recommended to use PostGraphile directly unless low-level access to the library is required.

  2. Overview of graphile-build v4.x hooks

    Graphile-build uses a hook system to allow developers to customize the schema generation process. Hooks are triggered at specific lifecycle events, such as during the initial build setup, when creating GraphQL types, or when finalizing the schema. Attempting to use a hook name that is not supported will result in an error.

  3. Overview of Graphile Build

    Graphile Build is a toolkit designed to auto-generate flexible and extensible GraphQL APIs from arbitrary data sources. It uses a plugin system to add or remove feature classes and a behavior system for fine-grained control over entity features. It is designed to integrate with GraFast to produce schemas that can outperform traditional hand-rolled resolvers and DataLoader implementations. A primary example of a system built with this toolkit is PostGraphile, which uses the graphile-build-pg plugin collection to introspect PostgreSQL databases and automatically generate GraphQL objects and fields.

  4. Overview of graphile-build-pg

    graphile-build-pg is a collection of graphile-build plugins that automatically extend a GraphQL schema with types and fields derived from PostgreSQL tables, views, functions, and other database resources. It works by introspecting the database via pg-introspection and building a @dataplan/pg registry of codecs, resources, and relations. This registry is then used to generate GraphQL types, fields, and GraFast plan resolver functions. It serves as a core component of PostGraphile.

  5. Overview of Graphile Build

    Graphile Build is a toolkit designed to auto-generate flexible and extensible GraphQL APIs from arbitrary data sources. It uses a plugin system to add or remove feature classes and a behavior system for fine-grained control over entity features. It integrates with Grafast to provide performance that often exceeds hand-rolled schemas using traditional resolvers and DataLoaders. While the core library is data-source agnostic, plugins like graphile-build-pg allow it to introspect PostgreSQL databases to automatically build GraphQL objects and fields based on tables, columns, functions, and relations.

  6. Understand Graphile Build Context and Scope properties

    In Graphile Build, the Context object changes for each hook and provides system-defined details about the entity being processed. All contexts include two common properties:

    • type: A string indicating the current hook (e.g., build, init, GraphQLObjectType).
    • scope: A structured object explaining why the entity exists, used by plugins to determine if they should apply changes to a specific entity.

    Context names are derived from hook names (e.g., GraphQLObjectType becomes ContextObject). Contexts inherit from parent contexts, ensuring properties like Self and fieldWithHooks are available in deeper hooks.

  7. Build a GraphQL schema using graphile-build

    Graphile Engine allows you to generate extensible GraphQL schemas by combining plugins. You can use the buildSchema function to assemble a schema based on a set of plugins or presets. This architecture supports transforming the schema (e.g., automatically adding @deprecated directives based on comments) and integrating with various datastores via introspection plugins.
    import { buildSchema, defaultPreset } from "graphile-build";
import { printSchema } from "graphql";

const preset = {
  extends: [
    defaultPreset,
    // Add more presets here!
  ],
};

const schema = await buildSchema(preset);
console.log(printSchema(schema));

  8. Optimize GraphQL performance with look-ahead features

    Graphile Engine includes a look-ahead feature that allows resolvers to determine which fields are requested deeper in the query tree. This enables the engine to fetch all required data in fewer round-trips (often a single SQL query), effectively solving the N+1 problem and reducing query latency.

  9. Understand the graphile-build hook system

    Hooks in graphile-build act as wrappers around GraphQL object specifications. They allow plugins to manipulate the arguments passed to GraphQL object constructors before the objects are actually instantiated.

    Key characteristics:

    • Synchronous: Every hook callback must synchronously return either the original specification or a derivative of it.
    • Mutation: For performance, mutating the input object is preferred over returning a new one.
    • Ordering: Hooks run in the order they were registered. Plugin authors can use graphile-config to define before or after relationships to control execution order.
    // Conceptual equivalent of how hooks wrap constructors:
const MyType = new GraphQLObjectType(hook3(hook2(hook1(spec))));

  10. Understand graphile-build-pg and its role in GraphQL schema generation

    graphile-build-pg is a collection of graphile-build plugins designed to extend a GraphQL schema with types and fields derived from PostgreSQL database resources (tables, views, and functions).

    It operates by:

    1. Introspecting the database using pg-introspection.
    2. Building a @dataplan/pg registry consisting of codecs, resources, and relations.
    3. Using plugins to inspect this registry to create GraphQL types, fields, and GraFast plan resolver functions.

    This package is a core component of PostGraphile. Users can either rely on automatic database introspection or manually build the registry for full control over the GraphQL API.

  11. Understand the graphile-build hook system

    The graphile-build hook system allows plugins to manipulate the specifications passed to GraphQL object constructors before the objects are instantiated. Hooks act as wrappers around the original object specification.

    Key characteristics:

    • Synchronous Execution: Every hook callback must synchronously return a value (either the original specification or a derivative).
    • Performance: Mutating the input object is preferred over returning new objects for performance reasons.
    • Execution Order: Hooks run in the order they were registered. Plugin authors can use graphile-config to define before/after relationships to control this order.

  12. Understand the Graphile Build Context object

    The Context object is passed to every hook and provides metadata about the entity currently being processed. Unlike the Build object, which is constant across a build, the Context object changes depending on the hook. All context objects include:

    • type: A string identifying the current hook (e.g., build, init, GraphQLObjectType).
    • scope: A structured object explaining why the entity exists, used by plugins to determine if they should apply changes.