First generate your definition with the builder.
The definition defines the schemas and collections you wanna use.
// build.jsconst Hyperschema = require('hyperschema')const HyperDB = require('hyperdb/builder')const SCHEMA_DIR = './spec/hyperschema' // where the schema definitions are writtenconst DB_DIR = './spec/hyperdb' // Where to install db definition// Hyperschema definitionsconst schema = Hyperschema.from(SCHEMA_DIR)const example = schema.namespace('example')// Define 'members'example.register({ name: 'members', compact: true, fields: [ { name: 'name', type: 'string', required: true }, { name: 'age', type: 'uint', required: true } ]})Hyperschema.toDisk(schema)// Hyperdb collection definitionsconst db = HyperDB.from(SCHEMA_DIR, DB_DIR)const exampleDB = db.namespace('example')// Import helpers (see next step)exampleDB.require('./helpers.js')// Define collections of structsexampleDB.collections.register({ name: 'members', schema: '@example/members', key: ['name']})// Define index over collectionexampleDB.indexes.register({ name: 'members-by-name', collection: '@example/members', unique: true, key: { type: 'string', map: 'mapNameToLowerCase' }})HyperDB.toDisk(db)
Define helper functions in helpers.js:
// helpers.jsexports.mapNameToLowerCase = (record, context) => { const name = record.name.toLowerCase().trim() return name ? [name] : []}
Run node build.js to build the spec.
Then boot your db. You can use the same definition for a fully local db and a P2P one.
// run.mjsimport HyperDB from 'hyperdb'import def from './spec/hyperdb/index.js'// first choose your engineconst db = HyperDB.rocks('./my-rocks.db', def)// Add some entriesawait db.insert('@example/members', { name: 'maf', age: 37 })await db.insert('@example/members', { name: 'sean', age: 36 })await db.flush() // commit changes// Query collectionconst maf = await db.get('@example/members', { name: 'maf'
It is that simple.
API
db = Hyperdb.bee(hypercore, definition, [options])
Make a db backed by Hyperbee. P2P!
Available options:
{ autoUpdate: false, // Whether the database should update when the underlying hyperbee does writable: true // Whether the database is writable}
For Hyperbee backed databases, the database does not update it's state when the bee updates. Setting autoUpdate to true makes this automatic. Otherwise the database can be manually updated with db.update().
db = Hyperdb.rocks(path, definition, [options])
Make a db backed by RocksDB. Local only!
Available options:
{ readOnly: false, // Whether the database be read-only writable: true // Whether the database is writable}
Insert multiple documents in parallel. Options include { type: 'delete' } which makes the batch
interpret the insert as a delete for that item.
bool = db.updated([collection], [query])
Returns a boolean indicating if this database was updated since last time it was flushed. Pass a collection and doc query to know if a specific record was updated.
const stream = db.changes(range = {})
Returns a stream of changes to the database. The range can have the
following properties:
{ gte: seq, // Start with this seq (inclusive) gt: seq, // Start after this index lte: seq, // Stop after this index lt: seq, // Stop before this index}
seq is the sequence number for the underlying Hyperbee node.
Only supported with Hyperbee engine.
const stream = db.diff(collection, query = {})
Returns a stream of { left, right } objects describing how a collection
changed between an earlier point in the database's history and the database as
it is now. left is the document as it was then, right is the document as it
is now, and either side is null when the document did not exist there:
{ from, // head to diff against, defaults to the empty database gt: { ... }, gte: { ... }, lt: { ... }, lte: { ... }, limit // how many max?}
from is a head, ie. { key, length }, as returned by db.engine.head(), the
same value db.changes({ from }) takes. It defaults to the empty database, so
db.diff(collection) streams every document as an insert.
The range is bounded to the given collection, and documents are streamed in key
order, so reverse is not supported. Diffing an index is not supported either,
since an index only sees changes that move its own keys.
Only committed state is compared, inserts and deletes that have not been flushed
yet are not included.
Only supported with the Hyperbee2 engine.
await db.flush()
Flush all changes to the db
db.watch(cb)
Register a callback to trigger when database updates.
db.unwatch(cb)
Remove watch callback.
db.reload()
Reload the internal snapshot. Clears the memory state.
db = db.snapshot()
Make a readonly snapshot of the database. All reads/streams are locked in time on a snapshot from the time you call the snapshot method.
db = db.transaction()
Make a writable snapshot of the database. All reads/streams are locked in time on a snapshot from the time you call the snapshot method.
When you flush this one, it updates the main instance also.
Warnings:
Transactions must always be closed. Flushing a transaction closes it, but when a transaction is cancelled (for example due to an error), transaction.close() has to be called explicitly.
Transactions must not be run in parallel. If you do not want to write your own locking mechanism, use await db.exclusiveTransaction() instead.
db = await db.exclusiveTransaction()
Like db.transaction(), but with a built-in lock to ensure transactions do not run concurrently.
await db.ready()
Wait for the database to fully open.
await db.close()
Close the database. You have to close any snapshots you use also.
db.closed
Whether the database has been closed.
db.writable
Whether the database can be written to.
db.readable
Whether the database can be read.
Builder API
We can define what the schema of collections and the documents they contain using the builder API. A common pattern is to create a build.js script that is run whenever the database schema changes. See the example.
The builder API can be imported via the builder subpath:
const HyperdbBuilder = require('hyperdb/builder')
const db = HyperdbBuilder.from(SCHEMA_DIR, DB_DIR)
Load a builder instance db with the hyperschema definitions (aka SCHEMA_DIR) and with existing hyperdb definitions (aka DB_DIR).
SCHEMA_DIR is either the hyperschema definition object or the directory path to load from disk.
DB_DIR is either the existing database definition as a object or the directory path to load from disk.
Persist the builder instance db to the path passed as DB_DIR. If DB_DIR is falsy, the builder will use the db.dbDir path from db. This method is usually called at the end of the build.js script.
If the esm option is set to true, the code generated will be an ESM module.
const namespacedDb = db.namespace(namespace)
Create a namespaced db for defining multiple sets of database definitions on one database.
db.require(path)
Load helper functions to be used in the database as callbacks for index maps.
Collections
db.collections.register(description)
Register collection with the description.
A description has the following form:
{ name: 'collection-name', schema: '@schema-ns/struct-name', // identifier for the collections schema key?: ['keyField1', 'keyField2'], // the definition of the primary key to lookup collection entries derived?: false // Whether it is derived collection and so shouldnt be versioned}
Elements in the key array should go from least to most specific, but often contain only one field that uniquely identifies the collection entry. Keys can use a 'dot notation' to specify nested properties of the collection entry's struct, for example:
{ name: 'index-name', collection: '@ns/collection', // The collection the index is a lookup into. unique: false, // whether index keys are unique, aka only return one document key: ['other-field'] || { type: 'string', // Key schema type map: 'indexMapFunctionName' // The function name (registered via db.require()) to map over the collection w/ to create the index }}
If unique is false, the primary key of the document will be added to the index key to ensure entries do not clobber one another.
Key Mapping
Indexes support defining key as an array of fields just like Collections, but also support a mapping callback to derive keys from indexed entries. This callback has the following function signature:
function keyMap (record, context): Array<any> {}
The return type of the mapping callback is always an array but the type of the elements in that array are defined as a hyperschema type with the type property like so: