Concepts

MeshQL connects client queries to SQL-friendly resolvers and nested JSON responses.

Schema

Your schema defines entities, fields, and joins:

const schema = {
  entities: {
    user: { type: {} as User, fields: ["id", "name"], table: "users" },
    token: {
      type: {} as Token,
      fields: ["accessToken"],
      table: "tokens",
      columns: { accessToken: "access_token" },
    },
  },
  joins: {
    "user.tokens": {
      entity: "token",
      on: "tokens.user_id = users.id",
      type: "many",
    },
  },
};

• entities — root types clients can query
• fields — allowed scalar fields per entity
• joins — how entities relate (used to build JoinPlan joins)
• table / columns — optional SQL mapping for buildSelectSql()

Query formats

JSON selection (default for @meshql/client):

{ "user": { "id": true, "name": true, "tokens": { "accessToken": true } } }

QL brace syntax:

{ user { id name tokens { accessToken } } }

Clients send queries in X-Mesh-Query (base64-encoded). See HTTP adapters.

JoinPlan

When a request arrives, MeshQL parses the query and builds a JoinPlan:

mesh.resolve("user", async (plan) => {
  plan.fields; // only fields the client asked for
  plan.joins;  // only joins the client requested
  plan.context.requestId; // correlation id for your logger
  // ...
});

Use plan to fetch only what was requested — no over-fetching.

You bring the database client. MeshQL does not create or pool connections. Register a resolver that closes over your PrismaClient, pg.Pool, Drizzle db, or SQLite handle. See Database connections and ORM adapters.

Language ports and alternate implementations: see the protocol specs.

Shaper

Resolvers return flat rows with aliased columns:

{ user_id: 1, user_name: "Ada", tokens_accessToken: "tok_1" }

MeshQL’s shaper converts these into nested JSON:

{
  "id": 1,
  "name": "Ada",
  "tokens": [{ "accessToken": "tok_1" }]
}

createMesh

import { createMesh } from "@meshql/core";

const mesh = createMesh(schema);
mesh.resolve("user", async (plan) => { /* ... */ });
await mesh.execute(query, { format: "json" });

Attach HTTP adapters from @meshql/http or call mesh.execute() directly in tests.

Errors

MeshQL returns structured JSON errors (ValidationError, TransportError, etc.). See the HTTP reference.