Kysely

Kysely is a type-safe TypeScript SQL query builder that provides TypeScript support and a fluent API for building SQL queries. In this guide, you'll learn how to connect Kysely to Prisma Postgres and start querying your database with full type safety.

Prerequisites

Node.js version 14 or higher
TypeScript version 4.6 or higher (5.4+ recommended for improved type inference, 5.9+ for better compilation performance)
Strict mode enabled in your tsconfig.json for Kysely's type safety

1. Create a new project

Create a new directory for your project and initialize it with npm:

title="bun"

mkdir kysely-quickstart

cd kysely-quickstart

bun init

pnpm

mkdir kysely-quickstart
cd kysely-quickstart
pnpm init

yarn

mkdir kysely-quickstart
cd kysely-quickstart
yarn init

npm

mkdir kysely-quickstart
cd kysely-quickstart
npm init

Install TypeScript and initialize it:

title="bun"

bun add --dev typescript

pnpm

pnpm add --save-dev typescript

yarn

yarn add --dev typescript

npm

npm install --save-dev typescript

title="bun"

bunx tsc --init

pnpm

pnpm tsc --init

yarn

yarn tsc --init

npm

npx tsc --init

2. Configure TypeScript

Kysely requires TypeScript's strict mode for proper type safety. Update your tsconfig.json file:

title="tsconfig.json"

{

  // ...

  "compilerOptions": {

    // ...

    "strict": true, 

    "allowImportingTsExtensions": true, 

    "noEmit": true

    // ...

  }

  // ...

}

In your package.json, set the type to module:

{

  // ...

  "type": "module"

  // ...

}

3. Create a Prisma Postgres database

Create a Prisma Postgres database with the create-db CLI tool:

title="bun"

bunx create-db

pnpm

pnpm dlx create-db

yarn

yarn dlx create-db

npm

npx create-db

Then the CLI tool should output:

┌  🚀 Creating a Prisma Postgres database

│

│  Provisioning a temporary database in us-east-1...

│

│  It will be automatically deleted in 24 hours, but you can claim it.

│

◇  Database created successfully!

│

│

●  Database Connection

│

│

│    Connection String:

│

│    postgresql://hostname:password@db.prisma.io:5432/postgres?sslmode=require

│

│

◆  Claim Your Database

│

│    Keep your database for free:

│

│    https://create-db.prisma.io/claim?CLAIM_CODE

│

│    Database will be deleted on 11/18/2025, 1:55:39 AM if not claimed.

│

└

Create a .env file and add the connection string from the output:

title=".env"

DATABASE_URL="postgresql://hostname:password@db.prisma.io:5432/postgres?sslmode=require"

The database created is temporary and will be deleted in 24 hours unless claimed. Claiming moves the database into your Prisma Data Platform account. Visit the claim URL from the output to keep your database.

4. Install dependencies

Install Kysely and the PostgreSQL driver:

title="bun"

bun add kysely pg dotenv

pnpm

pnpm add kysely pg dotenv

yarn

yarn add kysely pg dotenv

npm

npm install kysely pg dotenv

title="bun"

bun add --dev @types/pg tsx

pnpm

pnpm add --save-dev @types/pg tsx

yarn

yarn add --dev @types/pg tsx

npm

npm install --save-dev @types/pg tsx

Package breakdown:

kysely: The type-safe SQL query builder
pg: PostgreSQL driver for Node.js (required by Kysely's PostgresDialect)
dotenv: Loads environment variables from .env file
@types/pg: TypeScript type definitions for the pg driver
tsx: TypeScript execution engine for running .ts files directly

5. Define database types

Create a src/types.ts file to define your database schema types:

title="src/types.ts"

import type { Generated } from "kysely";

export interface Database {

  users: UsersTable;

}

export interface UsersTable {

  id: Generated<number>;

  email: string;

  name: string | null;

}

6. Configure database connection

Create a src/database.ts file to instantiate Kysely with your Prisma Postgres connection:

title="src/database.ts"

import "dotenv/config";

import type { Database } from "./types.ts";

import { Pool } from "pg";

import { Kysely, PostgresDialect } from "kysely";

// Parse DATABASE_URL into connection parameters

function parseConnectionString(url: string) {

  const parsed = new URL(url);

  return {

    host: parsed.hostname,

    port: parseInt(parsed.port),

    user: parsed.username,

    password: parsed.password,

    database: parsed.pathname.slice(1), // Remove leading '/'

  };

}

const connectionParams = parseConnectionString(process.env.DATABASE_URL!);

const dialect = new PostgresDialect({

  pool: new Pool({

    ...connectionParams,

    ssl: true,

    max: 10,

  }),

});

// Database interface is passed to Kysely's constructor, and from now on, Kysely

// knows your database structure.

// Dialect is passed to Kysely's constructor, and from now on, Kysely knows how

// to communicate with your database.

export const db = new Kysely<Database>({

  dialect,

});

7. Run queries

Create a src/script.ts file:

title="src/script.ts"

import { db } from "./database.ts";

async function main() {

  // Create the users table

  await db.schema

    .createTable("users")

    .ifNotExists()

    .addColumn("id", "serial", (col) => col.primaryKey())

    .addColumn("email", "varchar(255)", (col) => col.notNull().unique())

    .addColumn("name", "varchar(255)")

    .execute();

  // Insert a user

  const user = await db

    .insertInto("users")

    .values({

      email: "alice@prisma.io",

      name: "Alice",

    })

    .returningAll()

    .executeTakeFirstOrThrow();

  console.log("Created user:", user);

  // Query all users

  const users = await db.selectFrom("users").selectAll().execute();

  console.log("All users:", users);

}

main()

  .then(async () => {

    await db.destroy();

  })

  .catch(async (error) => {

    console.error("Error:", error);

    await db.destroy();

    process.exit(1);

  });

Run the script:

title="bun"

bunx tsx src/script.ts

pnpm

pnpm dlx tsx src/script.ts

yarn

yarn dlx tsx src/script.ts

npm

npx tsx src/script.ts

You should receive the following output:

Created user: { id: 1, email: 'alice@prisma.io', name: 'Alice' }

All users: [ { id: 1, email: 'alice@prisma.io', name: 'Alice' } ]

Next steps

Kysely is now connected to Prisma Postgres. For schemas, migrations, and more complex queries, see the Kysely documentation.