Guide · Open source
How to use crystal: Graphile's monorepo, Grafast and PostGraphile
Updated · written with AI from the project's own documentation and checked against our catalogue data
Crystal is Graphile's monorepo, a single repository that holds many related open-source packages for GraphQL and PostgreSQL. Its two headline projects are Grafast, a planning and execution engine for GraphQL.js, and PostGraphile, which builds a GraphQL API from a PostgreSQL database. This guide explains what is in the repository, how to get a copy, and how to choose the right package so you can start working with it.
Graphilegraphile/crystal · ★ 12.9k · MIT Install options & downloads Quick start
- 1Check prerequisites. Install Node.js and PostgreSQL, the two prerequisites listed in the README.
- 2Clone the repository. Run git clone https://github.com/graphile/crystal in your terminal to get a local copy.
- 3Pick your package. Choose PostGraphile for an auto-generated API from PostgreSQL, Grafast for a custom GraphQL schema, or a standalone library such as pg-sql2 or pg-introspection.
- 4Read the package docs. Open the folder for your chosen package in the repository, as the README links each package to its directory.
- 5Build your schema or API. Follow the package documentation to connect your database or define your plan resolvers.
What is in the Crystal monorepo?
The repository houses many of the Graphile packages that relate to GraphQL. The two headline projects are Grafast and PostGraphile, but many other packages can be used independently of them.
- Grafast: a planning and execution engine for GraphQL.js, usable as a drop-in replacement for the execute method.
- PostGraphile: builds a GraphQL API backed primarily by a PostgreSQL database.
- pg-sql2: a library for building dynamic, SQL-injection-proof PostgreSQL queries using tagged template literals.
- pg-introspection: a strongly typed introspection library for PostgreSQL.
- graphile-export, graphile-config and graphile-build: supporting packages for schema export, configuration and schema building.
Get a copy of the repository
The README's install step is to clone the repository. Run the command below in a terminal. The README lists Node.js and PostgreSQL as prerequisites, so have both available before you work with the packages.
If you need the older PostGraphile V4, the README points to a separate legacy branch of the same repository rather than the main code.
git clone https://github.com/graphile/crystalChoose the right package for your job
Use PostGraphile if you have a PostgreSQL database and want it to be the source of truth for an auto-generated GraphQL API that you can still change significantly. The README also notes that graphile-export can turn a PostGraphile setup into a starting point for an API you manage yourself.
Use Grafast if you are building your own GraphQL schemas and want good performance without much extra effort. Grafast works by moving from traditional resolvers to plan resolvers, which lets it execute your business logic more efficiently.
Use individual libraries if you only need one piece. pg-sql2 suits building SQL queries and pg-introspection suits reading database structure, and both can be used on their own.
Build SQL queries with pg-sql2
pg-sql2 lets you write PostgreSQL queries with tagged template literals while keeping them safe from SQL injection, as described in the README. It is useful when your queries are highly dynamic and you still want the database layer to be robust.
The README does not include a code sample for pg-sql2, so check that package's own documentation for syntax.
Understand what the caching library does
The monorepo includes @graphile/lru, a least-recently-used cache. The README describes it as very fast with a deliberately small feature set, and recommends lru-cache by @isaacs for most users instead.
What people use it for
- Generating a GraphQL API from an existing PostgreSQL database with PostGraphile.
- Building a custom GraphQL schema with Grafast plan resolvers to reduce server load.
- Writing dynamic, injection-safe SQL queries with pg-sql2.
- Reading PostgreSQL database structure with pg-introspection for tooling.
- Exporting a dynamically built GraphQL schema to JavaScript source with graphile-export.
Frequently asked questions
Is crystal free to use?
The repository is licensed under MIT. The README also asks users who rely on the software to support its maintenance through sponsorship, but sponsorship is requested rather than required by the licence.
What do I need to install crystal?
The README lists Node.js and PostgreSQL as prerequisites. The install step given is to clone the repository with git clone https://github.com/graphile/crystal.
Can I use PostGraphile without PostgreSQL?
No. PostGraphile is designed around PostgreSQL, and the README describes it as backed primarily by a PostgreSQL database. People who do not use PostgreSQL should look at other tools.
Where is PostGraphile V4?
PostGraphile V4 lives on the legacy branch of the repository, not the main branch. The README links to that branch directly.
What are alternatives to PostGraphile?
The source lists Hasura, PostGraphile V4, Apollo Server and graphql-js as comparable projects. Hasura is another option for generating an API from a database.
Do I need to know GraphQL to use crystal?
Yes, the README assumes familiarity with Node.js and GraphQL. Beginners without experience in either will find it hard to follow.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Crystal suits developers who already use Node.js and PostgreSQL and want an auto-generated GraphQL API they can customise, or who want individual libraries for SQL building and database introspection. People without PostgreSQL, people who need PostGraphile V4, or beginners new to GraphQL and Node.js should pick another tool, such as Hasura or Apollo Server.
Install options & downloads