graphql-development
Architect, implement, secure, and optimize production GraphQL APIs using Schema Definition Language (SDL), resolver design, DataLoader batching for N+1 prevention, cursor-based pagination, input valid
SKILL.mdskills/graphql-development/SKILL.md
GitHubGraphQL API Architecture & Engineering
GraphQL is a strongly typed query language and runtime for APIs that lets clients request precisely the data they need. Unlike REST, GraphQL executes queries against a single endpoint through hierarchical resolvers, making predictable execution plans, batching, schema evolution, and query safety critical engineering priorities.
Purpose & Overview
This skill guides the design, implementation, and hardening of production GraphQL services. It covers schema-first vs code-first workflows, resolver construction, elimination of N+1 query cascades via DataLoader, Relay-compliant cursor pagination, custom scalar validation, structured error reporting, and defensive depth/complexity limits against malicious queries.
Core Principles & Rules
- Eliminate N+1 queries with DataLoader: Never perform database or downstream HTTP lookups inside child field resolvers without batching. Every relation traversal must use a request-scoped DataLoader.
- Schema-first SDL or code-first with strict typing: Keep schema definitions and resolver types aligned. In code-first (e.g., Pothos, Nexus, Strawberry), generate SDL artifacts for review. In schema-first, use code-generation tools (e.g., GraphQL Code Generator) to produce strict TypeScript/Go types.
- Favor cursor-based pagination for collections: Follow the Relay Connection specification (
edges,node,cursor,pageInfo) for lists that change or scale. Avoid offset/limit pagination on mutable or large datasets. - Mutations must return structured payloads: Never return a bare boolean or single primitive from a mutation. Always return a payload object containing the modified entity, client mutation ID, and user-facing validation errors (
userErrors). - Never expose raw database or internal errors: Catch database and system errors before they reach the GraphQL execution engine. Return domain errors with structured
extensions(code, field, timestamp) and mask internal stack traces in production. - Enforce query depth and complexity limits: GraphQL APIs expose arbitrary graph traversals. Always validate query ASTs against maximum depth limits (e.g., 6–10 levels) and cost complexity budgets before execution.
- Input validation belongs at the edge: Use custom scalars (
DateTime,EmailAddress,PositiveInt) and input schema validators (Zod, Class-Validator, Pydantic) to reject invalid input before invoking business logic.
Standard Workflows & Procedures
Workflow 1: Schema-First Design with Code Generation
- Define canonical types, queries, and mutations in
.graphqlSDL files. - Define custom scalars for domain-specific primitives.
- Configure code generation (e.g.,
@graphql-codegen/cli) to generate resolver signatures and TypeScript models. - Implement root and field resolvers matching the generated contracts.
Workflow 2: Request-Scoped DataLoader Wiring
- Instantiate DataLoaders inside the per-request GraphQL context function (never as singletons across concurrent requests to avoid cross-tenant data leaks and stale cache poisoning).
- Wire batch loading functions using primary keys or foreign keys.
- Pass the dataloader collection via
context.loaders.
Workflow 3: Defensive Query Protection Pipeline
- Install query depth limiting (
graphql-depth-limit) on the schema validation phase. - Calculate query complexity scores based on field weights and list multipliers before execution.
- Set execution timeouts (e.g., 5 seconds) to terminate runaway resolvers.
- Disable introspection (
introspection: false) and schema exploration in public production environments unless explicitly required.
Real-World Examples & Patterns
1. Schema Definition Language (SDL) & Mutation Payloads
scalar DateTime
scalar EmailAddress
enum OrderStatus {
PENDING
PROCESSING
SHIPPED
DELIVERED
CANCELLED
}
interface Node {
id: ID!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
type OrderEdge {
cursor: String!
node: Order!
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type User implements Node {
id: ID!
email: EmailAddress!
name: String!
orders(first: Int = 20, after: String): OrderConnection!
createdAt: DateTime!
}
type Order implements Node {
id: ID!
user: User!
status: OrderStatus!
amountInCents: Int!
createdAt: DateTime!
}
input CreateOrderInput {
userId: ID!
amountInCents: Int!
}
type UserError {
field: [String!]
message: String!
code: String!
}
type CreateOrderPayload {
order: Order
userErrors: [UserError!]!
}
type Query {
user(id: ID!): User
order(id: ID!): Order
}
type Mutation {
createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
2. DataLoader Pattern to Eliminate N+1 Queries (TypeScript)
import DataLoader from 'dataloader';
import { db } from './database';
export interface GraphQLContext {
userId?: string;
loaders: {
userLoader: DataLoader<string, UserRecord | null>;
ordersByUserIdLoader: DataLoader<string, OrderRecord[]>;
};
}
// Request context factory (instantiated per incoming HTTP request)
export function createContext(): GraphQLContext {
return {
loaders: {
userLoader: new DataLoader<string, UserRecord | null>(async (userIds) => {
const users = await db.users.findMany({
where: { id: { in: [...userIds] } },
});
const userMap = new Map(users.map((u) => [u.id, u]));
return userIds.map((id) => userMap.get(id) ?? null);
}),
ordersByUserIdLoader: new DataLoader<string, OrderRecord[]>(async (userIds) => {
const orders = await db.orders.findMany({
where: { userId: { in: [...userIds] } },
orderBy: { createdAt: 'desc' },
});
const grouped = new Map<string, OrderRecord[]>();
for (const order of orders) {
const list = grouped.get(order.userId) ?? [];
list.push(order);
grouped.set(order.userId, list);
}
return userIds.map((id) => grouped.get(id) ?? []);
}),
},
};
}
// Resolvers leveraging DataLoader
export const resolvers = {
Order: {
user: async (parent: OrderRecord, _args: unknown, ctx: GraphQLContext) => {
const user = await ctx.loaders.userLoader.load(parent.userId);
if (!user) {
throw new Error(`User ${parent.userId} not found for Order ${parent.id}`);
}
return user;
},
},
User: {
orders: async (parent: UserRecord, args: { first?: number; after?: string }, ctx: GraphQLContext) => {
const allOrders = await ctx.loaders.ordersByUserIdLoader.load(parent.id);
return paginateArray(allOrders, args.first ?? 20, args.after);
},
},
};
3. Cursor-Based Pagination Implementation
export function paginateArray<T extends { id: string }>(
items: T[],
first: number,
after?: string
) {
const limit = Math.min(Math.max(first, 1), 100);
let startIndex = 0;
if (after) {
const decodedId = Buffer.from(after, 'base64').toString('utf-8');
const index = items.findIndex((item) => item.id === decodedId);
if (index !== -1) {
startIndex = index + 1;
}
}
const sliced = items.slice(startIndex, startIndex + limit);
const edges = sliced.map((item) => ({
cursor: Buffer.from(item.id).toString('base64'),
node: item,
}));
const hasNextPage = startIndex + limit < items.length;
const hasPreviousPage = startIndex > 0;
return {
edges,
totalCount: items.length,
pageInfo: {
hasNextPage,
hasPreviousPage,
startCursor: edges[0]?.cursor ?? null,
endCursor: edges[edges.length - 1]?.cursor ?? null,
},
};
}
4. Structured Error Handling with Extensions
import { GraphQLError } from 'graphql';
export class DomainValidationError extends GraphQLError {
constructor(message: string, field: string, code = 'BAD_USER_INPUT') {
super(message, {
extensions: {
code,
field,
timestamp: new Date().toISOString(),
},
});
}
}
export class UnauthorizedError extends GraphQLError {
constructor(message = 'Authentication required') {
super(message, {
extensions: {
code: 'UNAUTHENTICATED',
http: { status: 401 },
},
});
}
}
// In Resolver:
export const mutationResolvers = {
createOrder: async (_root: unknown, { input }: { input: CreateOrderInput }, ctx: GraphQLContext) => {
if (!ctx.userId) {
throw new UnauthorizedError();
}
if (input.amountInCents <= 0) {
return {
order: null,
userErrors: [{
field: ['input', 'amountInCents'],
message: 'Order amount must be greater than zero.',
code: 'INVALID_AMOUNT',
}],
};
}
const order = await db.orders.create({ data: input });
return { order, userErrors: [] };
},
};
5. Query Depth & Complexity Limiting
import depthLimit from 'graphql-depth-limit';
import { createComplexityLimitRule } from 'graphql-validation-complexity';
import { ApolloServer } from '@apollo/server';
const MAX_QUERY_DEPTH = 6;
const MAX_QUERY_COMPLEXITY = 1000;
const server = new ApolloServer({
typeDefs,
resolvers,
validationRules: [
depthLimit(MAX_QUERY_DEPTH),
createComplexityLimitRule(MAX_QUERY_COMPLEXITY, {
onCost: (cost) => console.log(`Calculated query cost: ${cost}`),
formatErrorMessage: (cost) =>
`Query cost ${cost} exceeds maximum allowed complexity of ${MAX_QUERY_COMPLEXITY}`,
}),
],
});
Common Anti-Patterns & Pitfalls
| Anti-Pattern | Why It Fails | Remediated Practice |
|---|---|---|
| Global DataLoader instance | Shares cached database records across separate HTTP requests, leaking tenant data and serving stale writes. | Always instantiate DataLoaders inside the per-request context factory function. |
| Offset/Limit on large collections | Performance degrades with high offsets (OFFSET 100000) and yields duplicate/skipped items on write-heavy tables. |
Use Relay-style cursor-based pagination backed by indexed keyset filters (WHERE id > :cursor). |
| Direct database queries in child resolvers | A query requesting 50 authors and their books issues 51 sequential queries (N+1 cascade), exhausting the pool. | Batch foreign-key lookups through DataLoader batch functions. |
| Exposing raw internal exceptions | Database constraint names, SQL statements, and internal server IPs are leaked in the errors payload. |
Sanitize errors in the formatting pipeline, returning friendly messages and typed userErrors. |
Unbounded list arguments (first: 100000) |
Allows malicious clients to exhaust memory and CPU by fetching entire tables in one query. | Enforce maximum bounds on list arguments (e.g. Math.min(first, 100)). |
| Unprotected recursive schemas | Circular relationships (user -> posts -> author -> posts) enable malicious denial-of-service queries. |
Attach query depth limiting and complexity estimation rules to schema validation. |
Verification Checklist
- Every relation resolver uses a request-scoped DataLoader batch function.
- DataLoaders are created inside the per-request context, never as modules or singletons.
- Schema defines custom scalars for dates, emails, and bounded numbers.
- All collections support cursor-based pagination with
edges,node,pageInfo, and an upper limit onfirst. - Mutations return a payload type containing the subject entity and a
userErrorscollection. - Query depth limiting rule is registered (maximum depth between 5 and 8).
- Query complexity rule is configured with field weights and array multipliers.
- Production servers mask internal stack traces and database error messages.
- Introspection is disabled or secured behind authenticated admin access in production.
Tooling & Reference Guides
- Schema Tools:
graphql-tag,@graphql-tools/schema,@graphql-codegen/clifor automated TypeScript generation. - Batching & Resolvers:
dataloader(JavaScript/TypeScript),strawberry-graphqlwith dataloaders (Python),gqlgenwith dataloaders (Go). - Security & Complexity:
graphql-depth-limit,graphql-validation-complexity,graphql-armorfor layered defense. - Standards: GraphQL Specification, GraphQL Cursor Connections Specification (Relay).