Registry / database / cozo-node

cozo-node

JSON →
library0.7.6jsnpmunverified

Cozo-node is a Node.js binding for CozoDB, an embedded Datalog and graph database. It provides direct native access to CozoDB's capabilities, allowing developers to embed a powerful, relational-like database engine directly within their Node.js applications. The current stable version is 0.7.6, with recent minor releases indicating active development. Cozo-node differentiates itself by offering various storage engines, including in-memory ('mem'), SQLite, and RocksDB (depending on compile-time flags), enabling flexible persistence options. It exposes a simple API for running Datalog queries, managing relations, and handling database backups and restores. While primarily accessed via JavaScript/TypeScript, its underlying implementation is in Rust, providing high performance and low-level control. This library is suitable for applications requiring an embedded, queryable knowledge base or a lightweight graph database solution.

npm install cozo-node
INSTALL
IMPORT
SIG · COZO-NODE
C
cozo-node
databasejavascriptv0.7.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CozoDb
✓ import { CozoDb } from 'cozo-node';
✗ import CozoDb from 'cozo-node';
This is the preferred ES Module import for TypeScript and modern JavaScript environments. CozoDb is a named export.
CozoDb
✓ const { CozoDb } = require('cozo-node');
✗ 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`.

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();
Debug
Known issues
gotchaFailure 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.
affects: >=0.4.0
gotchaPrecompiled 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.
affects: >=0.4.0
gotchaThe `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.
affects: >=0.4.0
gotchaThe `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.
affects: >=0.4.0
Errors
Common errors & fixes
Error: No precompiled binaries for your platform.
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
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>
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.
Upgrade
Version history
0.7.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
1
Resources
cozo-node — npm install cozo-node · libregistry