Database

Database provides transactional, CRUD-style persistence for Viper documents — backed by SQLite on disk or held entirely in memory. Documents are addressed by a typed (attachment, key, value) triple; writes are bracketed by a transaction, reads return a ValueOptional that you peel with .unwrap().

This page also covers the helpers that move a Database around: the faithful DatabaseCopier (one Database into another, blobs and all) and the DatabaseToCommitDatabaseConverter (importing a flat Database into the versioned tier).

When to use

Reach for Database when you want a plain document store with no history — the latest value for each key, nothing more. If you need an append-only mutation DAG with full version history, use CommitDatabase instead; see Commit & versioning. The two tiers interconvert through the converter classes below.

Use case	Class	Note
Simple CRUD, no history	Database	SQLite file or in-memory
Need version history	CommitDatabase	See Commit & versioning
Copy a Database faithfully	DatabaseCopier	Replicates every blob, orphans included
Import a Database into the versioned tier	DatabaseToCommitDatabaseConverter	Copies only referenced blobs

Quick Start

const {
  Database, Definitions, NameSpace, ValueUUId, Type,
} = require('@digitalsubstrate/dsviper');

// Build a schema and create or open a database
const defs = new Definitions();
const ns = new NameSpace(ValueUUId.create(), 'Demo');
const concept = defs.createConcept(ns, 'Item');
const att = defs.createAttachment(ns, 'Count', concept, Type.INT64);

const db = Database.createInMemory();        // or Database.create('data.db')
db.extendDefinitions(defs.const());          // seed/grow the schema incrementally

// Write — requires a transaction
const key = att.createKey();
db.beginTransaction();
db.set(att, key, 42);
db.commit();                                 // db.rollback() discards instead

// Read — get() returns a ValueOptional
const result = db.get(att, key);
if (!result.isNil()) {
  const count = result.unwrap();             // INT64 comes back as a bigint
  console.log(count === 42n);                // true
}

// Enumerate keys, then delete (inside a transaction)
for (const k of db.keys(att)) { /* ... */ }

db.beginTransaction();
db.delete(att, key);                         // no error if the key is absent
db.commit();

db.close();

Open an existing database read-only with Database.open(path, true), and probe a file first with Database.isCompatible(path). A failed operation (opening a missing file, writing through a read-only handle, using a closed database) throws a JS Error whose .name === 'ViperError'.

For the same API in Python, see Database.

Generated from the @digitalsubstrate/dsviper TypeScript declarations (index.d.ts) by TypeDoc.

Summary

Class	Description
Database	A Database is a CRUD like transactional database
DatabaseCopier	Copies a Database into another Database
DatabaseRemote	A low-level class used to access a CRUD like database from a remote repository through the Databasing interface
DatabaseSQLite	A low-level class used to represent a CRUD like database based on SQLite3 through the Databasing interface
DatabaseToCommitDatabaseConverter	Converts a Database into a CommitDatabase
DatabaseTransferInfo	Result of a database conversion: counts of copied documents and blobs

Reference

class Database()

A Database is a CRUD like transactional database. Use the static factory method

createInMemory(), create(…), open(…), connect(…) or connectLocal(…).

Note: Not directly instantiable.

exported from index.d

Database.attachmentGetting()

Return the AttachmentGetting interface.

Returns:

AttachmentGetting

Database.beginTransaction(mode)

Begin a transaction where the mode is ‘Deferred’, ‘Immediate’ or

‘Exclusive’.

Arguments:

• mode (string)

Database.blob(blobId)

Return a blob or null.

Arguments:

• blobId (ValueBlobId)

Returns:

ValueBlob

Database.blobGetting()

Return the BlobGetting interface.

Returns:

BlobGetting

Database.blobIds()

Return the set of blob_id.

Returns:

ValueBlobId[]

Database.blobInfo(blobId)

Return the information for the blob or null.

Arguments:

• blobId (ValueBlobId)

Returns:

BlobInfo

Database.blobInfos(blobIds)

Return a list of BlobInfo.

Arguments:

• blobIds (ValueBlobId[])

Returns:

BlobInfo[]

Database.blobStatistics()

Return the statistics for blobs.

Returns:

BlobStatistics

Database.blobStreamAppend(blobStream, blob)

Append a blob to the stream.

Arguments:

• blobStream (BlobStream)

• blob (ValueBlob)

Database.blobStreamClose(blobStream)

Return the computed blob_id and close the stream.

Arguments:

• blobStream (BlobStream)

Returns:

ValueBlobId

Database.blobStreamCreate(blobLayout, size)

Return a stream to fill a blob.

Arguments:

• blobLayout (BlobLayout)

• size (number)

Returns:

BlobStream

Database.close()

Close the database.

Database.codecName()

Return the name of the codec.

Returns:

string

Database.commit()

Commit the transaction.

Database.createBlob(blobLayout, blob)

Create the blob and return the blob_id.

Arguments:

• blobLayout (BlobLayout)

• blob (ValueBlob)

Returns:

ValueBlobId

Database.createBlobFromBuffer(buffer)

Compute and return the blob_id for an object implementing protocol buffer.

Arguments:

• buffer (Buffer)

Returns:

ValueBlobId

Database.databasing()

Return the Databasing interface.

Returns:

Databasing

Database.definitions()

Return the definitions.

Returns:

DefinitionsConst

Database.definitionsHexdigest()

Return the hexdigest of the definitions.

Returns:

string

Database.delBlob(blobId)

Return true if the blob was deleted.

Arguments:

• blobId (ValueBlobId)

Returns:

boolean

Database.delete(attachment, key)

Return true if the value was deleted.

Arguments:

• attachment (Attachment)

• key (ValueKey)

Returns:

boolean

Database.documentation()

Return the documentation.

Returns:

string

Database.extendDefinitions(definitions)

Extend the definitions.

Arguments:

• definitions (DefinitionsConst)

Returns:

DefinitionsExtendInfo

Database.get(attachment, key)

Return and optional<document_type> associated with the key.

Arguments:

• attachment (Attachment)

• key (ValueKey)

Returns:

ValueOptional

Database.has(attachment, key)

Return true if a document is present for the key.

Arguments:

• attachment (Attachment)

• key (ValueKey)

Returns:

boolean

Database.inMemory()

Return true if the database is in memory.

Returns:

boolean

Database.inTransaction()

Return true if a transaction is running.

Returns:

boolean

Database.isClosed()

Return true if the database is closed.

Returns:

boolean

Database.keys(attachment)

Return the set of all keys.

Arguments:

• attachment (Attachment)

Returns:

ValueSet

Database.path()

Return the path.

Returns:

string

Database.readBlob(blobId, size, offset)

Return the blob at offset.

Arguments:

• blobId (ValueBlobId)

• size (number)

• offset (number)

Returns:

ValueBlob

Database.rollback()

Roll back the transaction.

Database.set(attachment, key, value)

Assigns the value to the key.

Arguments:

• attachment (Attachment)

• key (ValueKey)

• value (InputValue)

Returns:

boolean

Database.uuid()

Return the uuid.

Returns:

ValueUUId

static Database.connect(database, host, service)

Connect to a server and use the database.

Arguments:

• database (string)

• host (string)

• service (string)

Returns:

Database

static Database.connectLocal(database, socketPath)

Connect to socket_path and use the database.

Arguments:

• database (string)

• socketPath (string)

Returns:

Database

static Database.create(filePath, documentation)

Create and return a database.

Arguments:

• filePath (string)

• documentation (string)

Returns:

Database

static Database.createInMemory()

Create and return a database in memory.

Returns:

Database

static Database.databases(host, service)

Connect to a server and return the list of databases.

Arguments:

• host (string)

• service (string)

Returns:

string[]

static Database.databasesLocal(socketPath)

Connect to a server and return the list of databases.

Arguments:

• socketPath (string)

Returns:

string[]

static Database.isCompatible(filePath)

Return true if the SQL schema contains required tables.

Arguments:

• filePath (string)

Returns:

boolean

static Database.open(filePath, readonly)

Open and return a database.

Arguments:

• filePath (string)

• readonly (boolean)

Returns:

Database

class DatabaseCopier()

Copies a Database into another Database.

exported from index.d

DatabaseCopier.copy(source, target, progress)

Copy every document and blob of a Database into another Database, as a

faithful replica (including blobs that no document references). progress is an optional StepperDelegate. Return a DatabaseTransferInfo.

Arguments:

• source (Database)

• target (Database)

• progress ((action: string, percent: number) => void | undefined)

Returns:

DatabaseTransferInfo

class DatabaseRemote()

A low-level class used to access a CRUD like database from a remote repository

through the Databasing interface. Use the high-level static factory method Database.connect(…) or Database.connectLocal(…). Use the high-level static method Database.databases(…) or Database.databasesLocal(…) to retrieve the list of the databases from a server.

Note: Not directly instantiable.

exported from index.d

DatabaseRemote.close()

Close the database.

DatabaseRemote.databasing()

Return the Databasing interface.

Returns:

Databasing

DatabaseRemote.isClosed()

Return true the connection is closed.

Returns:

boolean

static DatabaseRemote.connect(database, host, service)

Connect to a server and use the database.

Arguments:

• database (string)

• host (string)

• service (string)

Returns:

DatabaseRemote

static DatabaseRemote.connectLocal(database, socketPath)

Connect to socket_path and use the database.

Arguments:

• database (string)

• socketPath (string)

Returns:

DatabaseRemote

static DatabaseRemote.databases(host, service)

Connect to a server and return the list of databases.

Arguments:

• host (string)

• service (string)

Returns:

string[]

static DatabaseRemote.databasesLocal(socketPath)

Connect to a server and return the list of databases.

Arguments:

• socketPath (string)

Returns:

string[]

class DatabaseSQLite()

A low-level class used to represent a CRUD like database based on SQLite3

through the Databasing interface. Use the high-level static factory method Database.createInMemory(), Database.create(…) or Database.open(…).

Note: Not directly instantiable.

exported from index.d

DatabaseSQLite.close()

Close the database.

DatabaseSQLite.databasing()

Return the Databasing interface.

Returns:

Databasing

DatabaseSQLite.isClosed()

Return true if the database is closed.

Returns:

boolean

DatabaseSQLite.sqlite()

Return the sqlite api.

Returns:

SQLite

static DatabaseSQLite.create(filePath, documentation)

Create and return a database.

Arguments:

• filePath (string)

• documentation (string)

Returns:

DatabaseSQLite

static DatabaseSQLite.createInMemory()

Create and return a database in memory.

Returns:

DatabaseSQLite

static DatabaseSQLite.isCompatible(filePath)

Return true the SQL schema contains required tables.

Arguments:

• filePath (string)

Returns:

boolean

static DatabaseSQLite.open(filePath, readonly)

Open and return a database.

Arguments:

• filePath (string)

• readonly (boolean)

Returns:

DatabaseSQLite

class DatabaseToCommitDatabaseConverter()

Converts a Database into a CommitDatabase.

exported from index.d

DatabaseToCommitDatabaseConverter.convert(source, target, label, progress)

Convert a Database into a CommitDatabase as a single commit labelled label.

progress is an optional StepperDelegate. Return a DatabaseTransferInfo.

Arguments:

• source (Database)

• target (CommitDatabase)

• label (string)

• progress ((action: string, percent: number) => void | undefined)

Returns:

DatabaseTransferInfo

class DatabaseTransferInfo()

Result of a database conversion: counts of copied documents and blobs.

exported from index.d