cozo-lib-nodejs

cozo-node

Embedded CozoDB for NodeJS.

This document describes how to set up the Cozo module for use in NodeJS. To learn how to use CozoDB (CozoScript), read the docs.

Installation

npm install --save cozo-node

If that doesn't work because there are no precompiled binaries for your platform, scroll below to the building section.

Usage

const {CozoDb} = require('cozo-node')

const db = new CozoDb()

function printQuery(query, params = {}) {
    return 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, b] <- [[1, 2]]")

Basic API

class CozoDb {
    /**
     * Constructor
     * 
     * @param engine:  defaults to 'mem', the in-memory non-persistent engine.
     *                 'sqlite', 'rocksdb' and maybe others are available,
     *                 depending on compile time flags.
     * @param path:    path to store the data on disk, defaults to 'data.db',
     *                 may not be applicable for some engines such as 'mem'
     * @param options: defaults to {}, ignored by all the engines in the published NodeJS artefact
     */
    constructor(engine: string, path: string, options: object): CozoDb;

    /**
     * You must call this method for any database you no longer want to use:
     * otherwise the native resources associated with it may linger for as
     * long as your program runs. Simply `delete` the variable is not enough.
     */
    close(): void;

    /**
     * Runs a query
     * 
     * @param script: the query
     * @param params: the parameters as key-value pairs, defaults to {}
     */
    async run(script: string, params: object): object;

    /**
     * Export several relations
     * 
     * @param relations:  names of relations to export, in an array.
     */
    async exportRelations(relations: Array<string>): object;

    /**
     * Import several relations.
     * 
     * Note that triggers are _not_ run for the relations, if any exists.
     * If you need to activate triggers, use queries with parameters.
     * 
     * @param data: in the same form as returned by `exportRelations`. The relations
     *              must already exist in the database.
     */
    async importRelations(data: object): object;

    /**
     * Backup database
     * 
     * @param path: path to file to store the backup.
     */
    async backup(path: string): object;

    /**
     * Restore from a backup. Will fail if the current database already contains data.
     * 
     * @param path: path to the backup file.
     */
    async restore(path: string): object;

    /**
     * Import several relations from a backup. The relations must already exist in the database.
     * 
     * Note that triggers are _not_ run for the relations, if any exists.
     * If you need to activate triggers, use queries with parameters.
     * 
     * @param path: path to the backup file.
     * @param rels: the relations to import.
     */
    async importRelationsFromBackup(path: string, rels: Array<string>): object;
}

More information are here.

Advanced API

There are API for multi-statement transactions, mutation callbacks and implementing custom fixed rules for NodeJS, much like the Python counterpart. If you are interested, look at this example.

Building

Building cozo-node requires a Rust toolchain. Run

cargo build --release -p cozo-node -F compact -F storage-rocksdb

and then find the dynamic library (names can vary a lot, the file extension is .so on Linux, .dylib on Mac, and .dll on Windows) under the ../target/ folder (you may need to search for it). Copy it to the file native/6/cozo_node_prebuilt.node under this directory (create intermediate directories if they don't exist).

If you did everything correctly, you should get the hello world message printed out when you run

node example.js

under this directory.