|
|
# Cozo NodeJS 库
|
|
|
|
|
|
[](https://www.npmjs.com/package/cozo-node)
|
|
|
|
|
|
NodeJS 的嵌入式 [CozoDB](https://www.cozodb.org) 库。
|
|
|
|
|
|
本文叙述的是如何安装设置库本身。有关如何使用 CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
```bash
|
|
|
npm install --save cozo-node
|
|
|
```
|
|
|
|
|
|
安装过程中需要从 [GitHub 发布页](https://github.com/cozodb/cozo-lib-nodejs/releases/) 下载二进制文件。如果因为网络问题失败，可以使用此 [镜像](https://github.com/cozodb/cozo-lib-nodejs/releases/) ，使用方法为
|
|
|
|
|
|
```bash
|
|
|
npm install --save cozo-node --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/
|
|
|
```
|
|
|
|
|
|
注意：如果你用的是 Yarn 而不是 NPM，类似的命令 [可能不奏效](https://github.com/mapbox/node-pre-gyp/issues/514) 。
|
|
|
|
|
|
如果你的操作系统、平台不是常见的平台，可能会报错说找不到预编译库。这种情况下可以参见后面关于如何从源码编译的内容。
|
|
|
|
|
|
## 用法
|
|
|
|
|
|
```javascript
|
|
|
const {CozoDb} = require('cozo-node')
|
|
|
|
|
|
const db = new CozoDb()
|
|
|
|
|
|
function printQuery(query, params) {
|
|
|
db.run(query, params)
|
|
|
.then(data => console.log(data))
|
|
|
.catch(err => console.error(err.display || err.message))
|
|
|
}
|
|
|
|
|
|
printQuery("?[] <- [['hello', 'world!']]")
|
|
|
printQuery("?[] <- [['hello', 'world', $name]]", {"name": "JavaScript"})
|
|
|
printQuery("?[a] <- [[1, 2]]")
|
|
|
```
|
|
|
|
|
|
### 基本 API
|
|
|
|
|
|
```ts
|
|
|
class CozoDb {
|
|
|
/**
|
|
|
* 构造函数
|
|
|
*
|
|
|
* @param engine: 默认为 'mem'，即纯内存的非持久化存储。其他值可以是 'sqlite'、'rocksdb' 等
|
|
|
* @param path: 存储文件或文件夹的路径，默认为 'data.db'。在 'mem' 引擎下无用。
|
|
|
* @param options: 默认为 {}，在 NodeJS 支持的引擎中无用。
|
|
|
*/
|
|
|
constructor(engine: string, path: string, options: object): CozoDb;
|
|
|
|
|
|
/**
|
|
|
* 关闭数据库，并释放其原生资源。如果不调用此方法而直接删除数据库的变量，则会造成原生资源泄漏。
|
|
|
*/
|
|
|
close(): void;
|
|
|
|
|
|
/**
|
|
|
* 执行查询文本
|
|
|
*
|
|
|
* @param script: 查询文本
|
|
|
* @param params: 传入的参数，默认为 {}
|
|
|
*/
|
|
|
async run(script: string, params: object): object;
|
|
|
|
|
|
/**
|
|
|
* 导出存储表
|
|
|
*
|
|
|
* @param relations: 需要导出的存储表名称
|
|
|
*/
|
|
|
async exportRelations(relations: Array<string>): object;
|
|
|
|
|
|
/**
|
|
|
* 导入数据至存储表
|
|
|
*
|
|
|
* 注意：以此方法导入数据不会激活存储表上任何的触发器。
|
|
|
*
|
|
|
* @param data: 导入的表以及数据，格式与 `exportRelations` 返回的相同
|
|
|
*/
|
|
|
async importRelations(data: object): object;
|
|
|
|
|
|
/**
|
|
|
* 备份数据库
|
|
|
*
|
|
|
* @param path: 备份文件路径
|
|
|
*/
|
|
|
async backup(path: string): object;
|
|
|
|
|
|
/**
|
|
|
* 从备份文件恢复数据至当前数据库。若当前数据库非空，则报错。
|
|
|
*
|
|
|
* @param path: 备份文件路径
|
|
|
*/
|
|
|
async restore(path: string): object;
|
|
|
|
|
|
/**
|
|
|
* 将备份文件中指定存储表里的数据插入当前数据库中同名表里。
|
|
|
*
|
|
|
* 注意：以此方法导入数据不会激活存储表上任何的触发器。
|
|
|
*
|
|
|
* @param path: 备份文件路径
|
|
|
* @param rels: 需导入数据的表名
|
|
|
*/
|
|
|
async importRelationsFromBackup(path: string, rels: Array<string>): object;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。
|
|
|
|
|
|
### 进阶 API
|
|
|
|
|
|
Cozo 支持多语句事务、存储表更新时回调以及使用 NodeJS 实现自定义固定规则，与 [Python 库](https://github.com/cozodb/pycozo) （[国内镜像](https://gitee.com/cozodb/pycozo)）所支持的差不多。可参考此 [示例](./example.js)。
|
|
|
|
|
|
## 编译
|
|
|
|
|
|
编译 `cozo-node` 需要 [Rust 工具链](https://rustup.rs)。运行
|
|
|
|
|
|
```bash
|
|
|
cargo build --release -p cozo-node -F compact -F storage-rocksdb
|
|
|
```
|
|
|
|
|
|
完成后，动态链接库可以在 `../target/` 文件夹中找到（具体文件名根据平台与操作系统会有差异，一般来说 Linux 上 扩展名为 `.so`，Mac 上为 `.dylib`，Windows 上为 `.dll`）。
|
|
|
将找到的动态库拷贝为此目录下的 `native/6/cozo_node_prebuilt.node` 文件（中间目录若不存在，则需建立）。
|
|
|
|
|
|
如果一切操作正确，在此目录下执行下列命令则会正常返回：
|
|
|
|
|
|
```bash
|
|
|
node example.js
|
|
|
``` |