graphpgType-safe GraphQL and REST, generated from PostgreSQL

End-to-end types

Change the database, and the type checker finds every place that broke ​

How often have you asked an agent to "change this everywhere" and found, a day later, the one place it missed? In a large codebase, search finds most uses of a column, not all of them. When the types come from the database, the missed places stop compiling, and the agent reads the errors and fixes them in the same session.

export const patients = pgTable("patients", {
  id: uuid("id").primaryKey(),
  family: text("family"),
  given: text("given"),
});

graphql(`query PatientList {
  patientsConnection(orderBy: [FAMILY_ASC]) {
    nodes { id family given }
  } }`);

api.GET("/rest/patients", { params: {
  query: { fields: ["id", "family"] } } });

Schema in SQL

SQL is the schema language agents already write well ​

Built for AI

Two ways AI uses graphpg ​

Retrieval

Hybrid search is one field ​

Create a vector index and a lexical one; graphpg adds semantic, lexical and hybrid search to both APIs. Hybrid search fuses the two rankings by reciprocal rank inside one SQL statement, after your filters and policies have scoped the candidates.

CREATE TABLE documents (
    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tenant_id uuid NOT NULL,
    title text NOT NULL,
    body text NOT NULL,
    embedding vector(1536) NOT NULL
);
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);  -- semantic
CREATE INDEX ON documents USING gist (title gist_trgm_ops);          -- lexical, or ParadeDB bm25

query Retrieve($embedding: [Float!]!, $tenant: UUID!) {
  documentsHybridSearch(query: "refund policy", vector: $embedding, first: 5,
                        filter: { tenantId: { equalTo: $tenant } }) {
    hits { score node { id title body } }
  }
}

curl -X POST localhost:4000/rest/documents/search/hybrid \
     -H 'content-type: application/json' \
     -d '{"query": "refund policy", "vector": [0.012, -0.034, ...], "first": 5}'

MCP

Tools for your agents, from operations you choose ​

Apollo MCP Server turns GraphQL operations into MCP tools. Point it at graphpg, list the operations an agent may run, and give it the agent's token: each call runs as that role, under its policies and limits.

endpoint: http://localhost:4000/graphql
transport:
  type: stdio
headers:
  Authorization: "Bearer ${env.GRAPHPG_AGENT_TOKEN}"
schema:
  source: local
  path: ./schema.graphql          # graphpg export-graphql
operations:
  source: local
  paths:
    - ./operations/SearchPosts.graphql
    - ./operations/AddComment.graphql
overrides:
  mutation_mode: explicit         # listed mutations only

query SearchPosts($query: String!) {
  postsFuzzySearch(query: $query, first: 5) {
    hits { score node { id title excerpt(length: 200) } }
  }
}

{
  "mcpServers": {
    "graphpg": {
      "command": "apollo-mcp-server",
      "args": ["/path/to/mcp.yaml"],
      "env": { "GRAPHPG_AGENT_TOKEN": "..." }
    }
  }
}

One schema, two APIs

Write SQL. Get GraphQL and REST. ​

Schema design stays in PostgreSQL. This is a slice of the blog example; everything below is served from it with no further setup.

CREATE TYPE post_status AS ENUM ('draft', 'published', 'archived');

CREATE TABLE posts (
    id uuid PRIMARY KEY DEFAULT uuidv7(),
    author_id uuid NOT NULL REFERENCES authors (id),
    title text NOT NULL,
    body text NOT NULL,
    status post_status NOT NULL DEFAULT 'draft',
    word_count int GENERATED ALWAYS AS (cardinality(string_to_array(body, ' '))) STORED,
    created_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX posts_title_trgm_idx ON posts USING gist (title gist_trgm_ops);

-- a function of a row becomes a computed field: Post.excerpt
CREATE FUNCTION posts_excerpt(p posts, length int DEFAULT 80) RETURNS text
    LANGUAGE sql STABLE AS $$ SELECT left(p.body, length) $$;

{
  postsConnection(
    first: 10
    filter: { status: { equalTo: PUBLISHED } }
    orderBy: [CREATED_AT_DESC]
  ) {
    nodes {
      title
      wordCount             # generated column, read-only
      excerpt(length: 30)   # posts_excerpt(p posts, length int)
      author { displayName }
      tags { name }         # many-to-many through post_tags
    }
    pageInfo { hasNextPage endCursor }
  }
  postsFuzzySearch(query: "nanosec") { hits { score node { title } } }
}

mutation {
  createPost(input: {
    authorId: "0192f1a0-0000-7000-8000-000000000001"
    title: "Hello"
    body: "First words."
    tags: { connect: [{ name: "computing" }] }   # nested write, one transaction
  }) {
    post { id title wordCount tags { name } }
  }
}
# an unknown authorId fails with AUTHOR_NOT_FOUND on input.authorId,
# and the whole operation rolls back

# filter, order, keyset pagination (Link: rel="next") and embedding
curl -g 'localhost:4000/rest/posts?filter[status][eq]=PUBLISHED&order=-createdAt&first=5&include=tags'

# a nested write: the author and a post in one transaction
curl -X POST localhost:4000/rest/authors -H 'content-type: application/json' \
     -d '{"username": "ada2", "displayName": "Ada", "posts": {"create": [{"title": "Hello", "body": "Hi"}]}}'

# grouped aggregates, fuzzy search, and a function
curl -g 'localhost:4000/rest/posts/aggregate?group=status&max=createdAt'
curl -X POST localhost:4000/rest/posts/search/fuzzy -d '{"query": "nanosec"}' -H 'content-type: application/json'
curl 'localhost:4000/rest/rpc/popular_tags'

What it generates

Everything you would otherwise write by hand ​

Performance

Fast where it counts ​

Each request is one statement, so most of the time is PostgreSQL's own work, and graphpg keeps the rest small. Against PostgREST on the same database, the reads below ran at 1.4 to 3 times the throughput. Where PostgreSQL dominates it was about even: deep offset pagination, and bulk updates by filter (2% behind). Single-row writes ran at 1.1 to 1.4 times.

Compared

Where it sits ​

graphpg covers the ground of PostGraphile and Hasura on the GraphQL side and PostgREST on the REST side, from one binary. The comparison lists what each tool does, including where the others are broader.

From the blog

Why it works this way ​

Written by Mihai Farcas, who builds graphpg. Follow along on GitHub.

Latest release

What's new ​