Kysely: A Type-Safe SQL Query Builder for TypeScript Projects

The Problem: SQL Without Type Safety

Writing raw SQL in TypeScript is error-prone. Typos in column names surface only at runtime. Result rows come back as untyped objects, so you manually cast or guess shapes. Kysely solves this by making the query builder aware of your database schema at compile time. It is aimed at developers who want the flexibility of SQL but with the safety net of TypeScript's type checker. The README describes it as a type-safe and autocompletion-friendly TypeScript SQL query builder, inspired by Knex. This is not an ORM; it does not map objects to tables. It builds SQL strings with types attached, so you keep control over the SQL while gaining editor help and compile-time validation.

How Kysely Achieves Type Safety

The core mechanism is TypeScript's type system. Kysely defines types for your tables and columns, and the query builder methods are typed to only accept valid references. For example, when you write a select on a table, the result type is inferred from the selected columns, including aliases. The README highlights a specific feature: if you alias pet.name as pet_name, Kysely can parse that alias and add pet_name to the result row type. This inference extends to subqueries, joined subqueries, and with statements. The type system does the heavy lifting at compile time, so there is no runtime overhead for type checking. The library also offers escape hatches for cases where types cannot be inferred, such as the sql template tag and the DynamicModule. These are important because not every query fits the static type model.

Getting Started: Installation and Dialects

The README points to the documentation site for getting started, with dialect-specific guides for PostgreSQL, MySQL, MSSQL, SQLite, and pglite. Installation is via npm or JSR, as the package is published on both npm and jsr.io. For a typical Node.js project, you would install kysely and a database driver, then create a Kysely instance with a dialect. The exact commands are not in the README, but the documentation site provides them. The dialect abstraction is key: it allows Kysely to run on multiple environments, from Node.js to Cloudflare Workers, because the dialect handles the connection specifics. The README lists Deno, Bun, Cloudflare Workers, and web browsers as supported environments.

Escape Hatches for Dynamic SQL

Not everything can be typed at compile time. Kysely acknowledges this with two escape hatches: the sql template tag and the DynamicModule. The sql template tag lets you embed raw SQL fragments when the type system cannot express what you need. This is useful for database-specific functions or complex expressions. The DynamicModule, with its ref method, allows you to reference tables or columns dynamically, such as when building queries from user input or configuration. These escape hatches are not afterthoughts; they are essential for real-world usage. Without them, you would be forced to cast types or use raw queries, defeating the purpose of type safety. The trade-off is that these features shift some type checking back to runtime, so you lose compile-time guarantees in those spots.

Limitations and When It Is the Wrong Tool

Kysely's type safety depends on having a well-defined schema. If your database schema is not known at compile time, or if you generate queries dynamically from untyped sources, the type system becomes a hindrance rather than a help. The escape hatches exist, but using them extensively means you are bypassing the main benefit. Also, Kysely is not an ORM; it will not handle relationships. For developers who want object-relational mapping, a tool like Prisma might be more appropriate. Another limitation is that the type inference is complex, and as the README hints, there are cases where things cannot be typed. If you need to write highly dynamic SQL, such as a reporting tool with arbitrary filters, Kysely may force you into awkward type gymnastics.

Alternative: Knex.js and the Difference

Kysely is inspired by Knex.js, and the README lists Tim Griesser, credited for Knex, among its honorable mentions. Knex is a mature SQL query builder that has been around for years. The README does not compare the two in detail; its emphasis is that Kysely only lets you refer to tables and columns visible to the part of the query you are writing, and infers result columns, aliases and types. If you are already using Knex and are happy with runtime error checking, switching to Kysely requires adopting TypeScript's type system more deeply. For teams that are not ready for that, Knex remains a solid choice. Kysely's advantage is that it catches typos and type mismatches before you run the query, which can save debugging time.

Maintenance and License

Kysely is licensed under MIT, which is permissive and allows commercial use with attribution. The project is actively maintained, with v0.29.8 released on 2026-11-01 and v0.28.19 released the same day for the 0.28 line. The core team includes the original author and a co-maintainer, with a list of honorable mentions. The repository is not archived, indicating ongoing development. You should check the release notes before upgrading. The documentation is comprehensive, with API docs in the typing files and a hosted version, which helps with maintenance.

Editorial conclusion

Adopt Kysely if you are a TypeScript developer building on Node.js, Deno, Bun, Cloudflare Workers, or browsers and you want compile-time checking for your SQL queries without a full ORM. Avoid it if you need dynamic SQL generation without type constraints or if you prefer a query builder that does not force strict schema typing. Before adopting, verify that your database dialect is supported and that the escape hatches (sql template tag, DynamicModule) cover your dynamic query needs, as the type system has limits.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes