store

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package store provides mechanical SQLite persistence for wherehouse. It owns connection management, migrations, and typed SQL read/write operations. It contains no business logic — callers decide what to write.

Index

Constants

View Source 
const (
	// DefaultBusyTimeout is the SQLite busy timeout in milliseconds.
	DefaultBusyTimeout = 5000
	// DefaultBaseRetryDelay is the base delay for the first retry in WithRetry.
	DefaultBaseRetryDelay = 50 * time.Millisecond
)

Variables

View Source 
var (
	// ErrDatabasePathRequired is returned when Open is called with an empty path.
	ErrDatabasePathRequired = errors.New("database path is required")
	// ErrNotFound is returned when a requested record does not exist.
	ErrNotFound = errors.New("not found")
)

Functions

This section is empty.

Types

type ChildRow added in v0.4.0 

type ChildRow struct {
	Entity      *inventory.Entity
	HasChildren bool
}

ChildRow is the result of GetChildren: the entity plus whether it has non-removed children of its own.

type Config 

type Config struct {
	Path        string
	BusyTimeout int
	AutoMigrate bool
}

Config holds connection parameters for opening a Store.

type RawEvent added in v0.5.0 

type RawEvent struct {
	EventID   int64
	EventType string
	Payload   json.RawMessage
	EntityID  *string
}

RawEvent is an unvalidated event row — EventType is a plain string so callers can detect unknown types without triggering a scan error.

type Store 

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

Store wraps a SQLite database connection.

func Open 

func Open(cfg Config) (*Store, error)

Open opens (or creates) the SQLite database at cfg.Path.

func (*Store) AppendRawEvent 

func (s *Store) AppendRawEvent(
	ctx context.Context,
	eventType inventory.EventType,
	actorUserID string,
	payload json.RawMessage,
	note *string,
	entityID *string,
) (int64, error)

AppendRawEvent inserts a pre-constructed event into the events table. Does NOT apply projections — that is eventbus's responsibility.

func (*Store) ClearAllData added in v0.4.0 

func (s *Store) ClearAllData(ctx context.Context) error

ClearAllData deletes all rows from entities_current then events, leaving schema_metadata intact.

INVARIANT: entities_current is the only projection table (see CONTEXT.md "Projection"). If a second projection table is ever added, it must also be cleared here AND that change should be captured in an ADR — adding a projection breaks the documented single-projection invariant and the decision deserves to be recorded before the code is changed.

func (*Store) Close 

func (s *Store) Close() error

Close releases the database connection.

func (*Store) ComputeEntityPathTx 

func (s *Store) ComputeEntityPathTx(
	ctx context.Context,
	tx Tx,
	displayName, canonicalName string,
	parentID *string,
) (string, string, int, error)

ComputeEntityPathTx computes full_path_display, full_path_canonical, and depth for a new entity given its parent. Runs inside an existing transaction. ComputeEntityPathTx computes full_path_display, full_path_canonical, and depth for a new entity given its parent. Runs inside an existing transaction.

func (*Store) DB 

func (s *Store) DB() *sql.DB

DB returns the underlying sql.DB.

func (*Store) DeleteTagTx added in v0.6.0 

func (s *Store) DeleteTagTx(ctx context.Context, tx Tx, entityID, tag string) error

DeleteTagTx deletes a tag for entityID within the given transaction. Deleting a missing tag is a no-op.

func (*Store) ExecInTransaction 

func (s *Store) ExecInTransaction(ctx context.Context, fn func(Tx) error) error

ExecInTransaction runs fn inside a transaction, committing on success and rolling back on error.

func (*Store) GetAllEvents 

func (s *Store) GetAllEvents(ctx context.Context) ([]*inventory.Event, error)

GetAllEvents retrieves all events ordered by event_id ASC.

func (*Store) GetAllEventsRaw added in v0.5.0 

func (s *Store) GetAllEventsRaw(ctx context.Context) ([]RawEvent, error)

GetAllEventsRaw returns all events ordered by event_id ASC with EventType as a raw string.

func (*Store) GetChildren 

func (s *Store) GetChildren(ctx context.Context, parentID string) ([]ChildRow, error)

GetChildren retrieves direct non-removed children of a parent entity, each annotated with whether it has non-removed children of its own. Ordered by display_name ASC, entity_id ASC.

func (*Store) GetDescendants 

func (s *Store) GetDescendants(ctx context.Context, entityID string) ([]*inventory.Entity, error)

GetDescendants retrieves all descendants using path prefix matching, ordered by depth ASC, display_name ASC, entity_id ASC. GetDescendants retrieves all non-removed descendants using path prefix matching, ordered by depth ASC, display_name ASC, entity_id ASC.

func (*Store) GetDescendantsTx 

func (s *Store) GetDescendantsTx(ctx context.Context, tx Tx, entityID string) ([]*inventory.Entity, error)

GetDescendantsTx retrieves all descendants of a given entity inside an existing transaction, using path prefix matching. Ordered by depth ASC, display_name ASC, entity_id ASC.

func (*Store) GetEntitiesByCanonicalName 

func (s *Store) GetEntitiesByCanonicalName(ctx context.Context, canonical string) ([]*inventory.Entity, error)

GetEntitiesByCanonicalName retrieves all entities with a given canonical name, ordered by full_path_canonical ASC, entity_id ASC. GetEntitiesByCanonicalName retrieves all non-removed entities with a given canonical name, ordered by full_path_canonical ASC, entity_id ASC.

func (*Store) GetEntity 

func (s *Store) GetEntity(ctx context.Context, entityID string) (*inventory.Entity, error)

GetEntity retrieves a single entity by ID. GetEntity retrieves a single non-removed entity by ID.

func (*Store) GetEntityTx 

func (s *Store) GetEntityTx(ctx context.Context, tx Tx, entityID string) (*inventory.Entity, error)

GetEntityTx retrieves a single entity by ID inside an existing transaction.

func (*Store) GetEventByID 

func (s *Store) GetEventByID(ctx context.Context, eventID int64) (*inventory.Event, error)

GetEventByID retrieves a single event by its ID.

func (*Store) GetEventsByEntity 

func (s *Store) GetEventsByEntity(ctx context.Context, entityID string) ([]*inventory.Event, error)

GetEventsByEntity retrieves all events for a given entity ID, ordered by event_id ASC.

func (*Store) GetMetadata 

func (s *Store) GetMetadata(ctx context.Context, key string) (string, error)

GetMetadata retrieves a value from the schema_metadata table by key.

func (*Store) GetMigrationVersion 

func (s *Store) GetMigrationVersion() (uint, bool, error)

GetMigrationVersion returns the current schema version and dirty state.

func (*Store) GetTagsByEntities added in v0.6.0 

func (s *Store) GetTagsByEntities(ctx context.Context, entityIDs []string) (map[string][]string, error)

GetTagsByEntities returns a map of entityID → sorted tag slice for all given IDs. IDs absent from entity_tags are not present in the returned map (nil slice on lookup). Returns an empty map immediately when entityIDs is empty.

func (*Store) GetTagsByEntity added in v0.6.0 

func (s *Store) GetTagsByEntity(ctx context.Context, entityID string) ([]string, error)

GetTagsByEntity returns all tags for entityID, sorted alphabetically.

func (*Store) HasEvents added in v0.4.0 

func (s *Store) HasEvents(ctx context.Context) (bool, error)

HasEvents reports whether the events table contains at least one row.

func (*Store) InsertEntityTx 

func (s *Store) InsertEntityTx(ctx context.Context, tx Tx, e *inventory.Entity) error

InsertEntityTx inserts a new entity projection row inside an existing transaction.

func (*Store) InsertTagTx added in v0.6.0 

func (s *Store) InsertTagTx(ctx context.Context, tx Tx, entityID, tag string) error

InsertTagTx inserts a tag for entityID within the given transaction. Duplicate inserts are a no-op.

func (*Store) ListAllEntities added in v0.5.0 

func (s *Store) ListAllEntities(ctx context.Context) ([]*inventory.Entity, error)

ListAllEntities returns all entities in the projection, including removed ones.

func (*Store) ListEntities 

func (s *Store) ListEntities(ctx context.Context) ([]*inventory.Entity, error)

ListEntities retrieves all entities ordered by full_path_display ASC, entity_id ASC. ListEntities retrieves all non-removed entities ordered by full_path_display ASC, entity_id ASC.

func (*Store) RunMigrations 

func (s *Store) RunMigrations() error

RunMigrations applies all pending migrations to the database.

func (*Store) SetMetadata 

func (s *Store) SetMetadata(ctx context.Context, key, value string) error

SetMetadata upserts a key/value pair in the schema_metadata table.

func (*Store) TruncateEntitiesTx added in v0.5.0 

func (s *Store) TruncateEntitiesTx(ctx context.Context, tx Tx) error

TruncateEntitiesTx deletes all rows from entities_current within the supplied transaction.

func (*Store) TruncateTagsTx added in v0.6.0 

func (s *Store) TruncateTagsTx(ctx context.Context, tx Tx) error

TruncateTagsTx deletes all rows from entity_tags within the given transaction.

func (*Store) UpdateEntityTx 

func (s *Store) UpdateEntityTx(ctx context.Context, tx Tx, e *inventory.Entity) error

UpdateEntityTx updates an existing entity projection row inside an existing transaction.

func (*Store) WithRetry 

func (s *Store) WithRetry(ctx context.Context, fn func() error) error

WithRetry retries fn on SQLite BUSY/LOCKED errors with jittered backoff.

type Tx 

type Tx interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Tx is the interface passed to functions running inside ExecInTransaction. It exposes only the query methods needed by store operations.

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.