kysely-org/kysely

A type-safe TypeScript SQL query builder

How Data Flows Through the System

Kysely processes queries through three distinct phases: First, developers use fluent TypeScript APIs (SelectQueryBuilder, InsertQueryBuilder, etc.) which create an abstract syntax tree of OperationNode objects capturing query structure without database-specific syntax. Next, the DefaultQueryCompiler traverses this AST using dialect-specific visitors to generate SQL strings with parameter placeholders. Finally, the DefaultQueryExecutor acquires database connections, binds parameters, executes the SQL, and maps results back to TypeScript types based on the original schema definitions.

1. Query Construction — Developer chains method calls on QueryBuilder instances (db.selectFrom('users').select(['name', 'email']).where('active', '=', true)) which progressively build OperationNode trees while TypeScript tracks column types and table relationships [DatabaseSchema types → OperationNode]
2. AST Compilation — DefaultQueryCompiler.compileQuery() walks the OperationNode tree using visitSelectQuery, visitWhereClause, etc. methods that delegate to dialect-specific implementations to generate SQL strings with parameter placeholders [OperationNode → CompiledQuery]
3. Query Execution — DefaultQueryExecutor.executeQuery() acquires a connection from the connection provider, calls connection.executeQuery() with the compiled SQL and parameters, then processes the raw database results [CompiledQuery → QueryResult]
4. Result Transformation — QueryResult.rows are mapped back to TypeScript types using the original schema information captured during query building, ensuring type safety end-to-end [QueryResult → typed result objects]

Data Models

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

Hidden Assumptions

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

System Behavior

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

Data Pools

Feedback Loops

• Transaction Retry (retry, balancing) — Trigger: Transaction serialization failure or deadlock detection. Action: DefaultQueryExecutor.executeQuery() catches database errors and re-executes the entire transaction block. Exit: Transaction succeeds or max retry count exceeded.
• Connection Recovery (circuit-breaker, balancing) — Trigger: Database connection failure or timeout. Action: Connection providers mark connections as failed and attempt to establish new ones. Exit: Connection successfully established or permanent failure declared.

Delays

• Connection Acquisition (async-processing, ~Variable based on pool availability) — Query execution waits for available connection from pool before proceeding
• Compilation Caching (cache-ttl) — First execution of query pattern incurs compilation overhead, subsequent executions use cached result

Control Points

• Dialect Selection (architecture-switch) — Controls: Which SQL syntax, query compiler, and database driver are used for all operations
• Connection Pool Size (runtime-toggle) — Controls: Maximum concurrent database connections and query throughput capacity. Default: Driver-dependent defaults
• Query Logging (feature-flag) — Controls: Whether compiled SQL queries and parameters are logged for debugging

Technology Stack

Key Components

• Kysely (orchestrator) — Main entry point that coordinates query building, compilation, and execution while maintaining transaction boundaries and connection management src/kysely.ts
• SelectQueryBuilder (processor) — Fluent API for building SELECT queries with progressive type narrowing that tracks selected columns, joins, and filtering src/query-builder/select-query-builder.ts
• DefaultQueryCompiler (transformer) — Converts operation node AST into SQL strings using visitor pattern traversal with dialect-specific customization points src/query-compiler/default-query-compiler.ts
• OperationNodeVisitor (processor) — Base visitor class that traverses operation node trees, allowing dialects to override specific node handling for SQL generation src/operation-node/operation-node-visitor.ts
• PostgresDialect (adapter) — PostgreSQL-specific implementation providing query compiler, introspector, and driver integration for Postgres syntax and features src/dialect/postgres/postgres-dialect.ts
• DefaultQueryExecutor (executor) — Manages query execution lifecycle including connection acquisition, parameter binding, result streaming, and transaction coordination src/query-executor/default-query-executor.ts
• QueryBuilder (factory) — Base class for all query builders providing common functionality like raw SQL integration and operation node management src/query-builder/query-builder.ts
• SchemaBuilder (processor) — Provides DDL operations for creating, altering, and dropping database schema objects with type-safe column definitions src/schema/schema.ts
• DatabaseConnection (gateway) — Abstract interface over actual database connections providing consistent API for query execution across different drivers src/driver/database-connection.ts
• ExpressionBuilder (processor) — Creates type-safe SQL expressions, function calls, and operators while maintaining column type information through TypeScript generics src/expression/expression-builder.ts

Package Structure

Related Library Repositories

Frequently Asked Questions

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