虚谷 NodeJS 开发手册

📄字数 4.7K

👁️阅读量加载中...

XuguDB-NodeJS 驱动用于满足用户通过 NodeJS 完成对虚谷数据库服务的访问需求。目前支持 NodeJS 16.x.x 和 NodeJS 20.x.x。

一、开发环境搭建

1.1 获取软件包

1.1.1 产品包获取

XuguDB-NodeJS 驱动压缩包在虚谷数据库的产品包内，解压产品包后，XuguDB-NodeJS 驱动路径为：Driver/NodeJS。不同操作系统和 CPU 架构的 XuguDB-NodeJS 驱动，需要通过下载不同的产品包获取。

1.1.2 单独获取

我们提供在线下载链接，可以获取最新试用版和稳定版本的 XuguDB-NodeJS 驱动。

操作系统	CPU	下载地址
Windows	x86, 64-bit	下载
Linux	x86, 64-bit	下载
Linux	ARM, 64-bit	下载

提示

Windows 版本建议在 Windows 10 及以上系统使用。
Linux 版本可以在所有对应的 CPU 架构的类 Unix 系统下运行。
如果有在其它系统上使用虚谷 XuguDB-NodeJS 驱动的需求，请联系虚谷。

1.2 添加依赖

将下载的软件包解压将得到 xugudbjs.node 和 xugusql.dll，拷贝文件至 NodeJS 项目目录并保证两个文件在同级目录，使用 require("./xugudbjs") 将其导入。

二、快速入门

2.1 导入依赖

将所依赖的软件 xugudbjs.node 和 xugusql.dll 放入项目中，使用 require 将 xugudbjs.node 导入。此模块的导出对象中含有名为 createConnection 的方法，此方法用于创建 XGConnection。

const xugu = require("./xugudbjs");

2.2 创建连接

创建连接需要使用模块导出对象中的 createConnection 方法，此方法用于创建连接对象。在创建连接对象时，通过参数传入连接信息以及数据库的登录信息，最后使用连接对象的 connect 方法登录数据库。

let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA;char_set=utf8");
conn.connect();

2.3 执行语句

成功登录数据库后即可执行 SQL 语句。执行 SQL 语句使用 query 方法，此方法的第一个参数即为被执行的 SQL 语句，可执行 DML、DDL 和 DQL。详细用法参考接口参考中的 query 方法说明。

conn.query("INSERT INTO tab_test(id, name, created) VALUES(1, '张三', '2000-01-01')");

2.4 关闭连接

连接对象使用完毕后，需关闭连接以释放相关资源，所使用的方法为 disconnect。

conn.disconnect();

2.5 完整代码

const xugu = require("./xugudbjs");
let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA;char_set=utf8");
try {
    conn.connect();
} catch (err) {
    console.log(err);
    return;
}

let sql = "CREATE TABLE tab_test(id INT, name VARCHAR(20), created DATE)";
conn.query(sql, (err) => {
    if(err != null) console.log(err);
});

sql = "INSERT INTO tab_test(id, name, created) VALUES(1, '张三', '2000-01-01')";
conn.query(sql, (err) => {
    if(err != null) console.log(err);
});

sql = "SELECT * FROM tab_test";
conn.query(sql, (err, results, fields) => {
    if(err != null) 
        console.log(err);
    else
        console.log(results);
});
conn.disconnect();

三、接口参考

3.1 导出对象

3.1.1 createConnection

功能

创建数据库连接。

原型

createConnection(connectInfo);

参数

connectInfo：分号分隔的键值连接信息
- ip：数据库的 IP 地址
- port：数据库的端口
- database：连接的库名
- user：登录数据库的用户名
- pwd：用户名对应的密码
- char_set：字符集

返回值

XGConnection 对象。

说明

此方法仅创建 XGConnection 对象，不进行数据库的连接和登录，因此无法通过此方法判断连接信息是否有误。

示例

const xugu = require("./xugudbjs");
let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA;char_set=utf8");

3.2 XGConnection 类

3.2.1 connect

功能

连接数据库。

原型

connect();

参数

无

说明

连接数据库失败，则抛出异常。在得到 XGConnection 对象后，connect 应为第一个被调用的方法。

示例

const xugu = require("./xugudbjs");
let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA;char_set=utf8");
conn.connect();

3.2.2 disconnect

功能

断开数据库连接。

原型

disconnect();

参数

无

说明

断开连接后，可使用 connect 重新连接。

示例

const xugu = require("./xugudbjs");
let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA");
conn.connect();
conn.disconnect();

3.2.3 end

功能

销毁当前对象。

原型

end();

参数

无

说明

调用 end 方法后，当前对象中的资源被释放，数据库连接被断开，无法再使用 connect 方法重新连接，对象不再可用。

示例

const xugu = require("./xugudbjs");
let conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA");
conn.connect();
conn.disconnect();
conn.end();

3.2.4 query

功能

执行 SQL 语句。

原型

query(sql[, params][, callback]);

function callback(err, results, fields);

参数

sql：执行的 SQL 语句
params：SQL 参数
callback：回调函数，参数为
- err：执行 SQL 语句产生的错误信息
- results：查询的数据
- fields：查询的列信息

返回值

未传入回调函数时，返回 XGQuery 对象。传入回调函数时，无返回值。

说明

当 SQL 语句中含有用问号作为数据占位符的参数时，使用 param 参数传入实际数值，param 为数组类型，参数顺序与 SQL 语句中的问号顺序一致。获取执行结果可使用传入回调函数或接收返回值，当传入回调函数时，query 方法无返回值。

示例

conn.query("select * from tab_test where id = ?", [1], (err, results, fields) => {
    console.log(err);     //错误信息
    console.log(results); //数据
    console.log(fields);  //列信息
});

3.2.5 beginTransaction

功能

开启事务。

原型

beginTransaction();

参数

无

示例

conn.connect();
conn.beginTransaction();

3.2.6 commit

功能

提交事务。

原型

commit();

参数

无

示例

conn.connect();
conn.beginTransaction();
/* execute some DMLs here */
conn.commit();

3.2.7 rollback

功能

回滚事务。

原型

rollback();

参数

无

示例

conn.connect();
conn.beginTransaction();
/* execute some DMLs here */
conn.rollback();

3.3 XGQuery 类

3.3.1 on

功能

使用回调获取查询结果。

原型

on(type, callback);

参数

type：字符串，取值为：error、result 或 fields
callback：一个参数的回调函数，参数与 type 对应

示例

let query = conn.query("SELECT * FROM tab_test");
query.on("result", (row) => console.log(row));

3.3.2 nextRecord

功能

获取下一行.

原型

nextRecord(type, callback);

参数

type：字符串类型，取值 nextrecord
callback：一个参数的回调函数，参数为行数据

说明

若通过获取 XGQuery 对象获取并遍历结果集，则需要通过此方法不断获取下一行以实现遍历。获取当前行的数据，可通过回调函数取得，也可使用 on 方法取得。

示例

let query = conn.query("SELECT * FROM tab_test");
query.nextRecord("nextrecord", (row) => console.log(row));

四、示例

4.1 创建连接

const xugu = require("./xugudbjs");
const conn = xugu.createConnection("IP=127.0.0.1;Port=5138;Database=SYSTEM;USER=SYSDBA;PWD=SYSDBA");
conn.connect();

/* execute SQL */

conn.disconnect();

4.2 执行 DDL 语句

function createTable(conn) {
    let sql = "CREATE TABLE tab_test(id INT, name VARCHAR(20), created DATE, lob BLOB)";
    conn.query(sql, (err) => {
        if(err != null) console.log(err);
    });
}

4.3 执行 DML 语句

function insert(conn) {
    let sql = "INSERT INTO tab_test id, name, created VALUES(1, 'Tom', '2000-01-01')";
    conn.query(sql, (err) => {
        if(err != null) console.log(err);
    });
}

4.4 执行带参数的 DML 语句

function insertWithParam(conn) {
    let sql = "INSERT INTO tab_test id, name, created VALUES(?, ?, ?)";
    conn.query(sql, [2, "Jerry", "2000-01-02"], (err) => {
        if(err != null) console.log(err);
    });
}

4.5 执行查询

示例 1

function query(conn) {
    let sql = "SELECT id, name, created FROM tab_test WHERE id = ?";
    conn.query(sql, [1], (err, results, fields) => {
        if(err != null)
            console.log(err);
        else
            console.log(results);
    });
}

示例 2

function query(conn) {
    let sql = "SELECT id, name, created FROM tab_test WHERE id = ?";
    let query = conn.query(sql, [1]);
    query.on("error", (err) => {
        if(err != null) {
            console.log(err);
            return;
        }
    });
    query.nextRecord("nextrecord", function(row) {
        console.log(row);
    });
}

示例 3

function query(conn) {
    let sql = "SELECT id, name, created FROM tab_test WHERE id = ?";
    let query = conn.query(sql, [1]);
    query.on("error", (err) => {
        if(err != null) {
            console.log(err);
            return;
        }
    });
    query.on("result", (row) => console.log(row));
}

4.6 插入 Lob

function insertLob(conn) {
    const fs = require("fs");

    let buf = fs.readFileSync("blob.png");
    conn.query("INSERT INTO tab_test (id, lob) VALUES(?, ?)", [3, buf]);
}

虚谷 NodeJS 开发手册 ​

一、开发环境搭建 ​

1.1 获取软件包 ​

1.1.1 产品包获取 ​

1.1.2 单独获取 ​

1.2 添加依赖 ​

二、快速入门 ​

2.1 导入依赖 ​

2.2 创建连接 ​

2.3 执行语句 ​

2.4 关闭连接 ​

2.5 完整代码 ​

三、接口参考 ​

3.1 导出对象 ​

3.1.1 createConnection ​

3.2 XGConnection 类 ​

3.2.1 connect ​

3.2.2 disconnect ​

3.2.3 end ​

3.2.4 query ​

3.2.5 beginTransaction ​

3.2.6 commit ​

3.2.7 rollback ​

3.3 XGQuery 类 ​

3.3.1 on ​

3.3.2 nextRecord ​

四、示例 ​

4.1 创建连接 ​

4.2 执行 DDL 语句 ​

4.3 执行 DML 语句 ​

4.4 执行带参数的 DML 语句 ​

4.5 执行查询 ​

4.6 插入 Lob ​