Node-Kingbase

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

安装

npm install kingbasedb

模块导入

CommonJS

const { Client } = require('kingbasedb')

ES Module

import { Client } from 'kingbasedb'

导入模块说明

官方手册示例为：

const { Client } = require('kb')

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

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

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

npm install kb@npm:kingbasedb

或在 package.json 中：

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

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

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

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

快速开始

CommonJS

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：

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

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

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() // 关闭池内全部连接

也可用连接串：

// 用 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

子路径：

// 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：

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：

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/              # 密码文件支持