CozoDB for Node.js

Common errors

• Error: No precompiled binaries for your platform.

  cause The `cozo-node` package could not find a prebuilt native binary matching your system's operating system, architecture, or Node.js version.
  fix Install a Rust toolchain (`rustup.rs`) and then try installing the package with `npm install --build-from-source cozo-node` or by following the manual build steps in the README.

• TypeError: (0, _cozoNode.CozoDb) is not a constructor

  cause This error typically occurs when trying to use a default import for `CozoDb`, which is a named export, or incorrect CommonJS `require` syntax.
  fix For ES Modules, use `import { CozoDb } from 'cozo-node';`. For CommonJS, use destructuring: `const { CozoDb } = require('cozo-node');`.

• Database operation failed: <error message>

  cause A Datalog query or database operation encountered a runtime error specific to CozoDB's internal logic, often due to malformed queries or data constraints.
  fix Examine the `err.display` or `err.message` property for specific CozoDB error details. Review your Datalog script and parameters for syntax, relation existence, and data consistency.

Warnings

• gotcha Failure to call `db.close()` on a CozoDb instance will lead to native resource leaks and may prevent the Node.js process from exiting cleanly.
  Fix: Always ensure `db.close()` is called for every `CozoDb` instance when it's no longer needed, typically within a `finally` block or a resource cleanup hook.
• gotcha Precompiled binaries for `cozo-node` may not be available for all operating systems, architectures, or Node.js versions.
  Fix: If `npm install` fails with a binary-related error, you may need to compile the package from source. This requires a Rust toolchain. Refer to the 'Building' section in the package's README for detailed instructions.
• gotcha The `importRelations` and `importRelationsFromBackup` methods bypass triggers; any triggers defined on the imported relations will not be executed during these operations.
  Fix: If trigger activation is essential for imported data, use regular Datalog queries with parameters for data insertion, as these will correctly activate any associated triggers.
• gotcha The `restore` method is designed for initializing an empty database; it will fail if the current database instance already contains any data.
  Fix: Ensure the `CozoDb` instance is newly created or completely empty before attempting a `restore` operation. For existing databases, consider using `importRelationsFromBackup` if specific relations need to be merged.

Install

• npm install cozo-node npm
• yarn add cozo-node yarn
• pnpm add cozo-node pnpm

Imports

• CozoDb
  wrong:

  import CozoDb from 'cozo-node';

  correct:

  import { CozoDb } from 'cozo-node';

  This is the preferred ES Module import for TypeScript and modern JavaScript environments. CozoDb is a named export.
• CozoDb
  wrong:

  const CozoDb = require('cozo-node');

  correct:

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

  This is the correct CommonJS `require` pattern. The module exports CozoDb as a named property.
• * as CozoNode

  import * as CozoNode from 'cozo-node';

  Imports the entire module's exports into a namespace object. You would then access the class as `CozoNode.CozoDb`.

Quickstart

This quickstart demonstrates how to initialize an in-memory CozoDb instance, perform basic data insertion, query data with and without parameters, and execute more complex Datalog queries with relations, ensuring proper database closure.

import { CozoDb } from 'cozo-node';

async function main() {
    const db = new CozoDb('mem'); // Use 'mem' for in-memory, 'sqlite' for persistent storage
    try {
        console.log('Inserting initial data...');
        await db.run("?[] <- [['hello', 'world!'], ['cozo', 'database']]");

        console.log('Querying all data...');
        const result1 = await db.run("?[a, b] <- [[a, b]]");
        console.log("Result of '?[a, b] <- [[a, b]]':", result1);

        console.log('Querying with parameters...');
        const result2 = await db.run("?[message] <- [['hello', $name]]", { "name": "JavaScript" });
        console.log("Result of '?[message] <- [['hello', $name]]':", result2);

        console.log('Creating and querying a relation...');
        await db.run(`
            :create parent {child, parent}
            :insert parent <- [['Alice', 'Bob'], ['Bob', 'Charlie']]
        `);
        const ancestors = await db.run(`
            ?[ancestor] := parent{child, parent}, ancestor = parent
            :union
            ?[ancestor] := parent{child, intermediate}, ancestor_rec{intermediate, ancestor}
        `, { child: 'Alice' });
        console.log("Ancestors of Alice:", ancestors);

    } catch (err: any) {
        console.error("Database operation failed:", err.display || err.message);
    } finally {
        console.log("Closing database connection.");
        db.close();
        console.log("Database connection closed.");
    }
}

main();