HyperDB

Define product collections and an index for finding products by category.

How it works

HyperDB organizes records into schema-defined collections and query indexes. Choose it when a key-value API is too low-level for your domain.

The builder generates a schema and database definition before runtime code opens the database. Both files needed for this example are included below.

This example uses the local RocksDB engine. The generated collection is not automatically replicated or multi-writer.

Run an example

Use Node 22.17+ and npm for installation. Start in a new directory for this example so its ./data storage cannot collide with another example. Save each file below with the exact filename shown, then run the commands in order.

mkdir hyperdb-demo
cd hyperdb-demo
npm init -y
npm install hyperdb@'^6.7.0' hyperschema@'^1.21.0'

Save as build.cjs:

const Hyperschema = require('hyperschema')
const Builder = require('hyperdb/builder')
const schema = Hyperschema.from('./spec/schema')
schema.namespace('notes').register({
  name: 'note', compact: true,
  fields: [
    { name: 'id', type: 'string', required: true },
    { name: 'text', type: 'string', required: true }
  ]
})
Hyperschema.toDisk(schema)
const db = Builder.from('./spec/schema', './spec/db')
db.namespace('notes').collections.register({
  name: 'note', schema: '@notes/note', key: ['id']
})
Builder.toDisk(db)

Save as example.mjs:

import HyperDB from 'hyperdb'
import definition from './spec/db/index.js'
const db = HyperDB.rocks('./data', definition)
try {
  await db.insert('@notes/note', { id: 'welcome', text: 'Hello collection' })
  await db.flush()
  console.log((await db.get('@notes/note', { id: 'welcome' })).text)
} finally {
  await db.close()
}

Run from this example directory:

node build.cjs
node example.mjs

Expected result

Hello collection

API essentials

• Builder collections.register(): define the schema and primary key used by a collection.
• HyperDB.rocks(path, definition): open a device-local engine. insert() stages records and flush() persists the changes.
• get(collection, key): retrieve a record. find() queries collections or indexes. close() releases the engine.

Troubleshooting and limits

• Cannot find ./spec/db/index.js: run node build.cjs before the runtime script.
• A record disappears after restart: check that flush() completed and the data directory is unchanged.
• Changing schemas requires an intentional migration; rebuilding a definition is not a data migration.

Next steps