# @matrixai/db

> DB

Latest version **6.0.22** (published 2025-05-01) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @matrixai/db
pnpm add @matrixai/db
yarn add @matrixai/db
bun add @matrixai/db
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; large bundle.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.22 |
| Published | 2025-05-01 |
| First published | 2021-09-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Node | ^20.5.1 |
| Dependencies | 7 |
| Unpacked size | 23.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 7 |
| Author | Roger Qiu |
| Maintainers | brianbotha74, cmcdragonkai, matrixai-bot |

## Links

- npm: https://www.npmjs.com/package/@matrixai/db
- Repository: https://github.com/MatrixAI/js-db
- Homepage: https://github.com/MatrixAI/js-db#readme
- Issues: https://github.com/MatrixAI/js-db/issues
- npm.io page: https://npm.io/package/@matrixai/db

## Dependencies (7)

- [node-gyp-build](https://npm.io/package/node-gyp-build.md) 4.4.0
- [@matrixai/errors](https://npm.io/package/@matrixai/errors.md) ^2.0.1
- [@matrixai/logger](https://npm.io/package/@matrixai/logger.md) ^4.0.1
- [@matrixai/workers](https://npm.io/package/@matrixai/workers.md) ^2.0.1
- [@matrixai/resources](https://npm.io/package/@matrixai/resources.md) ^2.0.0
- [@matrixai/async-init](https://npm.io/package/@matrixai/async-init.md) ^2.0.0
- [@matrixai/async-locks](https://npm.io/package/@matrixai/async-locks.md) ^5.0.1

## Recent versions

- 6.0.22 (latest) — 2025-05-01
- 6.0.21 — 2025-03-27
- 6.0.20 — 2025-03-26
- 5.3.0 — 2023-09-13
- 5.2.1 — 2023-07-08
- 5.2.0 — 2023-06-26
- 5.1.0 — 2022-11-23
- 5.0.3 — 2022-08-21
- 5.0.2 — 2022-08-19
- 5.0.1 — 2022-07-22
- 5.0.0 — 2022-07-14
- 4.0.5 — 2022-05-31
- 4.0.4 — 2022-05-31
- 4.0.2 — 2022-05-31
- 4.0.1 — 2022-05-26
- … 23 more at https://npm.io/package/@matrixai/db/versions

## README

# js-db

DB is library managing key value state for MatrixAI's JavaScript/TypeScript applications.

This forks classic-level's C++ binding code around LevelDB 1.20. Differences from classic-level:

* Uses TypeScript from ground-up
* Supports Snapshot-Isolation based transactions via `DBTransaction`
* API supports "key paths" which can be used to manipulate "levels" of nested keys
* Value encryption (key-encryption is not supported yet) - requires additional work with block-encryption
* Uses RocksDB

## Installation

```sh
npm install --save @matrixai/db
```

## Usage

```ts
import { DB } from '@matrixai/db';

async function main () {

  const key = Buffer.from([
    0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x02, 0x03,
    0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x02, 0x03,
  ]);

  const encrypt = async (
    key: ArrayBuffer,
    plainText: ArrayBuffer
  ): Promise<ArrayBuffer> => {
    return plainText;
  };

  const decrypt = async (
    key: ArrayBuffer,
    cipherText: ArrayBuffer
  ): Promise<ArrayBuffer | undefined> => {
    return cipherText;
  }

  const db = await DB.createDB({
    dbPath: './tmp/db',
    crypto: {
      key,
      ops: { encrypt, decrypt },
    },
    fresh: true,
  });

  await db.put(['level', Buffer.from([0x30, 0x30]), 'a'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x31]), 'b'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x32]), 'c'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x33]), 'c'], 'value');

  console.log(await db.get(['level', Buffer.from([0x30, 0x32]), 'c']));

  await db.del(['level', Buffer.from([0x30, 0x32]), 'c']);

  for await (const [kP, v] of db.iterator(
    ['level'],
    {
      lt: [Buffer.from([0x30, 0x32]), ''],
    })) {
    console.log(kP, v);
  }

  await db.stop();
}

main();
```

If you created the `DB` with a `crypto` object, then upon restarting the `DB`, you must pass in the same `crypto` object.

## Development

This project uses Git submodules to bring in rocksdb. **Make sure to clone recursively.**

If you already cloned, run this:

```sh
git submodule update --init --recursive
```

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

## Benchmarks

```sh
npm run bench
```

View benchmarks here: https://github.com/MatrixAI/js-db/blob/master/benches/results with https://raw.githack.com/

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-db/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

---
_Source: https://npm.io/package/@matrixai/db · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._