Skip to content

API.md

Latest commit

 

History

History
406 lines (293 loc) · 7.66 KB

API.md

File metadata and controls

406 lines (293 loc) · 7.66 KB

LATTICE.DB API Reference

This document describes the public API for LATTICE.DB Go SDK.

Table of Contents

  1. Database
  2. Transactions
  3. Documents
  4. Collections
  5. Queries
  6. Sync
  7. Error Handling

Database

Opening a Database

import "github.com/lattice-db/lattice/pkg/lattice"

// Open with default options
db, err := lattice.Open("./data", nil)
if err != nil {
    log.Fatal(err)
}
defer db.Close()

// Open with custom options
opts := &lattice.Options{
    EncryptionKey: key,
    CreateIfMissing: true,
}
db, err := lattice.Open("./data", opts)

Options

Field Type Default Description
EncryptionKey []byte nil 32-byte key for at-rest encryption
CreateIfMissing bool true Create database if it doesn't exist
PageSize uint32 4096 Page size in bytes
CacheSize int 1000 Number of pages to cache

Methods

Begin(writable bool) (*Transaction, error)

Begin a new transaction.

Parameters:

  • writable: If true, transaction can write. If false, read-only.

Returns:

  • *Transaction: The transaction object
  • error: Error if transaction cannot begin

Example:

tx, err := db.Begin(true) // Writable transaction
if err != nil {
    return err
}
defer tx.Rollback()

Close() error

Close the database and release resources.

Verify() (*VerifyResult, error)

Verify database integrity.

Transactions

Methods

CreateCollection(name string, schema *Schema) error

Create a new collection.

Parameters:

  • name: Collection name (must be unique)
  • schema: Schema definition (optional but recommended)

Errors:

  • ErrCollectionExists: Collection already exists
  • ErrTransactionReadOnly: Transaction is read-only

DropCollection(name string) error

Drop a collection and all its documents.

GetCollection(name string) (*Collection, error)

Get a collection by name.

ListCollections() ([]string, error)

List all collection names.

Get(id string, collection string) (*Document, error)

Get a document by ID.

Parameters:

  • id: Document ID
  • collection: Collection name

Returns:

  • *Document: The document, or nil if not found
  • error: Error on failure

Errors:

  • ErrDocumentNotFound: Document doesn't exist

Insert(collection string, doc *Document) error

Insert a new document.

Errors:

  • ErrDocumentExists: Document ID already exists
  • ErrSchemaViolation: Document doesn't match schema
  • ErrTransactionReadOnly: Transaction is read-only

Update(collection string, doc *Document) error

Update an existing document.

Errors:

  • ErrDocumentNotFound: Document doesn't exist
  • ErrSchemaViolation: Document doesn't match schema
  • ErrTransactionReadOnly: Transaction is read-only

Delete(collection string, id string) error

Delete a document.

Query(collection string, query *Query) (*ResultSet, error)

Execute a query.

Commit() error

Commit the transaction.

Errors:

  • ErrConflict: Write-write conflict detected
  • ErrValidationFailed: Validation failed

Rollback() error

Rollback the transaction.

Documents

Type Definition

type Document struct {
    ID     string
    Data   map[string]interface{}
    Meta   DocumentMeta
    Version int
}

type DocumentMeta struct {
    CreatedAt   time.Time
    UpdatedAt   time.Time
    Deleted     bool
    DeletedAt   *time.Time
    CreatedBy   string
    UpdatedBy   string
}

Methods

NewDocument(id string) *Document

Create a new document with the given ID.

doc := lattice.NewDocument("user-123")
doc.Set("name", "Alice")
doc.Set("age", 30)

Get(key string) (interface{}, bool)

Get a field value.

name, ok := doc.Get("name")
if !ok {
    // Field not found
}

Set(key string, value interface{})

Set a field value.

Delete(key string)

Delete a field.

Collections

Methods

Count() (int64, error)

Count documents in the collection.

Schema() *Schema

Get the collection's schema.

Queries

Type Definition

type Query struct {
    Collection string
    Filters    []Filter
    OrderBy    []Order
    Limit      int
    Offset     int
}

type Filter struct {
    Field    string
    Operator FilterOp
    Value    interface{}
}

type FilterOp string

const (
    FilterOpEqual        FilterOp = "=="
    FilterOpNotEqual     FilterOp = "!="
    FilterOpLessThan     FilterOp = "<"
    FilterOpLessEqual    FilterOp = "<="
    FilterOpGreaterThan  FilterOp = ">"
    FilterOpGreaterEqual FilterOp = ">="
    FilterOpContains     FilterOp = "contains"
    FilterOpStartsWith   FilterOp = "starts_with"
    FilterOpEndsWith     FilterOp = "ends_with"
)

type Order struct {
    Field     string
    Direction OrderDirection
}

type OrderDirection string

const (
    OrderAsc  OrderDirection = "ASC"
    OrderDesc OrderDirection = "DESC"
)

Example

query := &lattice.Query{
    Collection: "users",
    Filters: []lattice.Filter{
        {Field: "age", Operator: lattice.FilterOpGreaterThan, Value: 18},
        {Field: "name", Operator: lattice.FilterOpContains, Value: "Alice"},
    },
    OrderBy: []lattice.Order{
        {Field: "name", Direction: lattice.OrderAsc},
    },
    Limit: 100,
}

result, err := tx.Query("users", query)
for result.Next() {
    doc := result.Document()
    // Process document
}
if err := result.Err(); err != nil {
    return err
}

Sync

Configuration

type SyncConfig struct {
    ServerURL    string
    DeviceID     string
    DeviceKey    []byte  // ECDH private key
    EncryptionKey []byte  // Master encryption key
    AutoSync     bool
    SyncInterval time.Duration
}

Methods

ConfigureSync(config *SyncConfig) error

Configure sync settings.

SyncStatus() *SyncStatus

Get current sync status.

type SyncStatus struct {
    Syncing    bool
    LastSync   time.Time
    Error      error
    Version    uint64
}

SyncOneShot() error

Perform a one-time sync.

Error Handling

Standard Errors

var (
    ErrDatabaseNotFound    = errors.New("database not found")
    ErrCollectionExists    = errors.New("collection already exists")
    ErrCollectionNotFound  = errors.New("collection not found")
    ErrDocumentExists      = errors.New("document already exists")
    ErrDocumentNotFound    = errors.New("document not found")
    ErrSchemaViolation     = errors.New("schema violation")
    ErrConflict            = errors.New("transaction conflict")
    ErrTransactionReadOnly = errors.New("transaction is read-only")
    ErrValidationFailed    = errors.New("validation failed")
)

Error Checking

err := tx.Insert("users", doc)
if errors.Is(err, lattice.ErrDocumentExists) {
    // Handle duplicate document
}

Best Practices

1. Always Defer Rollback

tx, err := db.Begin(true)
if err != nil {
    return err
}
defer tx.Rollback() // No-op if Commit succeeded

// ... do work ...

return tx.Commit()

2. Check Schema Violations

err := tx.Insert("users", doc)
if errors.Is(err, lattice.ErrSchemaViolation) {
    // Log validation failure
    log.Printf("Schema violation: %v", err)
}

3. Use Read-Only Transactions When Possible

tx, err := db.Begin(false) // Read-only
if err != nil {
    return err
}
defer tx.Rollback()

doc, err := tx.Get("users", "user-123")
// ...

4. Handle Conflicts

err = tx.Commit()
if errors.Is(err, lattice.ErrConflict) {
    // Retry transaction with exponential backoff
    time.Sleep(time.Millisecond * 100)
    // retry...
}