hasura/graphql-engine

Blazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.

31,950 stars TypeScript 8 components

Exposes database schemas as instant GraphQL APIs with realtime subscriptions and fine-grained authorization

Database schemas are introspected by data connectors to produce SchemaResponse objects containing table/column metadata. The GraphQL engine uses this to auto-generate GraphQL schemas. Incoming GraphQL queries are parsed, planned into QueryRequest objects with filters/joins, sent to appropriate data connectors for SQL execution, and results are formatted back to GraphQL responses. Configuration changes flow through the CLI to update metadata, which triggers schema regeneration.

Under the hood, the system uses 3 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.

A 8-component fullstack. 4462 files analyzed. Data flows through 5 distinct pipeline stages.

How Data Flows Through the System

Schema Introspection — Data connectors examine database schema using INFORMATION_SCHEMA queries or native APIs, extracting table definitions, column types, primary keys, foreign keys, and functions into standardized SchemaResponse format [Config → SchemaResponse] (config: db, tables, explicit_main_schema)
GraphQL Schema Generation — Engine processes SchemaResponse to auto-generate GraphQL schema with Query/Mutation/Subscription types, creating resolvers for each table and applying naming conventions and custom root field names [SchemaResponse → GraphQL Schema] (config: custom_root_fields, custom_column_names)
Query Planning — GraphQL queries are parsed into AST, validated against schema, and converted to QueryRequest objects containing table selection, field projection, where clauses, joins, and ordering with permission filters applied [GraphQL AST → QueryRequest]
Database Execution — Data connectors translate QueryRequest into native database queries (SQL for relational databases), execute against configured databases, and return QueryResponse with structured result sets [QueryRequest → QueryResponse] (config: db, timeout_seconds)
Response Formatting — QueryResponse data is mapped back to GraphQL response format, applying field selections, handling nested relationships, and formatting according to GraphQL specification [QueryResponse → GraphQL Response]

Data Models

The data structures that flow between stages — the contracts that hold the system together.

SchemaResponse dc-agents/dc-api-types/src/models/SchemaResponse.ts
object with tables: TableInfo[], functions: FunctionInfo[], procedures: ProcedureInfo[], scalar_types: Record<string, ScalarTypeCapabilities>
Generated by data connectors during schema introspection, consumed by engine to build GraphQL schema

QueryRequest dc-agents/dc-api-types/src/models/QueryRequest.ts
object with table: TableName, query: Query containing fields, where conditions, order_by, limit
Created from parsed GraphQL queries, sent to data connectors for execution

Config dc-agents/sqlite/src/config.ts
object with db: string, explicit_main_schema: boolean, tables: string[] | null, meta: boolean
Parsed from X-Hasura-DataConnector-Config header, used to configure data connector behavior

RequestTransform frontend/libs/console/legacy-ce/src/lib/metadata/types.ts
object with body: RequestTransformBody, method: RequestTransformMethod, query_params: QueryParams, template_engine: TemplateEngine
Configured in console UI, stored in metadata, applied to transform webhook requests

Expression dc-agents/dc-api-types/src/models/Expression.ts
union type: OrExpression | ApplyBinaryComparisonOperator | ExistsExpression | NotExpression | ApplyBinaryArrayComparisonOperator | ApplyUnaryComparisonOperator | AndExpression
Built from permission rules and GraphQL where clauses, evaluated during query execution

StaticData dc-agents/reference/src/data/index.ts
object with schema: SchemaResponse, data: Record<string, Record<string, string | number | boolean | null>[]>
Loaded from compressed XML files during reference connector initialization, serves as mock database

Hidden Assumptions

Things this code relies on but never validates. These are the things that cause silent failures when the system changes.

critical Contract weakly guarded

The X-Hasura-DataConnector-Config header contains valid JSON with a 'db' property that is a string path to an accessible SQLite database file

If this fails: If the header contains malformed JSON, missing 'db' property, or points to a non-existent/inaccessible file, the SQLite connector will fail to initialize but the error won't indicate which specific validation failed

dc-agents/sqlite/src/config.ts:getConfig

critical Environment weakly guarded

SQLite database files referenced in config.db exist on the filesystem and are readable/writable based on the configured access mode flags

If this fails: If database file doesn't exist or has wrong permissions, the SQLite.Database constructor will callback with an error, but the error handling doesn't distinguish between file not found vs permission denied vs corrupted database

dc-agents/sqlite/src/db.ts:withConnection

critical Domain unguarded

Compressed XML files are encoded in UTF-16LE format and the root XML element name matches the pattern '${name}DataSet' where name is the dataset parameter

If this fails: If XML files use different encoding (UTF-8, UTF-32) or different root element naming convention, xml2js parsing will fail with cryptic encoding errors or the data extraction will return undefined

dc-agents/reference/src/data/index.ts:loadStaticData

warning Shape unguarded

SchemaResponse.tables array contains ColumnInfo objects with 'type' property set to exactly 'number' for numeric columns, and XML data contains numeric values in columns marked as type 'number'

If this fails: If schema uses different type names ('integer', 'float', 'numeric') or XML contains non-numeric values in numeric columns, the selective number parsing will either parse strings as numbers incorrectly or leave valid numbers as strings

dc-agents/reference/src/data/index.ts:parseNumbersInNumericColumns

critical Resource weakly guarded

DB_ALLOW_LIST environment variable, if set, contains database paths that should be blocked (inverse logic), and database connections can be opened synchronously without connection pool limits

If this fails: The allow list logic is inverted - it blocks databases IN the allow list rather than allowing only those databases. Also, no connection pooling means concurrent requests can exhaust file descriptors

dc-agents/sqlite/src/db.ts:withConnection

warning Temporal weakly guarded

Schema JSON files and compressed XML data files are synchronized - if one exists, the matching file should also exist and be from the same dataset version

If this fails: Function only checks file accessibility, not content consistency. If schema.json is updated but xml.gz is stale, loadStaticData will succeed but return mismatched schema/data causing silent data corruption

dc-agents/reference/src/data/index.ts:staticDataExists

warning Scale unguarded

Compressed XML files are small enough to be fully loaded into memory as a single buffer without memory constraints or timeouts

If this fails: Large XML datasets (>1GB compressed) will cause out-of-memory errors or hang the process without timeout, affecting all other requests to the data connector

dc-agents/reference/src/data/index.ts:streamToBuffer

info Contract unguarded

KeyValuePair arrays contain unique keys - if duplicate keys exist, later values should overwrite earlier ones silently

If this fails: Function uses object spread to merge pairs, so duplicate keys get overwritten without warning. Configuration UI may show multiple entries for same key but only last value is used, confusing users

frontend/libs/console/legacy-ce/src/lib/components/Common/ConfigureTransformation/utils.ts:getPairsObjFromArray

warning Domain unguarded

Session variables in GraphQL headers must have names starting with 'x-hasura' (case insensitive) to be valid session variables

If this fails: Headers like 'X-Custom-Auth' or 'authorization' won't be recognized as session variables, potentially causing permission checks to fail silently when custom auth headers are expected

frontend/libs/console/legacy-ce/src/lib/components/Common/ConfigureTransformation/utils.ts:getSessionVarsArrayFromGraphiQL

warning Ordering unguarded

SQLite transaction operations (BEGIN, COMMIT, ROLLBACK) execute synchronously and in order without other operations interleaving

If this fails: If concurrent queries execute between BEGIN and COMMIT, they might see partial transaction state. No transaction isolation level is specified, defaulting to SQLite's default which may not match application expectations

dc-agents/sqlite/src/db.ts:withTransaction

System Behavior

How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Metadata Store (database)
PostgreSQL database storing Hasura metadata including table tracking, permissions, actions, remote schemas, and event triggers

Schema Cache (in-memory)
In-memory cache of processed GraphQL schema and query plans to avoid repeated schema generation

Connection Pool (buffer)
Pool of database connections with transaction support and configurable access modes

Feedback Loops

Schema Reload (cache-invalidation, balancing) — Trigger: Metadata changes via CLI or console. Action: Invalidate schema cache and regenerate GraphQL schema from fresh database introspection. Exit: New schema successfully generated and cached.
Database Connection Retry (retry, balancing) — Trigger: Database connection failure or timeout. Action: Exponential backoff retry with jitter, attempting to reconnect to database. Exit: Connection established or max retries exceeded.
Live Query Updates (polling, reinforcing) — Trigger: GraphQL subscription established. Action: Periodically re-execute subscription query and compare results to detect changes. Exit: Subscription cancelled by client.

Delays

Schema Introspection (warmup, ~varies by database size) — Initial startup delay while discovering database schema and generating GraphQL types
Metadata Migration (batch-window, ~user-configured) — Database unavailable during migration application, changes batched to reduce downtime
Connection Establishment (async-processing, ~network-dependent) — Initial query latency while establishing database connections in pool

Control Points

Database Connection Mode (env-var) — Controls: Whether SQLite opens in read-only, read-write, or create mode affecting mutation capabilities. Default: DB_READONLY, DB_CREATE, DB_PRIVATECACHE
Table Allow List (env-var) — Controls: Restricts which database files can be accessed for security. Default: DB_ALLOW_LIST
Query Length Limit (threshold) — Controls: Maximum SQL query length to prevent resource exhaustion attacks. Default: QUERY_LENGTH_LIMIT
Custom Root Fields (runtime-toggle) — Controls: Allows customizing GraphQL root field names for tables (select, insert, update, delete operations). Default: custom_root_fields config

Technology Stack

TypeScript (runtime)
Primary language for data connectors, CLI extensions, and frontend console

Haskell (runtime)
V2 GraphQL engine implementation with strong type safety for query planning

Go (runtime)
CLI tool implementation for migrations, metadata management, and project scaffolding

React (framework)
Frontend console UI for schema management and GraphQL exploration

FastifyJS (framework)
HTTP server framework for data connector API endpoints

SQLite (database)
Reference database implementation for testing and development

PostgreSQL (database)
Primary metadata store and supported database backend

Docker (infra)
Containerization for development environments and testing

Key Components

ExecutionContext (orchestrator) — Coordinates CLI operations with configuration, logging, HTTP clients, and plugin management cli/v2/execution_context.go
DataConnectorHandler (adapter) — Implements data connector API for SQLite, translating GraphQL queries to SQL and executing against SQLite databases dc-agents/sqlite/src/handlers
SchemaIntrospector (processor) — Discovers and parses database schema information, extracting tables, columns, relationships, and functions dc-agents/reference/src/data/index.ts
QueryPlanner (transformer) — Converts GraphQL AST into optimized database queries, handling joins, aggregations, and permission filters server/
MetadataManager (store) — Manages Hasura metadata (tables, permissions, actions, remote schemas) with versioning and migration support cli/commands/
TransformationEngine (transformer) — Applies request/response transformations to webhook payloads using template engines and custom logic frontend/libs/console/legacy-ce/src/lib/components/Common/ConfigureTransformation/
ConnectionPool (allocator) — Manages SQLite database connections with configurable access modes and transaction support dc-agents/sqlite/src/db.ts
PermissionValidator (validator) — Evaluates row-level and field-level permissions against user session variables and request context server/

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Fullstack Repositories

Frequently Asked Questions

What is graphql-engine used for?

Exposes database schemas as instant GraphQL APIs with realtime subscriptions and fine-grained authorization hasura/graphql-engine is a 8-component fullstack written in TypeScript. Data flows through 5 distinct pipeline stages. The codebase contains 4462 files.

How is graphql-engine architected?

graphql-engine is organized into 5 architecture layers: GraphQL Engine Core, Data Connectors, CLI & Migrations, Console Frontend, and 1 more. Data flows through 5 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.

How does data flow through graphql-engine?

Data moves through 5 stages: Schema Introspection → GraphQL Schema Generation → Query Planning → Database Execution → Response Formatting. Database schemas are introspected by data connectors to produce SchemaResponse objects containing table/column metadata. The GraphQL engine uses this to auto-generate GraphQL schemas. Incoming GraphQL queries are parsed, planned into QueryRequest objects with filters/joins, sent to appropriate data connectors for SQL execution, and results are formatted back to GraphQL responses. Configuration changes flow through the CLI to update metadata, which triggers schema regeneration. This pipeline design reflects a complex multi-stage processing system.

What technologies does graphql-engine use?

The core stack includes TypeScript (Primary language for data connectors, CLI extensions, and frontend console), Haskell (V2 GraphQL engine implementation with strong type safety for query planning), Go (CLI tool implementation for migrations, metadata management, and project scaffolding), React (Frontend console UI for schema management and GraphQL exploration), FastifyJS (HTTP server framework for data connector API endpoints), SQLite (Reference database implementation for testing and development), and 2 more. A focused set of dependencies that keeps the build manageable.

What system dynamics does graphql-engine have?

graphql-engine exhibits 3 data pools (Metadata Store, Schema Cache), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle cache-invalidation and retry. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does graphql-engine use?

5 design patterns detected: Schema-Driven Development, Plugin Architecture, Multi-Version Support, Configuration as Code, Type-Safe Code Generation.

Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.