PostGraphile

How PostGraphile is structured

PostGraphile (residing in the Graphile Crystal monorepo) is organized as a modular TypeScript workspace governed by Yarn Modern (yarn.lock, .yarnrc.yml). The repository splits functionality across several key namespaces:

• grafast/: The next-generation GraphQL planning and execution engine. It includes grafast/grafast (the core planning engine), grafast/dataplan-pg (PostgreSQL step classes that translate field selections into SQL query plans), grafast/grafserv (the HTTP server transport layer), and grafast/ruru (the GraphiQL exploration IDE).
• graphile-build/: The plugin-driven schema synthesis layer (graphile-build, graphile-build-pg), responsible for reading database catalogs and constructing the GraphQL schema AST through hook pipelines.
• postgraphile/: The top-level CLI (postgraphile/pgl), preset libraries (Amber, Relay, v4 compatibility), and documentation website (postgraphile/website).
• utils/: Low-level database introspection (utils/pg-introspection), SQL generation AST helpers (utils/pg-sql2), and configuration loaders (utils/graphile-config).

Frontend

PostGraphile does not ship a traditional end-user application frontend; instead, it delivers developer-facing exploration tooling centered around Ruru (grafast/ruru, grafast/ruru-components).

Ruru is a customized, Grafast-flavored distribution of GraphiQL built with React 19 (react, react-dom in grafast/ruru-components/package.json). It incorporates the GraphiQL plugin ecosystem (@graphiql/plugin-explorer, @graphiql/plugin-history, @graphiql/plugin-doc-explorer) and Mermaid diagram rendering (mermaid version 11) for visualizing Grafast query execution plans. The Ruru interface is bundled via Webpack (webpack.config.mts) and served either as an interactive web route or as a standalone CLI documentation server.

Backend & APIs

The backend engine is written entirely in strict TypeScript targeting modern Node.js environments ("node": ">=22" declared across package engines).

At the center of PostGraphile v5 is Grafast. Traditional GraphQL servers execute queries by invoking resolver functions recursively on each node in the GraphQL AST, which frequently leads to the infamous N+1 query problem. Grafast inverts this model: during the planning phase, it constructs a dependency graph of "steps" (using @dataplan/pg for database operations). When a query requests nested relations (such as users, their posts, and comments), Grafast plans a single, consolidated SQL query using lateral joins or subqueries, fetching all required data in one round trip.

HTTP serving is decoupled through Grafserv (grafast/grafserv). Grafserv implements standard transport protocols (including GraphQL-over-HTTP, incremental delivery, and SSE) while offering zero-cost adapters for popular Node.js frameworks:

• Node.js native http.createServer
• Express v4 (grafserv/express/v4)
• Fastify v4 and v5 (grafserv/fastify/v4, grafserv/fastify/v5)
• Koa v2 (grafserv/koa/v2)
• Hono (grafserv/hono/v4)
• AWS Lambda (grafserv/lambda/v1)

Data & persistence

PostGraphile does not manage a proprietary storage engine; rather, it treats PostgreSQL as the primary application engine:

• Introspection: Using utils/pg-introspection, PostGraphile connects to PostgreSQL, querying pg_catalog tables to discover tables, views, composite types, constraints, foreign keys, and stored functions.
• Smart Comments: Developers annotate PostgreSQL objects with SQL comments (e.g., COMMENT ON COLUMN users.password_hash IS '@omit';) to control GraphQL field visibility, naming inflections, and mutation behaviors without writing TypeScript code.
• SQL Execution: The engine constructs parameterized SQL queries using @dataplan/pg and utils/pg-sql2, executing queries against standard PostgreSQL connection pools (pg).
• Security via RLS: Authentication credentials (such as user IDs or tenant scopes extracted from JWTs) are injected into the PostgreSQL transaction context using SET LOCAL jwt.claims.user_id = .... The PostgreSQL engine then applies Row-Level Security (RLS) policies to enforce access control directly within the database engine.

Build, test & deploy

The development lifecycle in the monorepo is managed via Yarn workspaces and automated pipelines:

• Compilation: Project packages compile using project references in TypeScript (tsc -b).
• Testing: The repository uses Jest (jest.config.js) alongside custom serializers (utils/jest-serializer-graphql-schema) that verify emitted GraphQL schemas and SQL plan ASTs against regression snapshots.
• Continuous Integration: GitHub Actions workflows in .github/workflows execute linting (lint.yml), cross-version PostgreSQL matrix tests (test.yml), and documentation linting with Vale (vale.yml).
• Release Automation: Changesets (.changeset/config.json) automate semantic versioning, generating changelogs and publishing scoped packages to npm.

Self-hosting notes

Deploying PostGraphile requires minimal infrastructure:

1. A PostgreSQL instance (version 12 or newer, with version 16+ recommended for enhanced query planning).
2. A Node.js container or serverless function running the @graphile/postgraphile CLI or embedded in an existing Express/Fastify service.
3. Database credentials with appropriate permissions to read target schemas and execute functions.

PostGraphile can run as a standalone container using the pgl CLI (postgraphile/pgl), connecting to PostgreSQL via a standard connection string and exposing the GraphQL endpoint on a configurable HTTP port.

What to copy (and what not to)

Architectural insights from PostGraphile:

• Plan-based execution over resolvers: Replacing naive resolver execution trees with unified planning passes (the Grafast pattern) eliminates N+1 query bottlenecks at the architectural root rather than applying ad-hoc batching with DataLoader.
• Leveraging the database as the security boundary: Delegating authorization rules to PostgreSQL Row-Level Security policies guarantees that permissions are enforced consistently, whether queries originate from GraphQL, admin scripts, or background workers.
• Transport decoupling: Separating protocol parsing and execution from HTTP frameworks (as Grafserv does) makes libraries adaptable across Express, Fastify, Hono, and serverless environments.

Avoid attempting database schema introspection if your database schema lacks clean foreign key relationships or contains thousands of unpartitioned tables, as generating complete GraphQL schemas from unstructured relational schemas can produce bloated, unintuitive APIs.