store

Documentation

Overview

Package store wires Chronos's persistence backends behind a single scheme-dispatched factory.

Each provider (memory, sqlite, postgres, libsql, mysql, ...) lives in a subpackage and registers itself in init() with Register. Consumers blank-import the providers they want to support and open connections by DSN through Open. The factory dispatches on the URL scheme so new providers can be added without touching this package.

This pattern mirrors Mnemos's ADR 0001 across the cognitive stack (Mnemos, Chronos, Praxis, Nous): the factory contract, URL convention, and namespace primitive are shared; the shape of Conn is per-tool.

Index

• Constants
• Variables
• func LegacyDSN(dbType, conn string) (string, error)
• func ParseNamespace(u *url.URL) (string, error)
• func Register(scheme string, fn OpenFunc)
• func SupportedSchemes() []string
• type Conn
  • func Open(ctx context.Context, dsn string) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) InTx(ctx context.Context, fn func(context.Context) error) error
• type OpenFunc

Constants

const DefaultNamespace = "chronos"

DefaultNamespace is used when a DSN omits ?namespace=. Single-tenant local deployments rarely need to touch this; multi-tool clusters (Mnemos + Chronos in one Postgres) set it explicitly per tool.

Variables

var ErrNotTransactional = fmt.Errorf("store: provider does not support transactions")

ErrNotTransactional is returned by Conn.InTx when the underlying provider does not support transactions. Callers checking ports.Transactional via type-assertion will succeed for any Conn (Conn always has the InTx method) but should be prepared for this error from a provider that opts out — typically the memory backend in tests.

Functions

func LegacyDSN

func LegacyDSN(dbType, conn string) (string, error)

LegacyDSN converts the deprecated CHRONOS_DB_TYPE + CHRONOS_DB_CONN pair into the new DSN form. It exists to keep existing operator configurations working through the cutover; new deployments should set CHRONOS_DB_DSN directly.

The translation:

memory                          -> memory://
sqlite / sqlite3, path          -> sqlite:///<path>   (or sqlite://:memory: for ":memory:")
postgres / postgresql, libpq    -> postgres://...     (libpq URL is already a DSN; pass through)

If dbType is empty, the empty DSN is returned and the caller should fall back to its own default.

func ParseNamespace

func ParseNamespace(u *url.URL) (string, error)

ParseNamespace extracts the namespace from a parsed URL's query string, applying DefaultNamespace when absent and validating against [namespaceRE]. Providers call this when they need to translate the namespace into a native isolation primitive.

func Register

func Register(scheme string, fn OpenFunc)

Register associates a URL scheme with a provider factory. Providers invoke this from init(); duplicate registration panics so collisions surface at startup rather than silently shadowing.

func SupportedSchemes

func SupportedSchemes() []string

SupportedSchemes returns the registered scheme names in sorted order. Useful for error messages and CLI help.

Types

type Conn

type Conn struct {
	EntityStates ports.EntityStateRepository
	Signals      ports.SignalRepository

	// Raw is the provider's underlying handle (e.g. *sql.DB for the
	// SQL providers, an in-memory state struct for memory). It is
	// nil-safe to ignore. Tests and provider-specific helpers
	// type-assert against it; the engine itself does not.
	Raw any

	// Closer releases backend resources. Providers populate it; Close
	// invokes it. Repositories must not be used after Close returns.
	Closer func() error

	// Tx, when non-nil, advertises that the provider supports atomic
	// multi-statement units of work and supplies the implementation
	// behind [Conn.InTx]. SQL providers populate it with a BeginTx
	// wrapper; the memory provider leaves it nil because it has no
	// real cross-repository transaction semantics.
	Tx func(ctx context.Context, fn func(context.Context) error) error
}

Conn is the engine's port-typed view of an open backend. Every provider returns a Conn populated with concrete repositories that satisfy the ports interfaces.

func Open

func Open(ctx context.Context, dsn string) (*Conn, error)

Open opens a backend by DSN. The DSN's URL scheme picks the provider; everything after the scheme is provider-specific.

Examples:

memory://?namespace=chronos
sqlite:///var/lib/chronos/chronos.db
postgres://user:pw@host:5432/cogstack?namespace=chronos
mysql://user:pw@host:3306/?namespace=chronos
libsql://my-db.turso.io?authToken=...

The matching provider must have been blank-imported by the binary (e.g. _ "github.com/felixgeelhaar/chronos/internal/store/sqlite") so that its init() runs before Open is called.

func (*Conn) Close

func (c *Conn) Close() error

Close releases backend resources. Safe to call on a nil Conn or one without a Closer set.

func (*Conn) InTx

func (c *Conn) InTx(ctx context.Context, fn func(context.Context) error) error

InTx satisfies ports.Transactional for any Conn whose Tx field has been populated by the provider. fn runs inside a provider- native transaction; returning a non-nil error rolls back, returning nil commits. Repositories that mutate state inside fn do *not* yet auto-participate in the transaction — callers wanting strict cross-repository atomicity reach through Conn.Raw to issue queries against the *sql.Tx provided by Tx. Future work will route repository writes through the tx automatically (Mnemos ADR 0001 §4 describes the same evolution arc).

type OpenFunc

type OpenFunc func(ctx context.Context, dsn string) (*Conn, error)

OpenFunc is the provider-side factory signature. Each provider registers one of these per scheme it handles.