Graphile Crystal

Graphile Build is a toolkit designed for auto-generating flexible and extensible GraphQL APIs from arbitrary data sources. It uses a plugin-based architecture to allow for easy addition or removal of features, and a behavior system that provides fine-grained control over which features are enabled for specific entities.

Key characteristics include:

• Extensibility: A plugin system allows users to write custom or community extensions.
• Performance: Integration with Grafast allows generated schemas to potentially outperform hand-rolled schemas using traditional resolvers and DataLoader.
• Dynamic Updates: Plugins can trigger rebuild events when underlying data structures change, allowing the GraphQL schema to be updated without restarting the server.

A primary example of a system built with this toolkit is PostGraphile, which uses it to build GraphQL APIs from PostgreSQL databases.

Graphile Export allows you to export a GraphQL schema (or other code) as executable JavaScript code. It is designed for schemas that are typically generated in-memory via a framework.

By exporting the schema as code, you move intensive schema-building processes—such as introspection, looping, computation, and transformation—from startup time to build time. At runtime, you simply execute the final code without needing the underlying logic that shaped it.

Key Benefits

• Faster startup time: The schema is ready to run without re-computation.
• Reduced thundering herd: Prevents mass server restarts from overwhelming external data sources during schema generation.
• Lower resource usage: Production environments do not need to load or execute the code used to compute the schema, reducing CPU and memory overhead.
• Fewer runtime dependencies: Build-time systems can be omitted from the production bundle.
• Improved serverless performance: Enables much faster cold starts in environments like AWS Lambda.

Compatibility and Usage

• Tooling Agnostic: It is not limited to Graphile-produced software (like PostGraphile, Graphile Build, or Grafast). It works with any JavaScript-based GraphQL schema that is compatible with the export/import requirements.
• PostGraphile Users: While Graphile Export is tooling-agnostic, PostGraphile users should also consult the official PostGraphile "Exporting your schema" documentation for specific instructions and warnings.

Graphile* is a collection of utility modules developed for the Graphile suite of open source developer tools. These utilities are designed to be used in various projects to handle common tasks such as configuration, schema exporting, safe code evaluation, dynamic SQL generation, and PostgreSQL introspection.

Available utilities include:

• graphile-config: Provides a standard plugin interface and helpers used across the Graphile suite.
• graphile-export: Enables exporting a GraphQL Schema (or other code) as executable JavaScript code.
• tamedevil: A module designed to help manage and safely handle eval operations.
• pg-sql2: Allows for creating highly dynamic SQL in a powerful and flexible manner while preventing SQL injection attacks.
• pg introspection: A strongly-typed PostgreSQL introspection library built automatically from the PostgreSQL system catalog documentation.

The Crystal monorepo contains a suite of packages focused on GraphQL, planning, and execution engines. The two primary headline projects are Grafast and PostGraphile.

• Grafast: A high-performance planning and execution engine for GraphQL.js. It is designed as a drop-in replacement for the standard GraphQL.js execute method. By using Grafast "plan resolvers" instead of traditional resolvers, you can leverage the declarative nature of GraphQL requests to optimize business logic execution and reduce server load. This is ideal for developers building custom GraphQL schemas who want maximum efficiency.
• PostGraphile: A tool for building high-performance GraphQL APIs backed by a PostgreSQL database with minimal effort. It uses the database as the "source of truth" to auto-generate the API, while allowing for significant customization and extensibility. You can also use graphile-export to turn a PostGraphile-generated API into a managed codebase.