Documentation
¶
Overview ¶
Package db provides a multi-layer database abstraction supporting: - User-level SQLite with sqlite-vec for personal data and vector search - Organization-level SQLite for shared tenant data - PostgreSQL with pgvector for scalable deployments - MongoDB/FerretDB for document storage - Hanzo Datastore (ClickHouse) for deep analytics
ZAP protocol driver for the ORM.
ZAP (Zero-Copy App Proto) uses binary encoding over RPC, communicating with zap-sidecar backends (SQL, KV, Datastore, DocumentDB). Structs are encoded directly into the ZAP binary format — no JSON serialization step for storage fields. Complex types (slices, maps, nested structs) are transmitted natively, eliminating the need for Foo/Foo_ field pairs.
Index ¶
- Variables
- func GenerateID() string
- func LowercaseFirst(s string) string
- func NormalizeOp(op string) string
- func ParseFilterString(s string) (field, op string)
- func PoolFromDB(d DB) (*pgxpool.Pool, bool)
- func ToJSONFieldName(field string) string
- type AfterCreateHook
- type AfterDeleteHook
- type AfterUpdateHook
- type AnalyticsBatch
- type AnalyticsRows
- type AnalyticsStore
- type BeforeCreateHook
- type BeforeDeleteHook
- type BeforeUpdateHook
- type Config
- type Cursor
- type DB
- type DatastoreConfig
- type Entity
- type IsolationLevel
- type Iterator
- type Key
- type Kind
- type Layer
- type Manager
- func (m *Manager) Analytics() AnalyticsStore
- func (m *Manager) Close() error
- func (m *Manager) Org(orgID string) (DB, error)
- func (m *Manager) RegisterOrgDB(orgID string, db DB)
- func (m *Manager) RegisterUserDB(userID string, db DB)
- func (m *Manager) SetAnalyticsStore(store AnalyticsStore)
- func (m *Manager) User(userID string) (DB, error)
- type Model
- func (m *Model) Create(ctx context.Context) error
- func (m *Model) DB() DB
- func (m *Model) Delete(ctx context.Context) error
- func (m *Model) Entity() Kind
- func (m *Model) Exists(ctx context.Context) (bool, error)
- func (m *Model) Get(ctx context.Context) error
- func (m *Model) GetByID(ctx context.Context, id string) error
- func (m *Model) GetID() string
- func (m *Model) GetKind() string
- func (m *Model) GetNamespace() string
- func (m *Model) Init(database DB, entity Kind)
- func (m *Model) IsCreated() bool
- func (m *Model) IsLoaded() bool
- func (m *Model) JSON() ([]byte, error)
- func (m *Model) JSONString() string
- func (m *Model) Key() Key
- func (m *Model) MarkLoaded()
- func (m *Model) ModelQuery() Query
- func (m *Model) MustGet(ctx context.Context)
- func (m *Model) MustGetByID(ctx context.Context, id string)
- func (m *Model) MustPut(ctx context.Context)
- func (m *Model) Put(ctx context.Context) error
- func (m *Model) RunInTransaction(ctx context.Context, fn func(tx Transaction) error) error
- func (m *Model) SetDB(database DB)
- func (m *Model) SetEntity(entity Kind)
- func (m *Model) SetID(id string)
- func (m *Model) SetKey(key Key) error
- func (m *Model) SetKeyFromString(id string) error
- func (m *Model) SetNamespace(ns string)
- func (m *Model) SoftDelete(ctx context.Context) error
- func (m *Model) Update(ctx context.Context) error
- type PostgresConfig
- type PostgresDB
- type Query
- type QueryFilter
- type QueryOrder
- type SQLConfig
- type SQLDB
- func (db *SQLDB) AllocateIDs(kind string, parent Key, n int) ([]Key, error)
- func (db *SQLDB) Close() error
- func (db *SQLDB) Delete(ctx context.Context, key Key) error
- func (db *SQLDB) DeleteMulti(ctx context.Context, keys []Key) error
- func (db *SQLDB) Get(ctx context.Context, key Key, dst interface{}) error
- func (db *SQLDB) GetMulti(ctx context.Context, keys []Key, dst interface{}) error
- func (db *SQLDB) NewIncompleteKey(kind string, parent Key) Key
- func (db *SQLDB) NewKey(kind string, stringID string, intID int64, parent Key) Key
- func (db *SQLDB) Pool() *pgxpool.Pool
- func (db *SQLDB) Put(ctx context.Context, key Key, src interface{}) (Key, error)
- func (db *SQLDB) PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)
- func (db *SQLDB) PutVector(ctx context.Context, kind string, id string, vector []float32, ...) error
- func (db *SQLDB) Query(kind string) Query
- func (db *SQLDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
- func (db *SQLDB) TenantID() string
- func (db *SQLDB) TenantType() string
- func (db *SQLDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
- type SQLiteConfig
- type SQLiteDB
- func (db *SQLiteDB) AllocateIDs(kind string, parent Key, n int) ([]Key, error)
- func (db *SQLiteDB) Close() error
- func (db *SQLiteDB) Delete(ctx context.Context, key Key) error
- func (db *SQLiteDB) DeleteMulti(ctx context.Context, keys []Key) error
- func (db *SQLiteDB) Get(ctx context.Context, key Key, dst interface{}) error
- func (db *SQLiteDB) GetMulti(ctx context.Context, keys []Key, dst interface{}) error
- func (db *SQLiteDB) NewIncompleteKey(kind string, parent Key) Key
- func (db *SQLiteDB) NewKey(kind string, stringID string, intID int64, parent Key) Key
- func (db *SQLiteDB) Put(ctx context.Context, key Key, src interface{}) (Key, error)
- func (db *SQLiteDB) PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)
- func (db *SQLiteDB) PutVector(ctx context.Context, kind string, id string, vector []float32, ...) error
- func (db *SQLiteDB) Query(kind string) Query
- func (db *SQLiteDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
- func (db *SQLiteDB) TenantID() string
- func (db *SQLiteDB) TenantType() string
- func (db *SQLiteDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
- type SQLiteDBConfig
- type SimpleCursor
- type Syncable
- type Transaction
- type TransactionOptions
- type Validator
- type VectorResult
- type VectorSearchOptions
- type ZapBackend
- type ZapConfig
- type ZapDB
- func (z *ZapDB) AllocateIDs(kind string, parent Key, n int) ([]Key, error)
- func (z *ZapDB) Close() error
- func (z *ZapDB) Delete(ctx context.Context, key Key) error
- func (z *ZapDB) DeleteMulti(ctx context.Context, keys []Key) error
- func (z *ZapDB) Get(ctx context.Context, key Key, dst interface{}) error
- func (z *ZapDB) GetMulti(ctx context.Context, keys []Key, dst interface{}) error
- func (z *ZapDB) NewIncompleteKey(kind string, parent Key) Key
- func (z *ZapDB) NewKey(kind string, stringID string, intID int64, parent Key) Key
- func (z *ZapDB) Put(ctx context.Context, key Key, src interface{}) (Key, error)
- func (z *ZapDB) PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)
- func (z *ZapDB) PutVector(ctx context.Context, kind string, id string, vector []float32, ...) error
- func (z *ZapDB) Query(kind string) Query
- func (z *ZapDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
- func (z *ZapDB) TenantID() string
- func (z *ZapDB) TenantType() string
- func (z *ZapDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoSuchEntity is returned when an entity is not found. ErrNoSuchEntity = errors.New("db: no such entity") // ErrInvalidKey is returned when a key is invalid. ErrInvalidKey = errors.New("db: invalid key") // ErrInvalidEntityType is returned when an entity type is invalid. ErrInvalidEntityType = errors.New("db: invalid entity type") // ErrConcurrentModification is returned when optimistic locking fails. ErrConcurrentModification = errors.New("db: concurrent modification") // ErrDatabaseClosed is returned when operating on a closed database. ErrDatabaseClosed = errors.New("db: database closed") // ErrValidationFailed is returned when entity validation fails. ErrValidationFailed = errors.New("db: validation failed") // ErrEntityNotFound aliases ErrNoSuchEntity. ErrEntityNotFound = ErrNoSuchEntity )
var NewPostgresDB = NewSQLDB
NewPostgresDB is an alias for NewSQLDB.
Functions ¶
func LowercaseFirst ¶
LowercaseFirst lowercases the first character of a string.
func ParseFilterString ¶
ParseFilterString parses "Field=" into field and operator.
func PoolFromDB ¶ added in v0.3.2
PoolFromDB extracts the pgxpool.Pool from a SQLDB (if it is one).
func ToJSONFieldName ¶
ToJSONFieldName converts a Go struct field name (PascalCase) to its JSON equivalent (camelCase) by lowercasing the first letter of each path segment. Handles nested paths like "Account.TransactionHash" → "account.transactionHash".
Types ¶
type AfterCreateHook ¶
type AfterCreateHook interface {
AfterCreate() error
}
AfterCreateHook is called after entity creation.
type AfterDeleteHook ¶
type AfterDeleteHook interface {
AfterDelete() error
}
AfterDeleteHook is called after entity deletion.
type AfterUpdateHook ¶
type AfterUpdateHook interface {
AfterUpdate(prev interface{}) error
}
AfterUpdateHook is called after entity update.
type AnalyticsBatch ¶
type AnalyticsBatch interface {
Append(v ...interface{}) error
AppendStruct(v interface{}) error
Flush() error
Send() error
Abort() error
Rows() int
Close() error
}
AnalyticsBatch for bulk inserts into analytics store.
type AnalyticsRows ¶
type AnalyticsRows interface {
Next() bool
Scan(dest ...interface{}) error
ScanStruct(dest interface{}) error
Columns() []string
Close() error
Err() error
}
AnalyticsRows represents analytics query results.
type AnalyticsStore ¶
type AnalyticsStore interface {
Query(ctx context.Context, query string, args ...interface{}) (AnalyticsRows, error)
Select(ctx context.Context, dest interface{}, query string, args ...interface{}) error
Exec(ctx context.Context, query string, args ...interface{}) error
PrepareBatch(ctx context.Context, query string) (AnalyticsBatch, error)
AsyncInsert(ctx context.Context, query string, wait bool, args ...interface{}) error
Close() error
}
AnalyticsStore is the interface for analytics queries (e.g. ClickHouse).
type BeforeCreateHook ¶
type BeforeCreateHook interface {
BeforeCreate() error
}
BeforeCreateHook is called before entity creation.
type BeforeDeleteHook ¶
type BeforeDeleteHook interface {
BeforeDelete() error
}
BeforeDeleteHook is called before entity deletion.
type BeforeUpdateHook ¶
type BeforeUpdateHook interface {
BeforeUpdate(prev interface{}) error
}
BeforeUpdateHook is called before entity update.
type Config ¶
type Config struct {
DataDir string
UserDataDir string
OrgDataDir string
DatastoreDSN string
EnableDatastore bool
EnableVectorSearch bool
VectorDimensions int
SQLite SQLiteConfig
Datastore DatastoreConfig
IsDev bool
}
Config holds database configuration options.
type Cursor ¶
type Cursor interface {
String() string
}
Cursor represents a position in a result set.
func DecodeCursor ¶
DecodeCursor parses a cursor string.
type DB ¶
type DB interface {
// Core operations
Get(ctx context.Context, key Key, dst interface{}) error
Put(ctx context.Context, key Key, src interface{}) (Key, error)
Delete(ctx context.Context, key Key) error
// Batch operations
GetMulti(ctx context.Context, keys []Key, dst interface{}) error
PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)
DeleteMulti(ctx context.Context, keys []Key) error
// Query
Query(kind string) Query
// Vector search
VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
PutVector(ctx context.Context, kind string, id string, vector []float32, metadata map[string]interface{}) error
// Key management
NewKey(kind string, stringID string, intID int64, parent Key) Key
NewIncompleteKey(kind string, parent Key) Key
AllocateIDs(kind string, parent Key, n int) ([]Key, error)
// Transactions
RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
// Lifecycle
Close() error
// Tenant info
TenantID() string
TenantType() string
}
DB is the main database interface for entity storage.
type DatastoreConfig ¶
type DatastoreConfig struct {
MaxOpenConns int
MaxIdleConns int
ConnMaxLifetime time.Duration
Compression string
QueryTimeout time.Duration
}
DatastoreConfig holds Hanzo Datastore (ClickHouse) configuration.
type Entity ¶
type Entity interface {
Kind() string
}
Entity is the interface that all model entities should implement.
type IsolationLevel ¶
type IsolationLevel int
IsolationLevel represents transaction isolation levels.
const ( IsolationDefault IsolationLevel = iota IsolationReadUncommitted IsolationReadCommitted IsolationRepeatableRead IsolationSerializable )
type Key ¶
type Key interface {
Kind() string
StringID() string
IntID() int64
Parent() Key
Namespace() string
Incomplete() bool
Encode() string
Equal(other Key) bool
}
Key represents a unique identifier for an entity.
type Kind ¶
type Kind interface {
Kind() string
}
Kind interface for entities with a kind/table name.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the main entry point for database operations. It manages multiple database layers and provides unified access.
func NewManager ¶
NewManager creates a new database manager.
func (*Manager) Analytics ¶
func (m *Manager) Analytics() AnalyticsStore
Analytics returns the analytics store.
func (*Manager) RegisterOrgDB ¶
RegisterOrgDB registers an organization database.
func (*Manager) RegisterUserDB ¶
RegisterUserDB registers a user database.
func (*Manager) SetAnalyticsStore ¶
func (m *Manager) SetAnalyticsStore(store AnalyticsStore)
SetAnalyticsStore sets the analytics store for the manager.
type Model ¶
type Model struct {
Parent Key `json:"-"`
ID string `json:"id,omitempty"`
CreatedAt time.Time `json:"createdAt,omitempty"`
UpdatedAt time.Time `json:"updatedAt,omitempty"`
Deleted bool `json:"deleted,omitempty"`
Version int64 `json:"version,omitempty"`
Namespace_ string `json:"-"`
Mock bool `json:"-"`
UseStringKey bool `json:"-"`
// contains filtered or unexported fields
}
Model is a base type that provides common functionality for entities. Embed this in your entity structs for non-generic model usage.
func (*Model) GetNamespace ¶
GetNamespace returns the namespace for this entity.
func (*Model) JSONString ¶
JSONString returns the JSON string representation.
func (*Model) ModelQuery ¶
ModelQuery returns a new query for this entity's kind.
func (*Model) MustGetByID ¶
MustGetByID retrieves by ID or panics.
func (*Model) RunInTransaction ¶
RunInTransaction executes a function within a transaction.
func (*Model) SetKeyFromString ¶
SetKeyFromString sets the key from a string ID.
func (*Model) SetNamespace ¶
SetNamespace sets the namespace.
func (*Model) SoftDelete ¶
SoftDelete marks the entity as deleted without removing it.
type PostgresConfig ¶ added in v0.3.2
type PostgresConfig = SQLConfig
Aliases for backward compatibility.
type PostgresDB ¶ added in v0.3.2
type PostgresDB = SQLDB
type Query ¶
type Query interface {
Filter(filterStr string, value interface{}) Query
FilterField(fieldPath string, op string, value interface{}) Query
Order(fieldPath string) Query
OrderDesc(fieldPath string) Query
Limit(limit int) Query
Offset(offset int) Query
Project(fieldNames ...string) Query
Distinct() Query
Ancestor(ancestor Key) Query
GetAll(ctx context.Context, dst interface{}) ([]Key, error)
First(ctx context.Context, dst interface{}) (Key, error)
Count(ctx context.Context) (int, error)
Keys(ctx context.Context) ([]Key, error)
Run(ctx context.Context) Iterator
Start(cursor Cursor) Query
End(cursor Cursor) Query
}
Query provides a fluent interface for querying entities.
type QueryFilter ¶
QueryFilter holds a filter condition.
type QueryOrder ¶
QueryOrder holds an order directive.
type SQLConfig ¶ added in v0.3.2
type SQLConfig struct {
DSN string // connection string (e.g. postgres://user:pass@host:port/dbname)
MaxConns int32
MinConns int32
TablePrefix string
SchemaName string // "public" by default
TenantID string
TenantType string
}
SQLConfig holds configuration for a SQL database.
type SQLDB ¶ added in v0.3.2
type SQLDB struct {
// contains filtered or unexported fields
}
SQLDB implements the DB interface using pgx/v5.
func (*SQLDB) AllocateIDs ¶ added in v0.3.2
func (*SQLDB) DeleteMulti ¶ added in v0.3.2
func (*SQLDB) NewIncompleteKey ¶ added in v0.3.2
func (*SQLDB) RunInTransaction ¶ added in v0.3.2
func (db *SQLDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
func (*SQLDB) TenantType ¶ added in v0.3.2
func (*SQLDB) VectorSearch ¶ added in v0.3.2
func (db *SQLDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
type SQLiteConfig ¶
type SQLiteConfig struct {
MaxOpenConns int
MaxIdleConns int
BusyTimeout int
JournalMode string
Synchronous string
CacheSize int
QueryTimeout time.Duration
}
SQLiteConfig holds SQLite-specific configuration.
type SQLiteDB ¶
type SQLiteDB struct {
// contains filtered or unexported fields
}
SQLiteDB implements the DB interface using SQLite.
func NewSQLiteDB ¶
func NewSQLiteDB(cfg *SQLiteDBConfig) (*SQLiteDB, error)
NewSQLiteDB creates a new SQLite database connection.
func (*SQLiteDB) AllocateIDs ¶
func (*SQLiteDB) DeleteMulti ¶
func (*SQLiteDB) NewIncompleteKey ¶
func (*SQLiteDB) RunInTransaction ¶
func (db *SQLiteDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
func (*SQLiteDB) TenantType ¶
func (*SQLiteDB) VectorSearch ¶
func (db *SQLiteDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)
type SQLiteDBConfig ¶
type SQLiteDBConfig struct {
Path string
Config SQLiteConfig
EnableVectorSearch bool
VectorDimensions int
TenantID string
TenantType string
}
SQLiteDBConfig holds configuration for a SQLite database.
type SimpleCursor ¶
SimpleCursor is a basic cursor implementation.
func (*SimpleCursor) String ¶
func (c *SimpleCursor) String() string
type Transaction ¶
type Transaction interface {
Get(key Key, dst interface{}) error
Put(key Key, src interface{}) (Key, error)
Delete(key Key) error
Query(kind string) Query
}
Transaction represents a database transaction.
type TransactionOptions ¶
type TransactionOptions struct {
ReadOnly bool
MaxAttempts int
Isolation IsolationLevel
}
TransactionOptions configures transaction behavior.
type Validator ¶
type Validator interface {
Validate() error
}
Validator interface for entities that support validation.
type VectorResult ¶
VectorResult represents a vector search result.
type VectorSearchOptions ¶
type VectorSearchOptions struct {
Kind string
Vector []float32
Limit int
MinScore float32
Filters map[string]interface{}
}
VectorSearchOptions configures vector similarity search.
type ZapBackend ¶ added in v0.2.0
type ZapBackend int
ZapBackend selects which zap-sidecar proxy to target.
const ( // ZapSQL targets the SQL proxy (PostgreSQL via pgx). ZapSQL ZapBackend = iota // ZapDocumentDB targets the DocumentDB proxy (MongoDB/FerretDB). ZapDocumentDB // ZapKV targets the KV proxy (Redis/Valkey). ZapKV // ZapDatastore targets the Datastore proxy (ClickHouse). ZapDatastore )
type ZapConfig ¶ added in v0.2.0
type ZapConfig struct {
// Addr is the zap-sidecar address (e.g., "localhost:9651").
Addr string
// Backend selects which proxy to target.
Backend ZapBackend
// Database is the target database name (for SQL/DocumentDB backends).
Database string
// Collection is the default collection/table for entity storage.
// Defaults to "_entities" for SQL, "entities" for DocumentDB.
Collection string
// NodeID is this client's node ID for ZAP peer identification.
NodeID string
// QueryTimeout is the per-query timeout (default 30s).
QueryTimeout time.Duration
// Logger for ZAP node (optional).
Logger *slog.Logger
}
ZapConfig configures a ZAP database connection.
type ZapDB ¶ added in v0.2.0
type ZapDB struct {
// contains filtered or unexported fields
}
ZapDB implements db.DB over ZAP binary protocol.
func (*ZapDB) AllocateIDs ¶ added in v0.2.0
func (*ZapDB) DeleteMulti ¶ added in v0.2.0
func (*ZapDB) NewIncompleteKey ¶ added in v0.2.0
func (*ZapDB) RunInTransaction ¶ added in v0.2.0
func (z *ZapDB) RunInTransaction(ctx context.Context, fn func(tx Transaction) error, opts *TransactionOptions) error
func (*ZapDB) TenantType ¶ added in v0.2.0
func (*ZapDB) VectorSearch ¶ added in v0.2.0
func (z *ZapDB) VectorSearch(ctx context.Context, opts *VectorSearchOptions) ([]VectorResult, error)