Graphile's Crystal is a TypeScript monorepo of MIT-licensed GraphQL tooling for the Node.js and PostgreSQL ecosystems, aimed at developers who want an auto-generated, high-performance GraphQL API over a PostgreSQL database or a faster execution engine for a GraphQL.js schema they already own.

What it is

Crystal is the repository that houses the Graphile packages relating to GraphQL, including packages that relate to those packages in turn. The two headline projects are Grafast, a planning and execution engine for GraphQL, and PostGraphile, a tool for building a GraphQL API backed primarily by a PostgreSQL database. Alongside them sit a set of supporting libraries — @dataplan/pg, @dataplan/json, graphile-export, graphile-config, graphile-build, graphile-build-pg, pg-sql2, pg-introspection, @graphile/lru, eslint-plugin-graphile-export and jest-serializer-graphql-schema — a fair few of which can be used independently of the headline projects. The project is written in TypeScript, licensed under MIT, and documented at graphile.org.

The concrete problem it solves is the cost of wiring GraphQL to a database by hand. PostGraphile takes a PostgreSQL database and treats it as the source of truth for an automatically generated GraphQL API, which can still be customised and extended significantly, so a team does not have to hand-write a resolver layer that mirrors its schema. Grafast attacks the same cost from the execution side: it is a drop-in replacement for the execute method from GraphQL.js, and by moving from traditional resolvers to Grafast "plan resolvers" it uses the declarative nature of a GraphQL request to execute business logic more efficiently, reducing server load. Where a generated API later needs to stand on its own, graphile-export can export an in-memory, dynamically constructed GraphQL schema to raw JavaScript source that can be imported and executed.

Key capabilities

• Grafast provides a standalone planning and execution engine that drops into the execute method of GraphQL.js, with plan resolvers replacing traditional resolvers.
• PostGraphile generates a well-structured GraphQL API from a PostgreSQL database, and graphile-export can eject that in-memory schema to raw JavaScript source for self-managed operation.
• graphile-build constructs a GraphQL.js schema from plugins, and graphile-build-pg adds plugins that understand @dataplan/pg services and generate types, relations and mutations for database resources.
• @dataplan/pg supplies plan classes for interacting with PostgreSQL, and @dataplan/json supplies plan classes for encoding and decoding JSON.
• pg-sql2 builds highly dynamic, SQL-injection-proof PostgreSQL queries using tagged template literals, while pg-introspection is a strongly typed PostgreSQL introspection library generated from the PostgreSQL documentation.
• graphile-config handles plugins, presets and configuration files as a universal configuration layer for Graphile software, with eslint-plugin-graphile-export and jest-serializer-graphql-schema supporting code and snapshot workflows.
• @graphile/lru is an obsessively performant least-recently-used cache with a deliberately tiny feature set; the README states most users want lru-cache instead.

Who uses it and how

• Teams that already have a PostgreSQL database and want to stand up a GraphQL API from it with low effort, using the database as the source of truth and customising the generated schema afterwards.
• Developers building their own GraphQL schemas who adopt Grafast as a drop-in replacement for GraphQL.js execute to gain efficiency without large extra effort.
• Projects that want a generated API only as a starting point and then take ownership of it by running graphile-export to produce importable JavaScript source.
• Applications deployed as Node.js HTTP services, with Express and Koa (including Koa 2) listed among the project topics.
• Codebases that want shared plugins, presets and configuration files across Graphile-based tools through graphile-config.

Getting started

The repository publishes the Graphile packages directly, with grafast, postgraphile and graphile-config among the entry points and full documentation hosted at graphile.org; PostGraphile V4 remains available on the legacy branch. The README excerpt provided here does not include install, run or deploy commands, so those must be taken from the project documentation.

How it compares

Within the GraphQL.js ecosystem, Grafast positions itself as a drop-in replacement for the built-in execute method rather than a separate runtime, which lets existing schemas adopt it incrementally. For caching, the README does not claim @graphile/lru as a general-purpose choice and explicitly points users towards lru-cache for typical needs.

When to use it — and when not to

The main value in PostGraphile depends on operating a PostgreSQL database, so a self-hoster must be prepared to run and manage that database, and there is no hosted or container-based deployment option described in the facts. Teams that want a fully managed GraphQL service, or that do not use PostgreSQL, will not get the core benefit, and @graphile/lru should be avoided as a general LRU cache because its feature set is knowingly narrow. The repository is a monorepo whose packages differ in scope and maturity, PostGraphile V4 lives on a separate legacy branch rather than in the main line, and the project carries 169 open issues, so adopters should expect to track version splits and read per-package documentation rather than assume uniform behaviour.