# kes-node

**Repository Path**: king-db/kes-node

## Basic Information

- **Project Name**: kes-node
- **Description**: 金仓数据库 KingbaseES 的 Node.js 驱动是一些 Node.js 模块的集合，用于与 KingbaseES 数据库的交互。

通过 Node.js 驱动，应用程序可以完成与数据库的连接、执行 SQL 语句、从数据库中获取结果、获取状态及错误信息、终止连接等操作。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/king-db/kes-node
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-21
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KingbaseDB

面向 **KingbaseES** 的 Node.js 数据库驱动单包发行版。
通过 Nodejs 驱动，应用程序可以完成与数据库的连接、执行 SQL 语句、从数据库中获取结果、获取状态及错误信息、终止连接等操作。

## 安装

```bash
npm install kingbasedb
```

## 模块导入

### CommonJS

```js
const { Client } = require('kingbasedb')
```

### ES Module

```js
import { Client } from 'kingbasedb'
```

### 导入模块说明

官方手册示例为：

```js
const { Client } = require('kb')
```

**由于 Nodejs 驱动是多个模块(kb/kb-pool等)的集合包**，所以为了方便使用及版本管理，npm 仓库将对应模块(**kb/kb-pool等**)整合发布为一个完整的包(**kingbasedb**)。

对应导入驱动方式，与官网提供的驱动包对应手册导入方式有一定差异，可通过以下方式对齐手册的导入方式。

用 npm 别名把依赖装到 `node_modules/kb`：

```bash
npm install kb@npm:kingbasedb
```

或在 `package.json` 中：

```json
{
  "dependencies": {
    "kb": "npm:kingbasedb"
  }
}
```

添加别名后可对齐手册导入说明：

```js
// CJS
const { Client } = require('kb')
// ESM
import { Client } from 'kb'
```

`Client` 的连接参数与 `connect` / `query` / `end` 用法与手册示例相同。

## 快速开始

### CommonJS

```js
const { Client } = require('kingbasedb')
// 若已配置手册别名：const { Client } = require('kb')

async function main() {
  // 创建客户端并填写连接参数
  const client = new Client({
    host: '127.0.0.1',
    port: 54321,
    user: 'system',
    password: '******',
    database: 'test',
  })

  await client.connect() // 建立连接
  const res = await client.query('SELECT 1 AS n') // 执行 SQL
  console.log(res.rows[0]) // { n: 1 }
  await client.end() // 关闭连接
}

main().catch((err) => {
  console.error(err)
  process.exitCode = 1
})
```

### ES Module

适用于 `package.json` 含 `"type": "module"`，或文件为 `.mjs`：

```js
import { Client } from 'kingbasedb'
// 若已配置手册别名：import { Client } from 'kb'

// 创建客户端并填写连接参数
const client = new Client({
  host: '127.0.0.1',
  port: 54321,
  user: 'system',
  password: '******',
  database: 'test',
})

await client.connect() // 建立连接
const res = await client.query('SELECT 1 AS n') // 执行 SQL
console.log(res.rows[0]) // { n: 1 }
await client.end() // 关闭连接
```

### 连接池

#### CommonJS

```js
const { Pool } = require('kingbasedb')

async function main() {
  // 创建连接池；max 为最大连接数
  const pool = new Pool({
    host: '127.0.0.1',
    port: 54321,
    user: 'system',
    password: '******',
    database: 'test',
    max: 10,
  })

  // 池会自动借还连接，一般无需手动 connect
  const { rows } = await pool.query('SELECT now() AS ts')
  console.log(rows[0])
  await pool.end() // 关闭池内全部连接
}

main().catch((err) => {
  console.error(err)
  process.exitCode = 1
})
```

#### ES Module

```js
import { Pool } from 'kingbasedb'

// 创建连接池；max 为最大连接数
const pool = new Pool({
  host: '127.0.0.1',
  port: 54321,
  user: 'system',
  password: '******',
  database: 'test',
  max: 10,
})

// 池会自动借还连接，无需手动 connect
const { rows } = await pool.query('SELECT now() AS ts')
console.log(rows[0])
await pool.end() // 关闭池内全部连接
```

也可用连接串：

```js
// 用 URI 代替逐项 host/port/user 等参数
const pool = new Pool({
  connectionString: 'kingbase://system:******@127.0.0.1:54321/test',
})
```

## 导出与子路径

根导出提供：

- `Client`、`Pool`、`Connection`、`Query`、`Result`
- `types`、`TypeOverrides`、`DatabaseError`
- `escapeIdentifier`、`escapeLiteral`、`defaults`
- `Cursor`、`QueryStream`

子路径：

```js
// CJS
const Cursor = require('kingbasedb/cursor')
const QueryStream = require('kingbasedb/query-stream')
const Pool = require('kingbasedb/pool')

// ESM
import Cursor from 'kingbasedb/cursor'
import QueryStream from 'kingbasedb/query-stream'
import Pool from 'kingbasedb/pool'
```

| 子路径                       | 说明             |
| ------------------------- | -------------- |
| `kingbasedb`              | 主入口（CJS / ESM） |
| `kingbasedb/cursor`       | 服务端游标          |
| `kingbasedb/query-stream` | 查询结果流          |
| `kingbasedb/pool`         | 连接池实现          |

### Cursor 示例

ES Module：

```js
import { Client, Cursor } from 'kingbasedb'

const client = new Client({
  host: '127.0.0.1',
  port: 54321,
  user: 'system',
  password: '******',
  database: 'test',
})
await client.connect()

// 创建服务端游标，适合大结果集分批读取
const cursor = client.query(new Cursor('SELECT generate_series(1, 10) AS n'))
const rows = await cursor.read(10) // 一次读取最多 10 行（返回 Promise）
console.log(rows)
// [
//   { n: 1 }, { n: 2 }, ... { n: 10 }
// ]

await cursor.close() // 关闭游标
await client.end()
```

### QueryStream 示例

ES Module：

```js
import { Client, QueryStream } from 'kingbasedb'

const client = new Client({
  host: '127.0.0.1',
  port: 54321,
  user: 'system',
  password: '******',
  database: 'test',
})
await client.connect()

// 以流的方式读取查询结果，边读边处理
const stream = client.query(new QueryStream('SELECT generate_series(1, 5) AS n'))
// 异步迭代，每有一行数据就进入循环体一次
for await (const row of stream) {
  console.log(row)
}
// { n: 1 } ... { n: 5 }

await client.end()
```

## Native

**当前版本为纯 JavaScript 发布，暂不支持使用 libkci 的连接方式 KES 数据库**

## 包内结构

```
kingbasedb/
  LICENSE
  README.md
  package.json
  index.js               # CJS 入口
  index.mjs              # ESM 入口
  packages/
    kb/                  # 核心客户端
    kb-pool/
    kb-protocol/
    kb-connection-string/
    kb-cursor/
    kb-query-stream/
  vendor/
    kb-types/            # 类型解析
    kbpass/              # 密码文件支持
```