databases

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package databases implements the OrbitDB database types on top of the operation log: Events (an append-only event log), KeyValue, KeyValueIndexed and Documents.

It mirrors src/database.js and src/databases in @orbitdb/core 4. Operations are stored as the same {op, key, value} payloads, so a database written by one implementation reads the same in the other.

Index

Constants

View Source 
const (
	// DefaultReferencesCount is how many older entries each new entry
	// refers to, beyond the heads.
	DefaultReferencesCount = 16
	// DefaultDirectory is where databases keep their files.
	DefaultDirectory = "./orbitdb"
)
View Source 
const DefaultIndexBy = "_id"

DefaultIndexBy is the document field Documents uses as the key.

View Source 
const DocumentsType = "documents"

DocumentsType is the type name of Documents databases.

View Source 
const EventsType = "events"

EventsType is the type name of Events databases.

View Source 
const KeyValueType = "keyvalue"

KeyValueType is the type name of KeyValue databases.

Variables

View Source 
var ErrNotFound = errors.New("databases: not found")

ErrNotFound is returned when a key, document or event does not exist.

Functions

func UseDatabaseType 

func UseDatabaseType(typ string, f Factory) error

UseDatabaseType registers a database type, replacing any factory registered under the same name.

Types

type Database 

type Database struct {
	// contains filtered or unexported fields
}

Database is the base every database type builds on: an operation log, the sync protocol replicating it and an event stream.

func New 

func New(ctx context.Context, p Params) (*Database, error)

New opens the base database. Database types call it and add their operations on top.

func (*Database) AccessController 

func (db *Database) AccessController() oplog.AccessController

AccessController returns the access controller.

func (*Database) AddOperation 

func (db *Database) AddOperation(ctx context.Context, op any) (string, error)

AddOperation appends op to the log, announces it to peers and emits EventUpdate. It returns the new entry's hash.

func (*Database) Address 

func (db *Database) Address() string

Address returns the database address.

func (*Database) Close 

func (db *Database) Close() error

Close stops syncing, closes the log and its storages and emits EventClose. Closing twice is a no-op.

func (*Database) Drop 

func (db *Database) Drop(ctx context.Context) error

Drop removes every entry of the database (locally) and emits EventDrop.

func (*Database) Events 

func (db *Database) Events() *Emitter

Events returns the database's event emitter.

func (*Database) Identity 

func (db *Database) Identity() *identitytypes.Identity

Identity returns the identity the database writes as.

func (*Database) Log 

func (db *Database) Log() *oplog.Log

Log returns the operation log.

func (*Database) Meta 

func (db *Database) Meta() any

Meta returns the manifest metadata.

func (*Database) Name 

func (db *Database) Name() string

Name returns the database name.

func (*Database) Peers 

func (db *Database) Peers() []peer.ID

Peers returns the peers currently replicating the database.

func (*Database) Sync 

func (db *Database) Sync() *syncutils.Sync

Sync returns the sync protocol instance, or nil if the database has no IPFS node.

type Document 

type Document struct {
	Key   string
	Value map[string]any
	Hash  string
}

Document is a stored document, its key and the hash of the entry that stored it.

type Documents 

type Documents struct {
	*Database
	// contains filtered or unexported fields
}

Documents stores documents (maps, or structs that encode to maps) keyed by one of their fields.

func NewDocuments 

func NewDocuments(ctx context.Context, p Params, opts DocumentsOptions) (*Documents, error)

NewDocuments opens a Documents database.

func (*Documents) All 

func (d *Documents) All(ctx context.Context) ([]Document, error)

All returns every document, least recently written first.

func (*Documents) Del 

func (d *Documents) Del(ctx context.Context, key string) (string, error)

Del deletes the document with the given key.

func (*Documents) Get 

func (d *Documents) Get(ctx context.Context, key string) (*Document, error)

Get returns the document with the given key, or an error wrapping ErrNotFound. A document stored under a numeric key by another peer is found by the number's decimal form.

func (*Documents) IndexBy 

func (d *Documents) IndexBy() string

IndexBy returns the key field.

func (*Documents) Iterator 

func (d *Documents) Iterator(ctx context.Context, amount int) iter.Seq2[Document, error]

Iterator yields the current version of every document, most recently written first. amount limits the number of documents; zero or negative means all.

func (*Documents) Put 

func (d *Documents) Put(ctx context.Context, doc any) (string, error)

Put stores doc under the value of its IndexBy field and returns the hash of the entry. doc may be a map or a struct (encoded through its JSON form).

func (*Documents) Query 

func (d *Documents) Query(ctx context.Context, match func(doc map[string]any) bool) ([]map[string]any, error)

Query returns the documents for which match returns true, most recently written first.

func (*Documents) Type 

func (*Documents) Type() string

Type returns DocumentsType.

type DocumentsOptions 

type DocumentsOptions struct {
	// IndexBy is the field holding each document's key. Defaults to
	// DefaultIndexBy.
	IndexBy string
}

DocumentsOptions configures a Documents database.

type Emitter 

type Emitter struct {
	// contains filtered or unexported fields
}

Emitter fans events out to subscriptions. Emitting never blocks: each subscription buffers events until its reader takes them.

func (*Emitter) Subscribe 

func (e *Emitter) Subscribe() *Subscription

Subscribe returns a subscription that receives every event emitted from now on. Call Close when done with it. After the database closes, the channel delivers the remaining events, ending with EventClose, and is closed.

type Event 

type Event struct {
	Type  EventType
	Entry *oplog.Entry
	Peer  peer.ID
	Heads []*oplog.Entry
	Err   error
}

Event is something that happened to a database.

type EventEntry 

type EventEntry struct {
	Hash  string
	Value any
}

EventEntry is an event and the hash of the entry that holds it.

type EventType 

type EventType int

EventType identifies a database event. 

const (
	// EventUpdate: an entry was appended locally or joined from a peer.
	// Event.Entry is set.
	EventUpdate EventType = iota + 1
	// EventJoin: a heads exchange with a peer completed. Event.Peer and
	// Event.Heads are set.
	EventJoin
	// EventLeave: a peer stopped replicating. Event.Peer is set.
	EventLeave
	// EventError: a background error, e.g. an invalid entry from a peer.
	// Event.Err is set.
	EventError
	// EventClose: the database was closed. It is the last event.
	EventClose
	// EventDrop: the database was dropped.
	EventDrop
)

Database events, as emitted by @orbitdb/core's database.events.

func (EventType) String 

func (t EventType) String() string

type Events 

type Events struct {
	*Database
}

Events is an immutable, append-only event log.

func NewEvents 

func NewEvents(ctx context.Context, p Params) (*Events, error)

NewEvents opens an Events database.

func (*Events) Add 

func (e *Events) Add(ctx context.Context, value any) (string, error)

Add appends value and returns the hash of its entry.

func (*Events) All 

func (e *Events) All(ctx context.Context) ([]EventEntry, error)

All returns every event, oldest first.

func (*Events) Get 

func (e *Events) Get(ctx context.Context, hash string) (any, error)

Get returns the event stored in the entry with the given hash.

func (*Events) Iterator 

func (e *Events) Iterator(ctx context.Context, opts oplog.IteratorOptions) iter.Seq2[EventEntry, error]

Iterator yields events, newest first, optionally limited to a range of entry hashes (see oplog.IteratorOptions).

func (*Events) Type 

func (*Events) Type() string

Type returns EventsType.

type Factory 

type Factory func(ctx context.Context, p Params) (Store, error)

Factory opens a database of one type.

func DocumentsFactory 

func DocumentsFactory(opts DocumentsOptions) Factory

DocumentsFactory returns a Factory for Documents databases with opts.

func GetDatabaseType 

func GetDatabaseType(typ string) (Factory, error)

GetDatabaseType returns the factory registered for typ.

type KeyValue 

type KeyValue struct {
	*Database
}

KeyValue is a key/value store. Reads walk the log from the heads, so the latest write to a key wins; KeyValueIndexed keeps an index instead.

func NewKeyValue 

func NewKeyValue(ctx context.Context, p Params) (*KeyValue, error)

NewKeyValue opens a KeyValue database.

func (*KeyValue) All 

func (kv *KeyValue) All(ctx context.Context) ([]KeyValueEntry, error)

All returns every key and its current value, least recently written first.

func (*KeyValue) Del 

func (kv *KeyValue) Del(ctx context.Context, key string) (string, error)

Del deletes key and returns the hash of the entry.

func (*KeyValue) Get 

func (kv *KeyValue) Get(ctx context.Context, key string) (any, error)

Get returns the value of key, or an error wrapping ErrNotFound if the key was never set or was deleted.

func (*KeyValue) Iterator 

func (kv *KeyValue) Iterator(ctx context.Context, amount int) iter.Seq2[KeyValueEntry, error]

Iterator yields the current value of every key, most recently written first. amount limits the number of keys; zero or negative means all.

func (*KeyValue) Put 

func (kv *KeyValue) Put(ctx context.Context, key string, value any) (string, error)

Put sets key to value and returns the hash of the entry.

func (*KeyValue) Set 

func (kv *KeyValue) Set(ctx context.Context, key string, value any) (string, error)

Set is an alias for Put.

func (*KeyValue) Type 

func (*KeyValue) Type() string

Type returns KeyValueType.

type KeyValueEntry 

type KeyValueEntry struct {
	Key   string
	Value any
	Hash  string
}

KeyValueEntry is a key, its value and the hash of the entry that set it.

type KeyValueIndexed 

type KeyValueIndexed struct {
	*KeyValue
	// contains filtered or unexported fields
}

KeyValueIndexed is a KeyValue database that keeps the latest value of every key in a LevelDB index, so reads do not walk the log. Its type name is KeyValueType: it is a drop-in replacement, opened with orbitdb.WithDatabase(databases.KeyValueIndexedFactory).

func NewKeyValueIndexed 

func NewKeyValueIndexed(ctx context.Context, p Params) (*KeyValueIndexed, error)

NewKeyValueIndexed opens a KeyValueIndexed database. The index lives in Directory/<address>/_index.

func (*KeyValueIndexed) All 

func (kvi *KeyValueIndexed) All(ctx context.Context) ([]KeyValueEntry, error)

All returns every key and its value, in ascending key order.

func (*KeyValueIndexed) Close 

func (kvi *KeyValueIndexed) Close() error

Close closes the database and its index.

func (*KeyValueIndexed) Drop 

func (kvi *KeyValueIndexed) Drop(ctx context.Context) error

Drop drops the database and clears its index.

func (*KeyValueIndexed) Get 

func (kvi *KeyValueIndexed) Get(ctx context.Context, key string) (any, error)

Get returns the value of key from the index, or an error wrapping ErrNotFound.

func (*KeyValueIndexed) Iterator 

func (kvi *KeyValueIndexed) Iterator(ctx context.Context, amount int) iter.Seq2[KeyValueEntry, error]

Iterator yields every key and its value from the index, in descending key order. amount limits the number of keys; zero or negative means all.

type Operation 

type Operation struct {
	Op    string
	Key   any
	Value any
}

Operation is the payload database types append: {op, key, value}.

func ParseOperation 

func ParseOperation(payload any) (op Operation, ok bool)

ParseOperation reads an {op, key, value} payload. ok is false for payloads of another shape.

type Params 

type Params struct {
	// IPFS provides block storage and networking. Required unless every
	// storage is given and sync is disabled.
	IPFS *ipfs.Node
	// Identity writes to the database. Required.
	Identity *identitytypes.Identity
	// Address is the database address; it is also the log id and the sync
	// topic. Required.
	Address string
	Name    string
	// AccessController decides who may write. Defaults to anyone.
	AccessController oplog.AccessController
	// Directory holds the database files, under Directory/<address>.
	// Defaults to DefaultDirectory.
	Directory string
	// Meta is the manifest metadata.
	Meta any
	// EntryStorage defaults to an LRU cache over IPFS block storage;
	// HeadsStorage and IndexStorage to an LRU cache over LevelDB in
	// Directory.
	HeadsStorage storage.Storage
	EntryStorage storage.Storage
	IndexStorage storage.Storage
	// ReferencesCount is passed to Log.Append. Zero means
	// DefaultReferencesCount; negative means no references.
	ReferencesCount int
	// DisableAutoSync leaves sync stopped until Sync().Start() is called.
	DisableAutoSync bool
	// OnUpdate is called, before EventUpdate is emitted, for every entry
	// appended or joined.
	OnUpdate func(ctx context.Context, log *oplog.Log, entry *oplog.Entry) error
	// OnClose is called once the database has closed.
	OnClose func()
	// Encryption turns on entry and/or payload encryption.
	Encryption oplog.Encryption
}

Params configures a database. OrbitDB.Open fills it; it is exported for custom database types and for using a database without OrbitDB.

type Store 

type Store interface {
	Type() string
	Address() string
	Name() string
	Identity() *identitytypes.Identity
	Meta() any
	Log() *oplog.Log
	Sync() *syncutils.Sync
	Peers() []peer.ID
	Events() *Emitter
	AccessController() oplog.AccessController
	AddOperation(ctx context.Context, op any) (string, error)
	Close() error
	Drop(ctx context.Context) error
}

Store is what every database type provides. OrbitDB.Open returns one; type-assert it to *Events, *KeyValue, *KeyValueIndexed or *Documents, or use the typed Open helpers of package orbitdb.

func KeyValueIndexedFactory 

func KeyValueIndexedFactory(ctx context.Context, p Params) (Store, error)

KeyValueIndexedFactory opens KeyValueIndexed databases.

type Subscription 

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription receives database events.

func (*Subscription) Close 

func (s *Subscription) Close()

Close unsubscribes and discards undelivered events. The channel is closed.

func (*Subscription) Events 

func (s *Subscription) Events() <-chan Event

Events returns the channel events are delivered on.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.