Graphile Crystal: Grafast and PostGraphile in One Monorepo

What Graphile Crystal Actually Contains

Crystal is not a product. It is a monorepo that houses the Graphile packages related to GraphQL and to each other. The README names two headline projects: Grafast, described as a planning and execution engine for GraphQL.js, and PostGraphile, described as a way to build a GraphQL API backed primarily by a PostgreSQL database. Around those sit smaller packages that can be used on their own.

The README gives a rough breakdown. @dataplan/pg holds plan classes for interacting with PostgreSQL, and @dataplan/json handles encoding and decoding JSON. graphile-export can export an in-memory dynamically constructed GraphQL schema to raw JavaScript source. graphile-config handles plugins, presets and configuration files for Graphile software. graphile-build builds a GraphQL.js schema from plugins, and graphile-build-pg adds plugins that understand @dataplan/pg services so types, relations and mutations can be generated from database resources. pg-sql2 builds SQL-injection-proof PostgreSQL queries from tagged template literals, and pg-introspection is a strongly typed introspection library generated from the PostgreSQL documentation.

One entry in that list is worth reading twice. @graphile/lru is described as an obsessively performant least-recently-used cache with a ridiculously tiny feature set, and the README then tells you that you almost certainly want @isaacs' lru-cache instead. A project that tells you not to use its own cache is being honest about scope, and that honesty is a reasonable signal for how the rest of the documentation reads.

The repository is MIT licensed and the default branch is main. PostGraphile V4 lives on a separate legacy branch, so anyone arriving with V4 experience should expect a different codebase here.

How Grafast Replaces Resolvers With a Plan

The mechanism Grafast introduces is the plan resolver. The README says you can use Grafast as a drop-in replacement for the execute method from GraphQL.js, and that by moving from traditional resolvers to plan resolvers you can use the declarative nature of a GraphQL request to execute business logic more efficiently.

The distinction matters because a traditional GraphQL server resolves each field independently and often pays for the same database round trip several times within one request. A plan resolver instead describes what a field needs, and the engine builds one plan for the whole operation before anything executes. That is the architectural claim: the request shape is known up front, so the work can be arranged around it rather than discovered field by field.

Grafast does not talk to PostgreSQL by itself. @dataplan/pg supplies the plan classes that interact with the database, which is why the package sits under grafast in the repository layout rather than under postgraphile. If you adopt Grafast for a hand-written schema, you are choosing both the execution engine and the data-layer plan classes that go with it.

The README does not document what happens to existing resolvers during a migration, or whether a schema can mix plan resolvers and traditional resolvers in the same operation. That is the first thing to establish before planning a conversion.

Installing PostGraphile and Getting a First Query

The README does not reproduce install commands, so the reliable source is the PostGraphile package directory and the project site at graphile.org. What the README does confirm is the shape of the project: PostGraphile pulls most of the other packages together and generates a GraphQL API from a PostgreSQL database used as the source of truth.

The repository package.json shows how the maintainers work inside the monorepo. The w script is a shorthand for yarn workspace, and the postgraphile script changes into the package directory before running something there:

{
  "scripts": {
    "w": "yarn workspace",
    "postgraphile": "cd postgraphile/postgraphile && node di"
  }
}

That second script is truncated in the file listing, so treat it as a pointer to the package directory rather than a command to copy. The build pipeline is more informative. build-init runs yarn, builds ruru-components and ruru, then runs tsc -b, and build then runs build-package across every workspace in topological order, excluding the root, ruru and ruru-components, which were already handled:

# from the repository root
yarn build-init
yarn build

If you are consuming published packages rather than working on the monorepo itself, the relevant entry points are the PostGraphile package and the Grafast package, both linked from the README to their directories. The homepage at graphile.org is where the project points for documentation. Expect to configure a PostgreSQL connection and let PostGraphile introspect the schema; the README does not give the connection flag names, so take those from the package documentation rather than guessing.

Where PostGraphile Stops Being the Right Tool

PostGraphile is built around PostgreSQL as the source of truth. That is a constraint, not a preference. If your data lives in MySQL, MongoDB, a set of REST services, or a mix of sources, the automatic generation that makes PostGraphile attractive does not apply, and you are left with graphile-build and graphile-build-pg as lower-level pieces you would assemble yourself.

There is a second boundary in how the schema is produced. Because the GraphQL types, relations and mutations are generated from database resources, the shape of your API follows the shape of your database. Teams with an existing public GraphQL contract, or with a database schema that was never designed to be exposed, will spend their time on customisation rather than on generation. The README acknowledges this by describing customisability and extensibility as main focuses, which is another way of saying the generated result is a starting point.

The README also notes that graphile-export can, under the right circumstances, export a dynamically constructed schema to JavaScript source so you can manage the API yourself. The phrase under the right circumstances is doing real work in that sentence, and the README does not enumerate the conditions. If your plan is to generate once and then take ownership of the schema, that is the sentence to investigate first.

Finally, the monorepo is large. It contains packages that are not GraphQL-specific, and the README says so directly. Depending on Crystal as a whole means depending on a repository whose scope is deliberately wider than any single application needs.

Grafast Against a Conventional GraphQL.js Server

The obvious alternative to Grafast is the default execution path in GraphQL.js itself, which is what Grafast is designed to replace. The difference is where the intelligence sits. A conventional server resolves fields as they are reached, and performance work goes into batching and caching at the resolver level, often with a dataloader pattern. Grafast moves that decision earlier: plan resolvers describe the work, and the engine arranges it before execution begins.

That trade is real in both directions. The conventional approach requires no new mental model, works with the resolver code most GraphQL developers already write, and has a large body of tutorials behind it. Grafast asks you to express data access as plans, which is a different skill, and the README's own framing is that you should use it if you are building your own GraphQL schemas and want performance without much extra effort. The effort is not zero; it is relocated.

For the PostGraphile side, the alternative is writing the GraphQL layer by hand over the same PostgreSQL database. You keep full control of the schema and lose the generation step entirely. The README positions PostGraphile as low-effort and performance-focused, which is the honest summary of what you give up when you go manual: the automatic best-practices and the generated relations.

Note also that graphile-build is a general schema-building system, not only a PostGraphile component. The README says it is useful for hand-rolled schemas with modular concerns such as connections and naming. So the parts of Crystal can be adopted without adopting the whole.

Maintenance, Versions and the MIT Licence

The last push to the repository was on 2026-09-20, and the repository is not archived. Recent releases include [email protected], [email protected] and [email protected], all published on 2026-09-04.

Upgrade cost is the part to think about carefully. Crystal is a monorepo with independent packages, and the release list shows those packages versioned separately. A change to a shared utility can surface in a package you depend on without that package's version moving in a way that signals it. The repository uses changesets, visible as the .changeset directory and the changeset-version and changeset-publish scripts, which is the mechanism the maintainers use to record and publish version bumps. When you upgrade, read the changelog for the package you actually installed rather than the repository as a whole.

The licence is MIT. That is permissive and permits commercial use, modification and redistribution, subject to the terms of the licence file. This is not legal advice; if you are embedding these packages in a product, read LICENSE.md in the repository and take your own advice on attribution and notice requirements.

The README also asks individuals and businesses that use the software to support its maintenance through sponsorship, and lists a sponsor. Sponsorship is not a licence condition, but it is the stated model behind the project's ongoing development, which is worth knowing if you are planning a long-lived dependency.

Editorial conclusion

Adopt Graphile Crystal if you run PostgreSQL and want a GraphQL API generated from that schema, or if you are building your own GraphQL.js schema and want to replace the execute method with Grafast plan resolvers. Skip it if your data lives outside PostgreSQL, or if you need a stable public API surface across major versions while the project is still publishing 5.x PostGraphile releases. Before committing, verify that the GraphQL schema PostGraphile generates from your database matches what your clients expect, and check the changelog for the specific package you depend on rather than the monorepo as a whole.

Frequently asked questions

Official sources

1. graphile/crystal on GitHub
2. License: MIT
3. Project website
4. README
5. Releases