# Kysely

[Kysely](https://kysely.dev/) 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](/guides/introduction-2-postgres) and start querying your database with full type safety.

## [Prerequisites](#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](#1-create-a-new-project)

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

:::code-group
```title="bun"
mkdir kysely-quickstart

cd kysely-quickstart

bun init
```

```bash title="pnpm"
mkdir kysely-quickstart
cd kysely-quickstart
pnpm init
```

```bash title="yarn"
mkdir kysely-quickstart
cd kysely-quickstart
yarn init
```

```bash title="npm"
mkdir kysely-quickstart
cd kysely-quickstart
npm init
```
:::

Install TypeScript and initialize it:

:::code-group
```title="bun"
bun add --dev typescript
```

```bash title="pnpm"
pnpm add --save-dev typescript
```

```bash title="yarn"
yarn add --dev typescript
```

```bash title="npm"
npm install --save-dev typescript
```
:::

:::code-group
```title="bun"
bunx tsc --init
```

```bash title="pnpm"
pnpm tsc --init
```

```bash title="yarn"
yarn tsc --init
```

```bash title="npm"
npx tsc --init
```
:::

## [2. Configure TypeScript](#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

    // ...

  }

  // ...

}
```

:::callout{intent="note"}
The `strict: true` setting is **required** for Kysely's type safety to work correctly.
:::

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

```
{

  // ...

  "type": "module"

  // ...

}
```

## [3. Create a Prisma Postgres database](#3-create-a-prisma-postgres-database)

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

:::code-group
```title="bun"
bunx create-db
```

```bash title="pnpm"
pnpm dlx create-db
```

```bash title="yarn"
yarn dlx create-db
```

```bash title="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"
```

:::callout{intent="warning"}
**Never commit `.env` files to version control.** Add `.env` to your `.gitignore` file to keep credentials secure.
:::

The database created is temporary and will be deleted in 24 hours unless claimed. Claiming moves the database into your [Prisma Data Platform](https://console.prisma.io/?utm_source=docs\&utm_medium=content\&utm_content=%28index%29) account. Visit the claim URL from the output to keep your database.

:::callout{intent="note"}
To learn more about the `create-db` CLI tool, see the [create-db documentation](/guides/introduction-2-postgres-npx-create-db).
:::

## [4. Install dependencies](#4-install-dependencies)

Install Kysely and the PostgreSQL driver:

:::code-group
```title="bun"
bun add kysely pg dotenv
```

```bash title="pnpm"
pnpm add kysely pg dotenv
```

```bash title="yarn"
yarn add kysely pg dotenv
```

```bash title="npm"
npm install kysely pg dotenv
```
:::

:::code-group
```title="bun"
bun add --dev @types/pg tsx
```

```bash title="pnpm"
pnpm add --save-dev @types/pg tsx
```

```bash title="yarn"
yarn add --dev @types/pg tsx
```

```bash title="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](#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](#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](#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:

:::code-group
```title="bun"
bunx tsx src/script.ts
```

```bash title="pnpm"
pnpm dlx tsx src/script.ts
```

```bash title="yarn"
yarn dlx tsx src/script.ts
```

```bash title="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](#next-steps)

Kysely is now connected to Prisma Postgres. For schemas, migrations, and more complex queries, see the [Kysely documentation](https://kysely.dev/docs/intro).

:::callout{intent="note"}
Deploy to Compute

To run this app in the cloud, deploy it to [Prisma Compute](/guides/deploy-compute), which runs your app next to your Prisma Postgres database. Follow [Deploy your first app](/guides/start-prisma-compute-deploy).
:::

## Related pages

- [Authentication & Tools](./authentication-tools-index.md)
- [Build](./build-index.md)
- [Changelog](../changelog.md)
- [Concepts](./concepts-index.md)
- [Console commands](./console-commands-index.md)
- [Contract Authoring](./contract-authoring-index.md)
- [Core Concepts](./core-concepts-index.md)
- [Data Modeling](./data-modeling-index.md)
- [Database](./database-index.md)
- [DB commands](./db-commands-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.