kysely-org/kysely

A type-safe TypeScript SQL query builder

13,626 stars TypeScript 8 components 6 connections

Type-safe TypeScript SQL query builder with multi-database support

Query building flows from fluent API through AST compilation to database execution with type information preserved throughout.

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

Structural Verdict

A 8-component library with 6 connections. 472 files analyzed. Well-connected — clear data flow between components.

How Data Flows Through the System

Query building flows from fluent API through AST compilation to database execution with type information preserved throughout.

Query Construction — Type-safe query builders create operation node AST
SQL Compilation — Dialect-specific compilers generate SQL strings from operation nodes
Parameter Binding — Raw SQL expressions and parameters are safely bound
Query Execution — Compiled queries executed through database connections
Result Mapping — Database results mapped back to TypeScript types

System Behavior

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

Data Pools

Connection Pool (database)
Manages database connection lifecycle and pooling

Query Cache (cache)
Caches compiled SQL strings to avoid recompilation

Feedback Loops

Type Inference Loop (recursive, reinforcing) — Trigger: Query builder method calls. Action: TypeScript compiler refines return types based on query structure. Exit: Final query execution or compilation.
Connection Retry (retry, balancing) — Trigger: Database connection failures. Action: Attempts reconnection with exponential backoff. Exit: Successful connection or max retries reached.

Delays & Async Processing

Connection Acquisition (async-processing, ~variable) — Queries wait for available connections from pool
Query Compilation (async-processing, ~milliseconds) — First-time queries experience compilation overhead before caching

Control Points

Dialect Selection (runtime-toggle) — Controls: SQL generation strategy and database-specific behavior. Default: null
Connection Pool Size (threshold) — Controls: Maximum concurrent database connections. Default: null

Package Structure

This monorepo contains 3 packages:

kysely (library)
The main Kysely library providing type-safe SQL query building capabilities with dialect adapters for multiple databases.

kysely-site (app)
Docusaurus-based documentation website with interactive examples and feature showcase.

kysely-cloudflare-workers-test (tooling)
Test suite for validating Kysely compatibility with Cloudflare Workers runtime environment.

Technology Stack

TypeScript (framework)
Primary language with advanced type system usage

Mocha (testing)
Test framework for unit and integration tests

PostgreSQL (database)
Primary SQL database for testing and examples

SQLite (database)
Lightweight database for testing and examples

Docusaurus (framework)
Documentation site generator

ESBuild (build)
Fast JavaScript bundler for builds

Key Components

Kysely (class) — Main database interface providing query creation methods and transaction management src/kysely.ts
SelectQueryBuilder (class) — Fluent interface for building SELECT queries with type-safe column and table references src/query-builder/select-query-builder.ts
PostgresDialect (class) — PostgreSQL-specific SQL generation and database introspection capabilities src/dialect/postgres/postgres-dialect.ts
ExpressionBuilder (class) — Type-safe builder for SQL expressions like functions, operators, and subqueries src/expression/expression-builder.ts
DefaultQueryExecutor (class) — Executes compiled queries through database connections with streaming support src/query-executor/default-query-executor.ts
OperationNode (type-def) — Abstract syntax tree representation of SQL operations for compilation src/operation-node/operation-node.ts
sql (function) — Template tag function for creating raw SQL expressions with parameter binding src/raw-builder/sql.ts
Schema (class) — Schema management for creating and altering database tables, indexes, and types src/schema/schema.ts

Configuration

docker-compose.yml (yaml)

services.mssql.image (string, unknown) — default: mcr.microsoft.com/mssql/server:2022-latest
services.mssql.ports (array, unknown) — default: 21433:1433
services.mssql.environment.ACCEPT_EULA (string, unknown) — default: Y
services.mssql.environment.MSSQL_PID (string, unknown) — default: Express
services.mssql.environment.SA_PASSWORD (string, unknown) — default: KyselyTest0
services.mssql.healthcheck.test (string, unknown) — default: /opt/mssql-tools/bin/sqlcmd -S mssql -U sa -P 'KyselyTest0' -Q 'select 1'
services.waitmssql.image (string, unknown) — default: mcr.microsoft.com/mssql/server:2017-latest
services.waitmssql.links (array, unknown) — default: mssql
+14 more parameters

pnpm-workspace.yaml (yaml)

packages (array, unknown) — default: ./site,./test/cloudflare-workers
allowBuilds.better-sqlite3@12.8.0 (boolean, unknown) — default: true
allowBuilds.core-js (boolean, unknown) — default: false
allowBuilds.core-js-pure (boolean, unknown) — default: false
allowBuilds.esbuild@0.27.4 (boolean, unknown) — default: true
allowBuilds.sharp (boolean, unknown) — default: false
allowBuilds.workerd@1.20260317.1 (boolean, unknown) — default: true
blockExoticSubdeps (boolean, unknown) — default: true
+8 more parameters

deno.check.json (json)

$schema (string, unknown) — default: https://deno.land/x/deno/cli/schemas/config-file.v1.json
compilerOptions.types (array, unknown) — default: ./deno.check.d.ts
imports.better-sqlite3 (string, unknown) — default: npm:better-sqlite3
imports.kysely (string, unknown) — default: ./dist/esm
imports.kysely/helpers/mssql (string, unknown) — default: ./dist/esm/helpers/mssql.js
imports.kysely/helpers/mysql (string, unknown) — default: ./dist/esm/helpers/mysql.js
imports.kysely/helpers/postgres (string, unknown) — default: ./dist/esm/helpers/postgres.js
imports.kysely/helpers/sqlite (string, unknown) — default: ./dist/esm/helpers/sqlite.js
+7 more parameters

deno.lint.json (json)

$schema (string, unknown) — default: https://deno.land/x/deno/cli/schemas/config-file.v1.json
lint.rules.tags (array, unknown) — default: jsr

Explore the interactive analysis

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

Analyze on CodeSea

Related Library Repositories

Frequently Asked Questions

What is kysely used for?

Type-safe TypeScript SQL query builder with multi-database support kysely-org/kysely is a 8-component library written in TypeScript. Well-connected — clear data flow between components. The codebase contains 472 files.

How is kysely architected?

kysely is organized into 4 architecture layers: API Layer, Compilation Layer, Dialect Layer, Execution Layer. Well-connected — clear data flow between components. This layered structure enables tight integration between components.

How does data flow through kysely?

Data moves through 5 stages: Query Construction → SQL Compilation → Parameter Binding → Query Execution → Result Mapping. Query building flows from fluent API through AST compilation to database execution with type information preserved throughout. This pipeline design reflects a complex multi-stage processing system.

What technologies does kysely use?

The core stack includes TypeScript (Primary language with advanced type system usage), Mocha (Test framework for unit and integration tests), PostgreSQL (Primary SQL database for testing and examples), SQLite (Lightweight database for testing and examples), Docusaurus (Documentation site generator), ESBuild (Fast JavaScript bundler for builds). A focused set of dependencies that keeps the build manageable.

What system dynamics does kysely have?

kysely exhibits 2 data pools (Connection Pool, Query Cache), 2 feedback loops, 2 control points, 2 delays. The feedback loops handle recursive and retry. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does kysely use?

4 design patterns detected: Fluent Builder, Visitor Pattern, Dialect Adapter, Template Tag.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.