Required dependencies

npm install kysely
# Choose exactly one driver package that matches your dialect:
npm install pg                  # PostgreSQL
npm install mysql2              # MySQL
npm install better-sqlite3      # SQLite (sync)
npm install tedious             # MSSQL

No native build steps are required for kysely itself. better-sqlite3 requires a native build; ensure you have node-gyp prerequisites (Python, C++ compiler) or use a prebuilt binary.

Project setup

1. Copy the source/ directory into your project, e.g. src/kysely-source/, or simply install the upstream package user@example.com and import from it directly - the source is identical.

2. Configure tsconfig.json for strict mode and module resolution:

{
  "compilerOptions": {
    "strict": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020",
    "esModuleInterop": true
  }
}

3. If importing from the local source/ copy instead of the npm package, add a path alias:

{
  "compilerOptions": {
    "paths": {
      "kysely": ["./src/kysely-source/index.ts"]
    }
  }
}

4. Define your database schema as a TypeScript interface (see examples below). No env vars are required by Kysely itself; pass connection credentials directly to the dialect config.

5. Instantiate Kysely once at application startup, share the instance, and call db.destroy() on shutdown.

Public API

Kysely

import { Kysely, PostgresDialect } from 'kysely'

const db = new Kysely<Database>({
  dialect: new PostgresDialect({ pool }),
  log: ['query', 'error'],
})

The root class that ties together a dialect, connection pool, plugins, and logging. Create a single shared instance per process. Use db.transaction().execute(trx => ...) for transactions and db.withSchema('schema_name') to scope queries to a non-default schema.

QueryCreator

import { QueryCreator } from 'kysely'

// Accessed via db.selectFrom / db.insertInto / db.updateTable / db.deleteFrom
const query = db.selectFrom('person').selectAll()

QueryCreator is the base class behind Kysely that provides selectFrom, insertInto, updateTable, deleteFrom, and mergeInto. You rarely instantiate it directly; interact with it through the Kysely instance.

sql (raw builder tag)

import { sql } from 'kysely'

const fragment = sql<string>`now()`
const withParam = sql`${sql.literal('active')}::text`

A tagged template literal that produces a RawBuilder / Sql fragment for embedding raw SQL safely inside typed queries. Use it when Kysely's typed API does not cover a database-specific expression. Values passed as interpolations are parameterized automatically unless wrapped in sql.literal or sql.id.

expressionBuilder

import { expressionBuilder } from 'kysely'

const eb = expressionBuilder<Database, 'person'>()
const expr = eb('age', '>', 18)

A standalone factory returning an ExpressionBuilder outside of a query chain. Useful for extracting reusable where-clause fragments into helper functions.

Working examples

Scenario - Basic select with a join

Connect to PostgreSQL and select typed rows from joined tables.

import { Kysely, PostgresDialect } from 'kysely'
import { Pool } from 'pg'

interface Database {
  person: { id: number; name: string; age: number }
  pet: { id: number; owner_id: number; name: string; species: string }
}

const db = new Kysely<Database>({
  dialect: new PostgresDialect({ pool: new Pool({ connectionString: process.env.DATABASE_URL }) }),
})

async function getPeopleWithPets() {
  return db
    .selectFrom('person')
    .innerJoin('pet', 'pet.owner_id', 'person.id')
    .select(['person.name', 'pet.name as pet_name', 'person.age'])
    .where('person.age', '>', 18)
    .orderBy('person.name', 'asc')
    .execute()
}
// Return type: { name: string; pet_name: string; age: number }[]

Scenario - Insert with returning

Insert a row into PostgreSQL and retrieve the generated primary key.

async function createPerson(db: Kysely<Database>, name: string, age: number) {
  const result = await db
    .insertInto('person')
    .values({ name, age })
    .returning(['id', 'name'])
    .executeTakeFirstOrThrow()

  return result // { id: number; name: string }
}

Scenario - Transaction with rollback

Run multiple writes atomically; any thrown error triggers an automatic rollback.

import { sql } from 'kysely'

async function transferOwnership(
  db: Kysely<Database>,
  petId: number,
  newOwnerId: number,
) {
  await db.transaction().execute(async (trx) => {
    await trx
      .updateTable('pet')
      .set({ owner_id: newOwnerId })
      .where('id', '=', petId)
      .execute()

    await sql`SELECT pg_sleep(0)`.execute(trx) // arbitrary raw SQL in transaction
  })
}

Scenario - Schema migration

Create a table using the DDL schema builder and run migrations.

import { Kysely, Migrator, FileMigrationProvider } from 'kysely'
import * as path from 'path'
import * as fs from 'fs/promises'

async function migrateToLatest(db: Kysely<any>) {
  const migrator = new Migrator({
    db,
    provider: new FileMigrationProvider({
      fs,
      path,
      migrationFolder: path.join(__dirname, 'migrations'),
    }),
  })

  const { error, results } = await migrator.migrateToLatest()
  results?.forEach((r) => console.log(r.migrationName, r.status))
  if (error) throw error
}

File walkthrough

• index.ts - Single barrel export; import everything public from here.
• kysely.ts - Defines the Kysely<DB> class: initialization, transactions, withSchema, destroy.
• query-creator.ts - QueryCreator<DB>: selectFrom, insertInto, updateTable, deleteFrom, mergeInto, with (CTEs).
• dialect/ - Each subdirectory (postgres/, mysql/, sqlite/, mssql/) contains a dialect class, driver, introspector, adapter, and query compiler. Implement the Dialect interface to add a custom database.
• driver/ - Driver, DatabaseConnection, ConnectionProvider interfaces plus RuntimeDriver (lifecycle management) and SingleConnectionProvider (used by transactions).
• dynamic/ - DynamicModule.ref() for column references that are unknown at compile time.
• expression/ - Expression<T> interface, ExpressionBuilder, and ExpressionWrapper - the glue between typed queries and raw nodes.
• helpers/ - Dialect-specific convenience functions (e.g., jsonArrayFrom for PostgreSQL).
• migration/ - Migrator orchestrates up/down migrations; FileMigrationProvider loads .ts/.js files from a directory.
• operation-node/ - Immutable AST node definitions for every SQL construct; not consumed directly by application code.
• parser/ - Converts user-facing TypeScript values (strings, objects, callbacks) into operation nodes; internal use only.
• plugin/ - KyselyPlugin interface (transformQuery / transformResult) and WithSchemaPlugin. Implement the interface to intercept all queries.
• query-builder/ - The builder classes: SelectQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder, DeleteQueryBuilder, MergeQueryBuilder, JoinBuilder, CaseBuilder, AggregateFunctionBuilder, FunctionModule, result types (InsertResult, UpdateResult, DeleteResult, MergeResult).
• query-compiler/ - DefaultQueryCompiler walks the AST and emits SQL + parameters; CompiledQuery is the output.
• query-executor/ - DefaultQueryExecutor sends CompiledQuery to the driver and returns QueryResult; NoopQueryExecutor for testing.
• raw-builder/ - sql template tag, RawBuilder, and the Sql interface.
• schema/ - DDL builders: CreateTableBuilder, ColumnDefinitionBuilder, CreateIndexBuilder, CreateTypeBuilder, and their drop counterparts.
• util/ - Internal helpers (freeze, isObject, logging, type utilities). Not part of the public API.

Common pitfalls and fixes

• ESM / CJS interop: Kysely ships .js extensions on all internal imports; if bundling with CommonJS set "module": "CommonJS" in tsconfig or use a bundler that handles .js re-exports. Fix: use "moduleResolution": "NodeNext" with "module": "NodeNext".
• Missing pg types: @types/pg must be installed separately alongside pg. Fix: npm install --save-dev @types/pg.
• better-sqlite3 native build failures: requires Python and a C++ compiler. Fix: npm install --save-dev @types/better-sqlite3 and ensure build tools are present, or use npm install better-sqlite3 --ignore-scripts with a prebuilt binary.
• Forgetting await on .execute(): query builders are lazy; not awaiting silently discards the query. Fix: always await or use void explicitly if fire-and-forget is intended.
• Transaction isolation level not supported: passing isolationLevel or accessMode to dialects that don't support them throws at runtime. Fix: check dialect-specific docs; MSSQL and SQLite support subsets of isolation levels.
• Type widening with dynamic.ref(): using DynamicModule.ref() drops column-level type safety. Fix: use it only as a last resort and add runtime validation on the result shape.

Vibe-coding prompt template

I have the Kysely TypeScript SQL query builder source in `source/` and a usage
guide in `USAGE.md`. The upstream package is `user@example.com`.

My project is a Node.js + TypeScript + Express REST API using PostgreSQL.

Please do the following step by step:
1. Read `USAGE.md` and `source/index.ts` to understand all public exports.
2. Define a `Database` interface in `src/db/types.ts` that maps my existing
   table names and columns (I will list them below).
3. Create `src/db/index.ts` that instantiates a single shared `Kysely<Database>`
   using `PostgresDialect` with a `pg.Pool` configured from `process.env.DATABASE_URL`.
4. Create a `src/db/migrations/` folder and write an initial migration file using
   `CreateTableBuilder` from `source/schema/create-table-builder.ts`.
5. Wire `Migrator` and `FileMigrationProvider` in a `src/db/migrate.ts` script
   runnable via `ts-node src/db/migrate.ts`.
6. Write typed repository functions (select, insert, update, delete) for my main
   entity table using the query builder methods shown in `USAGE.md`.
7. Show how to wrap multiple writes in a transaction using `db.transaction().execute()`.

My tables: [PASTE YOUR SCHEMA HERE]

License and credit

Kysely is released under the MIT License. See the LICENSE file in the upstream repository or source/LICENSE if present.

Upstream package: kysely on npm - source repository at github.com/kysely-org/kysely.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.