将 Kysely 与 ClickHouse Managed Postgres 搭配使用

Kysely 是一个面向 TypeScript 的类型安全 SQL 查询构建器。在本指南中，您将通过 pg 驱动程序，在启用 TLS 证书验证的情况下将 Kysely 连接到 ClickHouse Managed Postgres，借助 Kysely 迁移创建表，并用 Node.js 搭建一个小型待办事项 API。

前置条件

Node.js 22.18 或更高版本，可直接运行 TypeScript 文件，无需构建步骤。本指南中的文件使用 .mts 扩展名，因此无论是 CommonJS 项目还是 ES 模块项目，Node.js 都会将其视为 ES 模块。
一个 ClickHouse Cloud 账户。
psql，用于创建数据库。也可以在 SQL 控制台中运行 CREATE DATABASE 语句。
curl，用于调用 API。

本指南已在 Node.js 24.21、Kysely 0.29.6、pg 8.23.1、TypeScript 7.0.2 和 PostgreSQL 18 环境下测试通过。

创建 ClickHouse Managed Postgres 服务

在 ClickHouse Cloud 控制台中，点击 New service，然后选择 Postgres。实例会在几分钟内准备就绪。详细操作步骤请参阅快速入门。

获取连接信息

在服务的左侧边栏中点击 Connect。保持选中 Directly，并开启 Use SSL：此时 url 连接字符串会以 sslmode=verify-full&sslrootcert=... 结尾。点击 Download CA certificate 下载服务的 CA 证书 (文件名为 <service-name>-ca-certificate.pem) ，然后复制该连接字符串。本指南直接连接到 Postgres 的 5432 端口，原因有二：

Node.js 服务器是长期运行的进程。pg 的 Pool 本身就会保持少量连接处于打开状态并加以复用，因此服务端连接池器带来的收益不大。
Kysely 的 Migrator 在执行迁移期间会持有一个会话级咨询锁 (pg_advisory_lock) 。PgBouncer 以事务池模式运行，因此获取锁、执行迁移和释放锁这几步操作可能分别落在不同的后端连接上。如果经由 PgBouncer 连接，该锁可能会一直被某个池化连接持有，导致后续的迁移因等待该锁而阻塞。

如果之后需要运行大量应用实例或无服务器函数，可以将应用的连接字符串指向 PgBouncer (主机不变，端口为 6432) 。由于 pg 默认使用未命名的预处理语句，Kysely 搭配 pg 可以在事务池模式下正常工作。但迁移仍应通过 5432 端口执行。请参阅 PgBouncer 连接池。

设置项目

创建一个项目，并安装 Kysely、pg 驱动程序和 TypeScript：

mkdir kysely-todo && cd kysely-todo
npm init -y
npm install kysely pg
npm install --save-dev typescript @types/node @types/pg
npm pkg set scripts.migrate="node --env-file=.env src/migrate.mts" scripts.start="node --env-file=.env src/server.mts" scripts.typecheck="tsc"
mkdir src migrations

要集成到现有应用中？请跳过 mkdir kysely-todo && cd kysely-todo 和 npm init -y。在你的项目中运行以下命令 (这些命令会添加 migrate 和 typecheck 脚本，但不会改动现有的 start 脚本) ，然后继续配置连接。

npm install kysely pg
npm install --save-dev typescript @types/node @types/pg
npm pkg set scripts.migrate="node --env-file=.env src/migrate.mts" scripts.typecheck="tsc"
mkdir -p src migrations

配置连接

将下载的 CA 证书移至项目目录，并重命名为 ca-certificate.pem。然后为该应用创建一个数据库：

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_kysely;"

CREATE DATABASE

将复制的连接字符串添加到新建的 .env 文件或现有的 .env 文件中。将 <PASSWORD> 替换为您的密码，将数据库名称替换为 guide_kysely，并将 sslrootcert 设置为 ca-certificate.pem：

.env

DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_kysely?sslmode=verify-full&sslrootcert=ca-certificate.pem"

pg 会从连接字符串中读取 sslmode 和 sslrootcert：verify-full 会让它校验服务器证书是否由您服务的 CA 签发，以及证书是否与主机名匹配。sslrootcert 按相对于工作目录的路径解析；使用 npm run 时，工作目录即为项目根目录。

请在 URL 中保留 sslmode=verify-full。如果没有 sslmode，pg 既不会使用 TLS，也不会验证服务器。也不要再向 Pool 传入 ssl 对象：当 URL 包含 sslmode 时，URL 中的设置会覆盖您的 ssl 对象。如果需要从文件以外的位置加载 CA，请从 URL 中移除 sslmode 和 sslrootcert，改为向 Pool 传入 ssl: { ca }。

添加 tsconfig.json，让 tsc 对 Node.js 所运行的文件执行类型检查。如果您的应用已有 tsconfig.json，请将以下 compilerOptions 和 migrations 文件夹合并到其中：

tsconfig.json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["src", "migrations"]
}

定义数据库接口

Kysely 依据一个描述各个表的接口，为每个查询推断类型。创建 src/db.mts，在其中定义该接口，并创建一个 Kysely 实例，该实例使用搭配 pg Pool 的 PostgresDialect：

src/db.mts

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

export interface TodoTable {
  id: Generated<number>
  title: string
  done: Generated<boolean>
  created_at: Generated<Date>
}

export interface Database {
  todo: TodoTable
}

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

Generated 用于标记由数据库自动填充的列，因此插入时可以省略这些列。

创建并运行迁移

本指南使用 Kysely 内置的 Migrator 和 FileMigrationProvider，二者均包含在核心 kysely 包中。独立的 kysely-ctl 命令行客户端是可选的，它封装的也是同一个 Migrator。创建一个迁移文件。Kysely 会按文件名的字母数字顺序依次运行迁移，因此请以日期作为文件名前缀：

migrations/2026-09-30_create_todo.mts

import { type Kysely, sql } from 'kysely'

export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('todo')
    .addColumn('id', 'integer', (col) => col.primaryKey().generatedAlwaysAsIdentity())
    .addColumn('title', 'text', (col) => col.notNull())
    .addColumn('done', 'boolean', (col) => col.notNull().defaultTo(false))
    .addColumn('created_at', 'timestamptz', (col) => col.notNull().defaultTo(sql`now()`))
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('todo').execute()
}

创建 src/migrate.mts，用于执行所有待处理的迁移。在 Kysely 0.29 中，需从 kysely/migration 导入 Migrator 和 FileMigrationProvider：

src/migrate.mts

import { promises as fs } from 'node:fs'
import path from 'node:path'
import { FileMigrationProvider, Migrator } from 'kysely/migration'
import { db } from './db.mts'

const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    path,
    migrationFolder: path.join(import.meta.dirname, '../migrations'),
  }),
})

const { error, results } = await migrator.migrateToLatest()

for (const result of results ?? []) {
  console.log(`${result.status}: ${result.migrationName}`)
}

await db.destroy()

if (error) {
  console.error('Migration failed:', error)
  process.exit(1)
}

运行迁移：

npm run migrate

Success: 2026-09-30_create_todo

Kysely 会在 kysely_migration 表中记录已应用的迁移，因此再次运行该命令不会有任何效果。

如需确认 pg 确实会验证证书，可以在不指定 sslrootcert 的情况下运行迁移。由于 Node.js 默认不信任您的服务所使用的 CA，连接将会失败：

DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_kysely?sslmode=verify-full" npm run migrate

Migration failed: Error: unable to verify the first certificate; if the root CA is installed locally, try running Node.js with --use-system-ca

查询数据库

创建 src/server.mts，这是一个小型 HTTP 服务器，使用 Kysely 对待办事项执行增删改查操作。如果是现有应用，你可以在自己的路由处理程序中使用相同的查询：

src/server.mts

import { createServer } from 'node:http'
import { json } from 'node:stream/consumers'
import { db } from './db.mts'

const port = Number(process.env.PORT ?? 3000)

const server = createServer(async (req, res) => {
  const { pathname } = new URL(req.url ?? '/', 'http://localhost')
  const id = Number(pathname.match(/^\/todos\/(\d+)$/)?.[1])

  try {
    let result: unknown

    if (req.method === 'GET' && pathname === '/todos') {
      result = await db.selectFrom('todo').selectAll().orderBy('id').execute()
    } else if (req.method === 'POST' && pathname === '/todos') {
      const { title } = (await json(req)) as { title: string }
      result = await db.insertInto('todo').values({ title }).returningAll().executeTakeFirstOrThrow()
    } else if (req.method === 'PATCH' && id) {
      const { done } = (await json(req)) as { done: boolean }
      result = await db.updateTable('todo').set({ done }).where('id', '=', id).returningAll().executeTakeFirst()
    } else if (req.method === 'DELETE' && id) {
      result = await db.deleteFrom('todo').where('id', '=', id).returningAll().executeTakeFirst()
    } else {
      res.writeHead(404).end()
      return
    }

    res.writeHead(result ? 200 : 404, { 'content-type': 'application/json' })
    res.end(JSON.stringify(result ?? { error: 'not found' }, null, 2))
  } catch (err) {
    console.error(err)
    res.writeHead(500).end()
  }
})

server.listen(port, () => console.log(`Listening on http://localhost:${port}/todos`))

由于每个查询都会依据 Database 接口进行校验，因此一旦表名或列名拼写错误，或插入时缺少必填的 title，类型检查都会失败。对项目进行检查：

npm run typecheck

验证

启动服务器：

npm start

如果是在现有应用中，npm start 运行的是你自己的应用，因此请改用 node --env-file=.env src/server.mts 来启动示例服务器。在另一个终端中，创建、更新和删除几条待办事项：

curl -X POST localhost:3000/todos -d '{"title": "Create a Managed Postgres service"}'
curl -X POST localhost:3000/todos -d '{"title": "Connect Kysely with verify-full"}'
curl -X POST localhost:3000/todos -d '{"title": "Try PgBouncer later"}'
curl -X PATCH localhost:3000/todos/1 -d '{"done": true}'
curl -X DELETE localhost:3000/todos/3

在浏览器中打开 http://localhost:3000/todos，即可查看剩余的待办事项列表。响应如下所示：

[
  {
    "id": 1,
    "title": "Create a Managed Postgres service",
    "done": true,
    "created_at": "2026-09-30T16:47:31.081Z"
  },
  {
    "id": 2,
    "title": "Connect Kysely with verify-full",
    "done": false,
    "created_at": "2026-09-30T16:47:31.142Z"
  }
]

要在控制台中查看相同的数据，请在服务的左侧边栏中打开 SQL 控制台，依次展开 guide_kysely 和 public schema，然后点击 todo 表。Kysely 创建的 kysely_migration 和 kysely_migration_lock 表也会一并列在旁边：

id	title	done	created_at
1	Create a Managed Postgres service	true	2026-09-30 16:47:31.081942+00
2	Connect Kysely with verify-full	false	2026-09-30 16:47:31.142225+00

后续步骤

连接：连接字符串、PgBouncer 和 TLS。
设置：调优 PostgreSQL 和 PgBouncer 参数，例如 max_connections。
只读副本：扩展读密集型工作负载。
Kysely 文档：连接 (join) 、事务和类型生成。

入门

功能

指南

定价

ClickHouse 集成

迁移

监控

常见问题

将 Kysely 与 ClickHouse Managed Postgres 搭配使用

前置条件

创建 ClickHouse Managed Postgres 服务

获取连接信息

设置项目

配置连接

定义数据库接口

创建并运行迁移

查询数据库

验证

后续步骤

​前置条件

​创建 ClickHouse Managed Postgres 服务

​获取连接信息

​设置项目

​配置连接

​定义数据库接口

​创建并运行迁移

​查询数据库

​验证

​后续步骤

前置条件

创建 ClickHouse Managed Postgres 服务

获取连接信息

设置项目

配置连接

定义数据库接口

创建并运行迁移

查询数据库

验证

后续步骤