Skip to main content

Encryption & key rotation

LioranDB encrypts documents at rest when an encryption key is configured on the manager.

Setting the encryption key​

Provide encryptionKey when creating a LioranManager:

  • string: hashed internally into a fixed-length key
  • Buffer: must be 32 bytes

If you lose the key, encrypted data cannot be decrypted.

Example: enable encryption (string key)​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  rootPath: "./.liorandb",
  encryptionKey: "dev-secret-change-me",
});

const db = await manager.db("app");
await db.collection("secrets").insertOne({ note: "hello" });
await manager.close();
Sandbox output (example)
(no output)

Document size limit (encrypted)​

Encrypted documents are stored as JSON and must be at most 5,000,000 characters (about 5MB). Larger documents throw:

Error: Document too large (>5MB)

Rotating keys​

db.rotateEncryptionKey(newKey) re-encrypts:

  • every collection document (all collections on disk), and
  • the WAL records

Use rotation for:

  • incident response
  • planned key rollover
  • changing environments (dev -> prod)

Example: rotate to a new key​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  rootPath: "./.liorandb",
  encryptionKey: "old-key",
});

const db = await manager.db("app");
await db.rotateEncryptionKey("new-key");
await manager.close();
Sandbox output (example)
(no output)