graphpg

A GraphQL and REST server for PostgreSQL. Point it at a database and it serves a GraphQL API and a REST API (described by an OpenAPI 3.1 document) generated from the schema: tables, relations, constraints, types, functions and privileges. There is no resolver code to write and no schema to maintain in two places.

For AI work it covers two jobs. Agents that use your data get typed tools over it: vector, BM25 and hybrid search from your indexes, and MCP through Apollo's MCP Server, limited to the operations you list and to what Row-Level Security lets the agent's token see. Agents that build applications get a typed contract to code against: the GraphQL SDL and the OpenAPI document are generated from the database, pinned in CI, and errors carry typed codes. See AI agents and end-to-end type safety.

graphpg is a single Rust binary. It reads PostgreSQL's catalogs at startup, builds the APIs, and compiles each request into one SQL statement (lateral joins and JSON aggregation, so nested selections don't cause N+1 queries). Both APIs are planned onto the same engine, so they share filters, pagination, nested writes, typed errors, authorization and safety limits.

Status: 1.1, the API is stable. Versions follow semantic versioning: the GraphQL and REST APIs derived from a database, error codes, configuration and CLI change incompatibly only in a major version. The behaviour documented here is covered by an integration test suite that runs against PostgreSQL 18. See the changelog.

Quick start

git clone https://github.com/mihailtd/graphpg && cd graphpg/examples/blog
docker compose up --build

Open http://localhost:4000/graphiql for GraphQL, or http://localhost:4000/scalar for the REST API reference. The blog example loads a small schema and shows relations, filtering, pagination, search and nested writes in both.

Run the published container image against your own database:

docker run --rm -p 4000:4000 \
  -e DATABASE_URL=postgres://user:[email protected]/mydb \
  ghcr.io/mihailtd/graphpg:1.3.0 --mode dev

The image is a static binary on distroless/static (about 27 MB with the embedded GraphiQL and Scalar UIs, no shell, non-root, signed with Sigstore). See running in a container.

Or build from source:

cargo install --path crates/graphpg          # or: cargo build --release
DATABASE_URL=postgres://user:pass@localhost/mydb graphpg --mode dev

{
  authors {
    username
    postsConnection(first: 5, orderBy: [CREATED_AT_DESC]) { nodes { title tags { name } } }
  }
}

The same data over REST:

curl -g 'localhost:4000/rest/posts?filter[status][eq]=PUBLISHED&order=-createdAt&first=5&include=tags'
curl -X POST localhost:4000/rest/authors -H 'content-type: application/json' \
     -d '{"username": "ada", "displayName": "Ada", "posts": {"create": [{"title": "Hello", "body": "Hi there"}]}}'    # a nested write

This is the beginning of the README. Read the rest at the original. Read the full README ↗