graphpg: Unified GraphQL and REST Engine for PostgreSQL

graphpg is an open-source, database-first API engine built in-house in Rust. It reads a PostgreSQL schema—tables, foreign keys, constraints, composite types, functions, and Row-Level Security policies—and serves a full GraphQL API and a REST API (with OpenAPI 3.1 specifications) from a single query planner.

We built and Adopted graphpg across our infrastructure after hitting the limits of running separate tools for GraphQL and REST. Maintaining two distinct data layers creates protocol drift: filter operators differ, error codes diverge, and connection limits apply inconsistently. graphpg eliminates this drift by planning both protocols onto one execution model where every request compiles into one SQL statement.

Architectural Philosophy: One Engine, One Statement

Rather than implementing a GraphQL server in Node.js and a separate REST gateway in Haskell or Go, graphpg runs as a static Rust binary (distroless/static, ~27 MB) directly in front of PostgreSQL.

1. Unified Operation Plan Across Both Protocols

In graphpg, a REST call such as GET /rest/posts?filter[status][eq]=PUBLISHED&include=tags and its equivalent GraphQL selection are two syntax projections of the exact same operation plan. They share:

• Keyset cursor pagination (first / after / last / before) and HTTP Range headers (Range: items=0-19).
• Deep filtering across relations (some, every, none, count), full-text, vector cosine scans (pgvector), and BM25 text search.
• Nested atomic writes (creating, connecting, updating, and syncing related records in a single transaction).
• Database-derived error codes (EMAIL_TAKEN, AUTHOR_NOT_FOUND).

2. Zero N+1 Queries: Single-Statement Execution

Nested relational selections in GraphQL frequently trigger N+1 queries in naive resolvers. graphpg compiles nested queries into SQL lateral joins and JSON aggregation. A query retrieving 20 posts with their respective authors, tags, and top comments executes as a single round trip to PostgreSQL.

In benchmark evaluations against PostgREST 16.4 on PostgreSQL 18.6, graphpg delivered 1.4x to 3x higher throughput on reads while enforcing strict depth, page-size, and cost limits on the plan before any SQL runs.

3. End-to-End Type Safety for AI Coding Agents

graphpg automatically exports schema.graphql (GraphQL SDL) and openapi.json (OpenAPI 3.1) during development. Code generators (GraphQL Code Generator and openapi-typescript) convert these contracts into TypeScript client types.

When an engineer or an AI coding agent executes a database migration (e.g., renaming a column in Drizzle), the contracts update immediately. The TypeScript compiler catches every outdated query across the codebase, turning an ambiguous refactoring task into a bounded list of compiler errors.

4. Enterprise Integrations Without In-Process Plugins

graphpg rejects arbitrary in-process plugins to preserve predictable single-statement execution and strict transaction rollback guarantees:

• Computed Columns & Queries: Declared directly as PostgreSQL functions (STABLE for queries, VOLATILE for mutations).
• Asynchronous Side Effects: Captured via event triggers within the database transaction and delivered as signed webhooks (Standard Webhooks format).
• Federated Services: Composed at the gateway as an Apollo Federation v2 subgraph.
• External Data: Linked across databases and Parquet files using PostgreSQL Foreign Data Wrappers.

Verdict & Usage

graphpg is our standard API engine for PostgreSQL-backed applications and AI agent workflows. We recommend it for:

• Projects requiring both GraphQL for frontend user interfaces and REST for external services and AI agents.
• Workflows where database migrations drive typed frontend and client contracts automatically.
• High-throughput services requiring sub-millisecond single-statement queries with zero resolver bloat.

In-Depth Articles & Documentation

• Architectural Deep-Dive: Why GraphQL and REST Should Share One Engine: What I Learned Building graphpg
• Developer Guide: How End-to-End Type Safety Turns "Change It Everywhere" Into a List Your AI Agent Can Finish
• Official Website & Documentation: graphpg Documentation
• Open Source Repository: GitHub @mihailtd/graphpg