将 Prisma Postgres 与 Kysely 结合使用

Kysely 是一个类型安全的 TypeScript SQL 查询构建器，它提供了 TypeScript 支持和流畅的 API 来构建 SQL 查询。在本指南中，你将学习如何将 Kysely 连接到 Prisma Postgres 并开始以完全类型安全的方式查询数据库。

先决条件

• Node.js 版本 14 或更高
• TypeScript 版本 4.6 或更高（建议 5.4+ 以获得更好的类型推断，5.9+ 以获得更好的编译性能）
• 在你的 tsconfig.json 中启用严格模式以实现 Kysely 的类型安全

1. 创建新项目

为你的项目创建一个新目录并使用 npm 初始化它

mkdir kysely-quickstart
cd kysely-quickstart
npm init -y

安装 TypeScript 并初始化它

npm install --save-dev typescript
npx tsc --init

2. 配置 TypeScript

Kysely 需要 TypeScript 的严格模式才能实现正确的类型安全。更新你的 tsconfig.json 文件

tsconfig.json

{
  // ...
  "compilerOptions": {
    // ...
    "strict": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
    // ...
  }
  // ...
}

注意

strict: true 设置是 Kysely 类型安全正常工作的必需条件。

在你的 package.json 中，将 type 设置为 module

{
// ...
"type": "module"
// ...
}

3. 创建 Prisma Postgres 数据库

您可以使用 create-db CLI 工具创建 Prisma Postgres 数据库。按照以下步骤创建您的 Prisma Postgres 数据库

npx create-db

然后 CLI 工具应该输出

┌  🚀 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.
│
└  

创建一个 .env 文件并添加输出中的连接字符串

.env

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

警告

切勿将 .env 文件提交到版本控制。 将 .env 添加到您的 .gitignore 文件中以确保凭据安全。

创建的数据库是临时的，如果未声明，将在 24 小时内删除。声明会将数据库移至您的帐户。访问输出中的声明 URL 以保留您的数据库。

注意

要了解有关 create-db CLI 工具的更多信息，请参阅 create-db 文档。

4. 安装依赖项

安装 Kysely 和 PostgreSQL 驱动程序

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

包分解

• kysely：类型安全的 SQL 查询构建器
• pg：Node.js 的 PostgreSQL 驱动程序（Kysely 的 PostgresDialect 所需）
• dotenv：从 .env 文件加载环境变量
• @types/pg：pg 驱动程序的 TypeScript 类型定义
• tsx：用于直接运行 .ts 文件的 TypeScript 执行引擎

5. 定义数据库类型

创建一个 src/types.ts 文件来定义你的数据库模式类型

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. 配置数据库连接

创建一个 src/database.ts 文件，用你的 Prisma Postgres 连接实例化 Kysely

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. 运行查询

创建一个 src/script.ts 文件

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)
  })

运行脚本

npx tsx src/script.ts

你应该会收到以下输出

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

后续步骤

你已成功将 Kysely 连接到 Prisma Postgres！有关模式、迁移和复杂查询等更高级功能，请参阅 Kysely 文档。