database

README

Manifold Database API Documentation

This document provides an overview of the API functions available in the Manifold database package.

Table of Contents

1. Database Initialization
2. Basic Operations
3. Event Operations
4. Query Operations
5. Logging

Database Initialization

New

func New() (d *D)

Creates a new database instance with default settings.

Returns:

• d *D: A new database instance

Init

func (d *D) Init(path string) (err error)

Initializes the database with the specified path.

Parameters:

• path string: The directory path where the database files will be stored

Returns:

• err error: Any error that occurred during initialization

Close

func (d *D) Close() (err error)

Closes the database.

Returns:

• err error: Any error that occurred during closing

Path

func (d *D) Path() string

Returns the path where the database files are stored.

Returns:

• string: The database directory path

Basic Operations

Set

func (d *D) Set(k, v []byte) (err error)

Sets a key-value pair in the database.

Parameters:

• k []byte: The key
• v []byte: The value (can be nil)

Returns:

• err error: Any error that occurred

Get

func (d *D) Get(k []byte) (v []byte, err error)

Gets a value by key from the database.

Parameters:

• k []byte: The key

Returns:

• v []byte: The value
• err error: Any error that occurred

View

func (d *D) View(fn func(txn *badger.Txn) (err error)) (err error)

Executes a read-only transaction.

Parameters:

• fn func(txn *badger.Txn) (err error): The function to execute within the transaction

Returns:

• err error: Any error that occurred

Update

func (d *D) Update(fn func(txn *badger.Txn) (err error)) (err error)

Executes a read-write transaction.

Parameters:

• fn func(txn *badger.Txn) (err error): The function to execute within the transaction

Returns:

• err error: Any error that occurred

Serial

func (d *D) Serial() (ser uint64, err error)

Returns the next monotonic conflict-free unique serial number.

Returns:

• ser uint64: The next serial number
• err error: Any error that occurred

Event Operations

StoreEvent

func (d *D) StoreEvent(ev *event.E) (err error)

Stores an event in the database, creating all necessary indexes.

Parameters:

• ev *event.E: The event to store

Returns:

• err error: Any error that occurred, including "duplicate event" if the event already exists

GetEventIndexes

func (d *D) GetEventIndexes(ev *event.E) (indices [][]byte, ser *number.Uint40, err error)

Generates all the index entries for an event.

Parameters:

• ev *event.E: The event to generate indexes for

Returns:

• indices [][]byte: The generated index entries
• ser *number.Uint40: The serial number assigned to the event
• err error: Any error that occurred

FindEventSerialById

func (d *D) FindEventSerialById(evId []byte) (ser *number.Uint40, err error)

Finds the serial number of an event by its ID.

Parameters:

• evId []byte: The event ID

Returns:

• ser *number.Uint40: The serial number of the event
• err error: Any error that occurred, including "event not found"

GetEventFromSerial

func (d *D) GetEventFromSerial(ser *number.Uint40) (ev *event.E, err error)

Retrieves an event by its serial number.

Parameters:

• ser *number.Uint40: The serial number of the event

Returns:

• ev *event.E: The retrieved event
• err error: Any error that occurred

GetEventById

func (d *D) GetEventById(evId []byte) (ev *event.E, err error)

Retrieves an event by its ID.

Parameters:

• evId []byte: The event ID

Returns:

• ev *event.E: The retrieved event
• err error: Any error that occurred

GetIdPubkeyTimestampFromSerial

func (d *D) GetIdPubkeyTimestampFromSerial(ser *number.Uint40) (id, pk []byte, ts int64, err error)

Retrieves the ID, public key, and timestamp of an event by its serial number.

Parameters:

• ser *number.Uint40: The serial number of the event

Returns:

• id []byte: The event ID
• pk []byte: The public key
• ts int64: The timestamp
• err error: Any error that occurred

Query Operations

QueryEvents

func (d *D) QueryEvents(f filter.F) (eventIds [][]byte, err error)

Queries events based on the provided filter criteria.

Parameters:

• f filter.F: The filter criteria, which can include:
  • Ids [][]byte: Specific event IDs to retrieve (if this field is present, any others will be invalid and return an error)
  • Authors [][]byte: Author public keys to filter by
  • Tags map[string][][]byte: Tags to filter by
  • Since int64: Minimum timestamp (inclusive)
  • Until int64: Maximum timestamp (inclusive)
  • NotIds [][]byte: Event IDs to exclude
  • NotAuthors [][]byte: Author public keys to exclude
  • NotTags map[string][][]byte: Tags to exclude
  • Sort string: Sort order ("asc" or "desc")

Returns:

• eventIds [][]byte: The IDs of events matching the filter criteria
• err error: Any error that occurred

Logging

NewLogger

func NewLogger(logLevel int, label string) (l *logger)

Creates a new logger for the database.

Parameters:

• logLevel int: The initial log level
• label string: A label for the logger

Returns:

• l *logger: The new logger

SetLogLevel

func (l *logger) SetLogLevel(level int)

Sets the log level of the logger.

Parameters:

• level int: The new log level

Log Methods

The logger provides the following methods for logging at different levels:

func (l *logger) Errorf(s string, i ...interface{})
func (l *logger) Warningf(s string, i ...interface{})
func (l *logger) Infof(s string, i ...interface{})
func (l *logger) Debugf(s string, i ...interface{})

Each method takes a format string and optional arguments, similar to fmt.Printf.

Documentation

Index

• func NewLogger(logLevel int, label string) (l *logger)
• type D
  • func New() (d *D)
  • func (d *D) Close() (err error)
  • func (d *D) FindEventSerialById(evId []byte) (ser *number.Uint40, err error)
  • func (d *D) Get(k []byte) (v []byte, err error)
  • func (d *D) GetEventById(evId []byte) (ev *event.E, err error)
  • func (d *D) GetEventFromSerial(ser *number.Uint40) (ev *event.E, err error)
  • func (d *D) GetEventIndexes(ev *event.E) (indices [][]byte, ser *number.Uint40, err error)
  • func (d *D) GetIdPubkeyTimestampFromSerial(ser *number.Uint40) (id, pk []byte, ts int64, err error)
  • func (d *D) Init(path string) (err error)
  • func (d *D) Path() string
  • func (d *D) QueryEvents(f *filter.F) (eventIds [][]byte, err error)
  • func (d *D) Serial() (ser uint64, err error)
  • func (d *D) Set(k, v []byte) (err error)
  • func (d *D) StoreEvent(ev *event.E) (err error)
  • func (d *D) Update(fn func(txn *badger.Txn) (err error)) (err error)
  • func (d *D) View(fn func(txn *badger.Txn) (err error)) (err error)
• type IdPubkeyTimestamp

Functions

func NewLogger

func NewLogger(logLevel int, label string) (l *logger)

NewLogger creates a new badger logger.

Types

type D

type D struct {
	BlockCacheSize int
	Logger         *logger
	InitLogLevel   int
	// DB is the badger db
	*badger.DB
	// contains filtered or unexported fields
}

func New

func New() (d *D)

func (*D) Close

func (d *D) Close() (err error)

func (*D) FindEventSerialById

func (d *D) FindEventSerialById(evId []byte) (ser *number.Uint40, err error)

func (*D) Get

func (d *D) Get(k []byte) (v []byte, err error)

func (*D) GetEventById

func (d *D) GetEventById(evId []byte) (ev *event.E, err error)

func (*D) GetEventFromSerial

func (d *D) GetEventFromSerial(ser *number.Uint40) (ev *event.E, err error)

func (*D) GetEventIndexes

func (d *D) GetEventIndexes(ev *event.E) (indices [][]byte, ser *number.Uint40, err error)

func (*D) GetIdPubkeyTimestampFromSerial

func (d *D) GetIdPubkeyTimestampFromSerial(ser *number.Uint40) (id, pk []byte, ts int64, err error)

func (*D) Init

func (d *D) Init(path string) (err error)

Init sets up the database with the loaded configuration.

func (*D) Path

func (d *D) Path() string

Path returns the path where the database files are stored.

func (*D) QueryEvents

func (d *D) QueryEvents(f *filter.F) (eventIds [][]byte, err error)

QueryEvents finds events that match the given filter and returns their IDs. The results are sorted according to the Sort field in the filter.

func (*D) Serial

func (d *D) Serial() (ser uint64, err error)

Serial returns the next monotonic conflict free unique serial on the database.

func (*D) Set

func (d *D) Set(k, v []byte) (err error)

func (*D) StoreEvent

func (d *D) StoreEvent(ev *event.E) (err error)

func (*D) Update

func (d *D) Update(fn func(txn *badger.Txn) (err error)) (err error)

func (*D) View

func (d *D) View(fn func(txn *badger.Txn) (err error)) (err error)

type IdPubkeyTimestamp

type IdPubkeyTimestamp struct {
	Id, Pubkey []byte
	Timestamp  int64
}