ps

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package ps provides the persistence layer for CommitDB.

The persistence layer is backed by Git, using go-git for storage. Every write operation creates a Git commit, providing full version control and history tracking.

Memory Persistence

For testing or ephemeral databases: 

persistence, err := ps.NewMemoryPersistence()
if err != nil {
    log.Fatal(err)
}

File Persistence

For persistent storage: 

persistence, err := ps.NewFilePersistence("/path/to/data", nil)
if err != nil {
    log.Fatal(err)
}

Transaction Batching

For improved write performance, use TransactionBuilder: 

txn, _ := persistence.BeginTransaction()
txn.AddWrite("db", "table", "key1", data1)
txn.AddWrite("db", "table", "key2", data2)
result, _ := txn.Commit(identity)

Indexing

The persistence layer supports B-tree indexes for faster queries: 

im := ps.NewIndexManager(persistence)
im.CreateIndex("idx_name", "db", "table", "column", false)
keys := im.Lookup("db", "table", "column", "value")

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotInitialized = errors.New("persistence layer not initialized")
	ErrRepoNotFound   = errors.New("repository not found")
)

Functions

This section is empty.

Types

type AuthType added in v1.5.0 

type AuthType string

AuthType defines the type of authentication 

const (
	AuthTypeNone  AuthType = "none"
	AuthTypeToken AuthType = "token"
	AuthTypeSSH   AuthType = "ssh"
	AuthTypeBasic AuthType = "basic"
)

type Index 

type Index struct {
	Name     string              `json:"name"`
	Database string              `json:"database"`
	Table    string              `json:"table"`
	Column   string              `json:"column"`
	Unique   bool                `json:"unique"`
	Entries  map[string][]string `json:"entries"` // column value -> list of primary keys
}

Index represents a B-tree index on a column

func (*Index) Delete 

func (idx *Index) Delete(columnValue, primaryKey string)

Delete removes an entry from the index

func (*Index) Insert 

func (idx *Index) Insert(columnValue, primaryKey string) error

Insert adds an entry to the index

func (*Index) Lookup 

func (idx *Index) Lookup(columnValue string) []string

Lookup finds primary keys for a given column value

func (*Index) LookupRange 

func (idx *Index) LookupRange(minValue, maxValue string) []string

LookupRange finds primary keys within a range (inclusive)

type IndexManager 

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

IndexManager manages indexes for a persistence layer

func NewIndexManager 

func NewIndexManager(persistence *Persistence) *IndexManager

NewIndexManager creates a new index manager

func (*IndexManager) CreateIndex 

func (im *IndexManager) CreateIndex(name, database, table, column string, unique bool) (*Index, error)

CreateIndex creates a new index on a column

func (*IndexManager) DropIndex 

func (im *IndexManager) DropIndex(database, table, column string) error

DropIndex removes an index

func (*IndexManager) GetIndex 

func (im *IndexManager) GetIndex(database, table, column string) (*Index, bool)

GetIndex retrieves an existing index

func (*IndexManager) LoadIndexes 

func (im *IndexManager) LoadIndexes(database, table string, columns []core.Column) error

LoadIndexes loads all indexes from storage for a table

func (*IndexManager) RebuildIndex 

func (im *IndexManager) RebuildIndex(idx *Index, getRecordValue func(pk string) (string, bool)) error

RebuildIndex rebuilds an index by scanning all records

type MergeOptions added in v1.4.0 

type MergeOptions struct {
	Strategy MergeStrategy
}

MergeOptions configures merge behavior

func DefaultMergeOptions added in v1.4.0 

func DefaultMergeOptions() MergeOptions

DefaultMergeOptions returns the default merge options (row-level merge)

type MergeResult added in v1.4.0 

type MergeResult struct {
	Transaction   Transaction
	MergedRecords int
	FastForward   bool
	Conflicts     []RecordConflict // conflicts that were auto-resolved (LWW)
	Unresolved    []RecordConflict // conflicts requiring manual resolution
	MergeID       string           // ID to resume pending merge (empty if complete)
	Pending       bool             // true if merge is pending manual resolution
}

MergeResult contains information about a completed or pending merge

type MergeStrategy added in v1.4.0 

type MergeStrategy string

MergeStrategy defines how to handle merge 

const (
	// MergeStrategyFastForwardOnly only allows fast-forward merges
	MergeStrategyFastForwardOnly MergeStrategy = "fast-forward-only"
	// MergeStrategyRowLevel performs row-level merge for diverged branches (LWW auto-resolve)
	MergeStrategyRowLevel MergeStrategy = "row-level"
	// MergeStrategyManual pauses on conflicts for manual resolution
	MergeStrategyManual MergeStrategy = "manual"
)

type Operation 

type Operation struct {
	Type     OperationType
	Database string
	Table    string
	Key      string
	Data     []byte
}

Operation represents a single write operation in a transaction

type OperationType 

type OperationType int
const (
	WriteOp OperationType = iota
	DeleteOp
)

type PendingMerge added in v1.4.0 

type PendingMerge struct {
	MergeID       string            `json:"merge_id"`
	HeadCommit    string            `json:"head_commit"`
	SourceCommit  string            `json:"source_commit"`
	SourceBranch  string            `json:"source_branch"`
	BaseCommit    string            `json:"base_commit"`
	Resolved      map[string][]byte `json:"resolved"`       // key -> resolved data
	Unresolved    []RecordConflict  `json:"unresolved"`     // remaining conflicts
	MergedRecords map[string][]byte `json:"merged_records"` // non-conflicting merged data
	CreatedAt     time.Time         `json:"created_at"`
}

PendingMerge stores state for a merge awaiting manual conflict resolution

type Persistence 

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

func NewFilePersistence 

func NewFilePersistence(baseDir string, gitUrl *string) (Persistence, error)

func NewMemoryPersistence 

func NewMemoryPersistence() (Persistence, error)

func (*Persistence) AbortMerge added in v1.4.0 

func (p *Persistence) AbortMerge() error

AbortMerge cancels a pending merge

func (*Persistence) AddRemote added in v1.5.0 

func (p *Persistence) AddRemote(name, url string) error

AddRemote adds a named remote to the repository

func (*Persistence) BeginTransaction 

func (persistence *Persistence) BeginTransaction() (*TransactionBuilder, error)

BeginTransaction creates a new transaction builder for batching operations

func (*Persistence) Branch added in v1.3.0 

func (p *Persistence) Branch(name string, from *Transaction) error

Branch creates a new branch at current HEAD or at a specific transaction

func (*Persistence) Checkout added in v1.3.0 

func (p *Persistence) Checkout(name string) error

Checkout switches to an existing branch

func (*Persistence) CompleteMerge added in v1.4.0 

func (p *Persistence) CompleteMerge(identity core.Identity) (Transaction, error)

CompleteMerge finishes a pending merge after all conflicts are resolved

func (*Persistence) CopyRecords added in v1.7.0 

func (persistence *Persistence) CopyRecords(srcDatabase, srcTable, dstDatabase, dstTable string, identity core.Identity) (txn Transaction, err error)

CopyRecords copies all records from source table to destination table in a single atomic transaction. This is memory-efficient: records are streamed row-by-row from source and written to dest without loading all into memory.

func (*Persistence) CreateDatabase 

func (persistence *Persistence) CreateDatabase(database core.Database, identity core.Identity) (txn Transaction, err error)

func (*Persistence) CreateTable 

func (persistence *Persistence) CreateTable(table core.Table, identity core.Identity) (txn Transaction, err error)

func (*Persistence) CurrentBranch added in v1.3.0 

func (p *Persistence) CurrentBranch() (string, error)

CurrentBranch returns the name of the current branch

func (*Persistence) DeleteBranch added in v1.3.0 

func (p *Persistence) DeleteBranch(name string) error

DeleteBranch deletes a branch

func (*Persistence) DeleteRecord 

func (persistence *Persistence) DeleteRecord(database string, table string, key string, identity core.Identity) (txn Transaction, err error)

func (*Persistence) DropDatabase 

func (persistence *Persistence) DropDatabase(name string, identity core.Identity) (txn Transaction, err error)

func (*Persistence) DropTable 

func (persistence *Persistence) DropTable(database string, table string, identity core.Identity) (txn Transaction, err error)

func (*Persistence) Fetch added in v1.5.0 

func (p *Persistence) Fetch(remoteName string, auth *RemoteAuth) error

Fetch fetches refs from a remote without merging

func (*Persistence) GetDatabase 

func (persistence *Persistence) GetDatabase(name string) (d *core.Database, err error)

func (*Persistence) GetPendingMerge added in v1.4.0 

func (p *Persistence) GetPendingMerge() *PendingMerge

GetPendingMerge returns the current pending merge, if any

func (*Persistence) GetRecord 

func (persistence *Persistence) GetRecord(database string, table string, key string) (data []byte, exists bool)

func (*Persistence) GetTable 

func (persistence *Persistence) GetTable(database string, table string) (t *core.Table, err error)

func (*Persistence) IsInitialized 

func (p *Persistence) IsInitialized() bool

IsInitialized returns true if the persistence layer has a valid repository

func (*Persistence) LatestTransaction 

func (persistence *Persistence) LatestTransaction() Transaction

func (*Persistence) ListBranches added in v1.3.0 

func (p *Persistence) ListBranches() ([]string, error)

ListBranches returns all branch names

func (*Persistence) ListDatabases 

func (persistence *Persistence) ListDatabases() []string

func (*Persistence) ListRecordKeys 

func (persistence *Persistence) ListRecordKeys(database string, table string) []string

func (*Persistence) ListRemotes added in v1.5.0 

func (p *Persistence) ListRemotes() ([]Remote, error)

ListRemotes returns all configured remotes

func (*Persistence) ListTables 

func (persistence *Persistence) ListTables(database string) []string

func (*Persistence) Lock 

func (p *Persistence) Lock()

Lock acquires a write lock for exclusive write operations

func (*Persistence) Merge added in v1.3.0 

func (p *Persistence) Merge(source string, identity core.Identity) (Transaction, error)

Merge merges the source branch into the current branch. Uses row-level merge strategy for diverged branches (Last-Writer-Wins).

func (*Persistence) MergeWithOptions added in v1.4.0 

func (p *Persistence) MergeWithOptions(source string, identity core.Identity, opts MergeOptions) (MergeResult, error)

MergeWithOptions merges source branch into current with specified options

func (*Persistence) Pull added in v1.5.0 

func (p *Persistence) Pull(remoteName, branch string, auth *RemoteAuth) error

Pull pulls changes from a remote and merges into current branch

func (*Persistence) Push added in v1.5.0 

func (p *Persistence) Push(remoteName, branch string, auth *RemoteAuth) error

Push pushes a branch to a remote

func (*Persistence) RLock 

func (p *Persistence) RLock()

RLock acquires a read lock for concurrent read operations

func (*Persistence) RUnlock 

func (p *Persistence) RUnlock()

RUnlock releases the read lock

func (*Persistence) Recover 

func (persistence *Persistence) Recover(name string) error

func (*Persistence) RemoveRemote added in v1.5.0 

func (p *Persistence) RemoveRemote(name string) error

RemoveRemote removes a remote from the repository

func (*Persistence) RenameBranch added in v1.3.0 

func (p *Persistence) RenameBranch(oldName, newName string) error

RenameBranch renames a branch

func (*Persistence) ResolveConflict added in v1.4.0 

func (p *Persistence) ResolveConflict(database, table, key string, resolution []byte) error

ResolveConflict resolves a single conflict in a pending merge

func (*Persistence) Restore 

func (persistence *Persistence) Restore(asof Transaction, database *string, table *string) error

func (*Persistence) SaveRecord 

func (persistence *Persistence) SaveRecord(database string, table string, records map[string][]byte, identity core.Identity) (txn Transaction, err error)

func (*Persistence) Scan 

func (persistence *Persistence) Scan(database string, table string, filterExpr *func(key string, value []byte) bool) iter.Seq2[string, []byte]

func (*Persistence) Snapshot 

func (persistence *Persistence) Snapshot(name string, asof *Transaction) error

func (*Persistence) TransactionsFrom 

func (persistence *Persistence) TransactionsFrom(asof string) []Transaction

func (*Persistence) TransactionsSince 

func (persistence *Persistence) TransactionsSince(asof time.Time) []Transaction

func (*Persistence) Unlock 

func (p *Persistence) Unlock()

Unlock releases the write lock

func (*Persistence) UpdateTable added in v1.7.0 

func (persistence *Persistence) UpdateTable(table core.Table, identity core.Identity, message string) (txn Transaction, err error)

UpdateTable updates an existing table's schema

type RecordConflict added in v1.4.0 

type RecordConflict struct {
	Database  string
	Table     string
	Key       string
	BaseVal   []byte // nil if record didn't exist at base
	HeadVal   []byte // nil if deleted in HEAD
	SourceVal []byte // nil if deleted in SOURCE
	Resolved  []byte // the resolved value (LWW winner)
}

RecordConflict represents a conflict where both branches modified the same record

type Remote added in v1.5.0 

type Remote struct {
	Name string
	URLs []string
}

Remote represents a Git remote

type RemoteAuth added in v1.5.0 

type RemoteAuth struct {
	Type       AuthType
	Token      string // For token auth
	KeyPath    string // For SSH key auth
	Passphrase string // For SSH key with passphrase
	Username   string // For basic auth
	Password   string // For basic auth
}

RemoteAuth holds authentication configuration for remote operations

type Transaction 

type Transaction struct {
	Id     string
	When   time.Time
	Author string // "Name <email>" format
}

func (Transaction) String 

func (transaction Transaction) String() string

type TransactionBuilder 

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

TransactionBuilder allows batching multiple write operations into a single commit

func (*TransactionBuilder) AddDelete 

func (tb *TransactionBuilder) AddDelete(database, table, key string) error

AddDelete adds a delete operation to the transaction batch

func (*TransactionBuilder) AddWrite 

func (tb *TransactionBuilder) AddWrite(database, table, key string, data []byte) error

AddWrite adds a write operation to the transaction batch

func (*TransactionBuilder) Commit 

func (tb *TransactionBuilder) Commit(identity core.Identity) (Transaction, error)

Commit applies all batched operations in a single git commit

func (*TransactionBuilder) OperationCount 

func (tb *TransactionBuilder) OperationCount() int

OperationCount returns the number of pending operations

func (*TransactionBuilder) Rollback 

func (tb *TransactionBuilder) Rollback()

Rollback discards all batched operations without committing

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.