Go Packages

Package Index

Package	Import Path	Description
`grove`	`github.com/xraph/grove`	Core types: DB, BaseModel, Open(), RegisterModel()
`schema`	`github.com/xraph/grove/schema`	Schema reflection: Table, Field, Relation, Registry
`driver`	`github.com/xraph/grove/driver`	Driver and Dialect interfaces
`scan`	`github.com/xraph/grove/scan`	Result scanning with cached field maps
`hook`	`github.com/xraph/grove/hook`	Privacy hooks: PreQuery, PostQuery, PreMutation, PostMutation, StreamRowHook
`stream`	`github.com/xraph/grove/stream`	Streaming iterator: Stream[T], pipeline transforms, ChangeStream[T]
`migrate`	`github.com/xraph/grove/migrate`	Migration system: Group, Migration, Orchestrator
`pgdriver`	`github.com/xraph/grove/drivers/pgdriver`	PostgreSQL driver (pgx-based)
`mysqldriver`	`github.com/xraph/grove/drivers/mysqldriver`	MySQL driver
`sqlitedriver`	`github.com/xraph/grove/drivers/sqlitedriver`	SQLite driver (pure Go)
`mongodriver`	`github.com/xraph/grove/drivers/mongodriver`	MongoDB driver
`tursodriver`	`github.com/xraph/grove/drivers/tursodriver`	Turso/libSQL driver
`clickhousedriver`	`github.com/xraph/grove/drivers/clickhousedriver`	ClickHouse driver
`esdriver`	`github.com/xraph/grove/drivers/esdriver`	Elasticsearch driver
`plugin`	`github.com/xraph/grove/plugin`	Plugin interfaces and registry
`grovetest`	`github.com/xraph/grove/grovetest`	Testing utilities: mock driver, fixtures, assertions
`extension`	`github.com/xraph/grove/extension`	Forge extension entry point
`audit`	`github.com/xraph/grove/audit`	Chronicle audit plugin
`observability`	`github.com/xraph/grove/observability`	Prometheus metrics plugin
`internal/tagparser`	`github.com/xraph/grove/internal/tagparser`	High-performance struct tag parser
`internal/pool`	`github.com/xraph/grove/internal/pool`	sync.Pool-based byte buffer pool
`internal/safe`	`github.com/xraph/grove/internal/safe`	Safe identifier quoting
KV Module
`kv`	`github.com/xraph/grove/kv`	Core KV Store: Open, Get, Set, Delete, Exists, MGet, MSet
`kv/driver`	`github.com/xraph/grove/kv/driver`	KV Driver interface, capabilities, optional interfaces
`kv/codec`	`github.com/xraph/grove/kv/codec`	Codecs: JSON, MsgPack, Protobuf, Gob
`kv/keyspace`	`github.com/xraph/grove/kv/keyspace`	Keyspace[T] typed key-value partitions
`kv/middleware`	`github.com/xraph/grove/kv/middleware`	Middleware: cache, retry, circuit, compress, encrypt, namespace, logging, stampede
`kv/crdt`	`github.com/xraph/grove/kv/crdt`	CRDT adapter: Counter, Register[T], Set[T], Map, Syncer
`kv/plugins`	`github.com/xraph/grove/kv/plugins`	Plugins: lock, ratelimit, session, counter, leaderboard, queue
`kv/extension`	`github.com/xraph/grove/kv/extension`	Forge extension: multi-store KV with DI, config, lifecycle
`kv/redisdriver`	`github.com/xraph/grove/kv/drivers/redisdriver`	Redis KV driver (go-redis)
`kv/memcacheddriver`	`github.com/xraph/grove/kv/drivers/memcacheddriver`	Memcached KV driver (gomemcache)
`kv/dynamodriver`	`github.com/xraph/grove/kv/drivers/dynamodriver`	DynamoDB KV driver (aws-sdk-go-v2)
`kv/boltdriver`	`github.com/xraph/grove/kv/drivers/boltdriver`	BoltDB KV driver (bbolt)
`kv/badgerdriver`	`github.com/xraph/grove/kv/drivers/badgerdriver`	Badger KV driver (badger/v4)
`kv/kvtest`	`github.com/xraph/grove/kv/kvtest`	KV conformance test suite and mock driver

Core Types

grove.DB

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

// Open creates a new DB with an already-connected driver.
// The driver must be connected before calling Open (call driver.Open first).
//
//   pgdb := pgdriver.New()
//   pgdb.Open(ctx, "postgres://localhost:5432/mydb")
//   db, err := grove.Open(pgdb)
func Open(drv GroveDriver, opts ...Option) (*DB, error)

func (db *DB) Close() error
func (db *DB) Ping(ctx context.Context) error
func (db *DB) RegisterModel(models ...any)

// Driver returns the underlying GroveDriver.
// Use with pgdriver.Unwrap(db) for typed access.
func (db *DB) Driver() GroveDriver

// Hooks returns the hook engine for registering lifecycle hooks.
//   db.Hooks().AddHook(&TenantIsolation{}, hook.Scope{Tables: []string{"users"}})
func (db *DB) Hooks() *hook.Engine

// Query builders return any; use pgdriver.Unwrap(db) for typed builders.
func (db *DB) NewSelect(model ...any) any
func (db *DB) NewInsert(model any) any
func (db *DB) NewUpdate(model any) any
func (db *DB) NewDelete(model any) any

func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error)

grove.BaseModel

type BaseModel struct{}

Embed in your model structs to declare them as Grove models. Tag with grove:"table:name,alias:a".

grove.Option

func WithPoolSize(n int) Option
func WithQueryTimeout(d time.Duration) Option
func WithLogger(l *slog.Logger) Option
func WithPlugin(p plugin.Plugin) Option

Driver Interfaces

driver.Driver

type Driver interface {
    Name() string
    Open(ctx context.Context, dsn string, opts ...Option) error
    Close() error
    Dialect() Dialect
    Ping(ctx context.Context) error
    BeginTx(ctx context.Context, opts *TxOptions) (Tx, error)
    Exec(ctx context.Context, query string, args ...any) (Result, error)
    Query(ctx context.Context, query string, args ...any) (Rows, error)
    QueryRow(ctx context.Context, query string, args ...any) Row
    SupportsReturning() bool
}

driver.StreamCapable

Optional interface for drivers that support streaming and CDC:

type StreamCapable interface {
    SupportsStreaming() bool
    SupportsCDC() bool
}

driver.Dialect

type Dialect interface {
    Name() string
    Quote(ident string) string
    Placeholder(index int) string
    GoToDBType(goType reflect.Type) string
    AppendBytes(b []byte, data []byte) []byte
    AppendTime(b []byte, t time.Time) []byte
}

Hook Types

hook.Scope

type Scope struct {
    Tables     []string    // restrict to these tables (empty = all)
    Operations []Operation // restrict to these operations (empty = all)
    Priority   int         // execution order, lower = earlier (default: 100)
}

Hook Interfaces

type PreQueryHook interface {
    BeforeQuery(ctx context.Context, qc *QueryContext) (*HookResult, error)
}

type PostQueryHook interface {
    AfterQuery(ctx context.Context, qc *QueryContext, result any) error
}

type PreMutationHook interface {
    BeforeMutation(ctx context.Context, qc *QueryContext, data any) (*HookResult, error)
}

type PostMutationHook interface {
    AfterMutation(ctx context.Context, qc *QueryContext, data any, result any) error
}

type StreamRowHook interface {
    OnStreamRow(ctx context.Context, qc *QueryContext, row any) (Decision, error)
}

hook.Decision

type Decision int

const (
    Allow  Decision = iota // proceed with the query
    Deny                    // block the query, return error
    Modify                  // hook modified query context
    Skip                    // exclude this row (post-query / stream)
)

Stream Types

stream.Stream[T]

func New[T any](cursor Cursor, decode DecodeFunc[T]) *Stream[T]
func NewWithHooks[T any](cursor Cursor, decode DecodeFunc[T], hooks HookRunner, qc any) *Stream[T]

func (s *Stream[T]) WithHooks(runner HookRunner, qc any) *Stream[T]
func (s *Stream[T]) Next(ctx context.Context) bool
func (s *Stream[T]) Value() T
func (s *Stream[T]) Err() error
func (s *Stream[T]) Close() error
func (s *Stream[T]) All(yield func(T, error) bool)           // Go 1.23+ range-over-func
func (s *Stream[T]) Collect(ctx context.Context) ([]T, error)
func (s *Stream[T]) Count(ctx context.Context) (int64, error)

Pipeline Transforms

func Map[T, U any](s *Stream[T], fn func(T) (U, error)) *Stream[U]
func Filter[T any](s *Stream[T], fn func(T) bool) *Stream[T]
func Take[T any](s *Stream[T], n int) *Stream[T]
func Chunk[T any](s *Stream[T], size int) *Stream[[]T]
func Reduce[T, A any](s *Stream[T], initial A, fn func(A, T) A) (A, error)
func ForEach[T any](s *Stream[T], fn func(T) error) error

stream.ChangeStream[T]

func NewChangeStream[T any](source ChangeSource[T]) *ChangeStream[T]

func (cs *ChangeStream[T]) Next(ctx context.Context) bool
func (cs *ChangeStream[T]) Event() ChangeEvent[T]
func (cs *ChangeStream[T]) Err() error
func (cs *ChangeStream[T]) Close() error
func (cs *ChangeStream[T]) ResumeToken() any
func (cs *ChangeStream[T]) All(yield func(ChangeEvent[T], error) bool)

stream.ChangeEvent[T]

type ChangeEvent[T any] struct {
    Operation   ChangeOp
    Before      *T          // previous state (nil for inserts)
    After       *T          // new state (nil for deletes)
    Timestamp   time.Time
    ResumeToken any
}

pgdriver Types

pgdriver.Unwrap

// Unwrap extracts the underlying *PgDB from a *grove.DB handle.
// Panics if the driver is not a *PgDB.
func Unwrap(db *grove.DB) *PgDB

Usage:

pgdb := pgdriver.Unwrap(db)
pgdb.NewSelect(&User{}).Where("active = $1", true).Scan(ctx, &users)

pgdriver.PgDB streaming methods

// Stream opens a server-side cursor with default fetch size (100 rows/batch).
func (q *SelectQuery) Stream(ctx context.Context) (*stream.Stream[any], error)

// StreamBatch opens a server-side cursor with custom fetch size.
func (q *SelectQuery) StreamBatch(ctx context.Context, fetchSize int) (*stream.Stream[any], error)

pgdriver.Listener

func (db *PgDB) NewListener() *Listener
func (db *PgDB) Listen(ctx context.Context, channel string, handler func(*Notification)) (*Listener, error)

func (l *Listener) Start(ctx context.Context) error
func (l *Listener) Listen(ctx context.Context, channel string) error
func (l *Listener) Unlisten(ctx context.Context, channel string) error
func (l *Listener) OnNotification(channel string, handler func(*Notification))
func (l *Listener) Notify(ctx context.Context, channel, payload string) error
func (l *Listener) Close() error

Sentinel Errors

var (
    ErrNoRows             = errors.New("grove: no rows in result set")
    ErrModelNotRegistered = errors.New("grove: model not registered")
    ErrNotSupported       = errors.New("grove: operation not supported by driver")
    ErrHookDenied         = errors.New("grove: hook denied the operation")
    ErrMigrationFailed    = errors.New("grove: migration failed")
    ErrMigrationLocked    = errors.New("grove: migration lock held by another process")
    ErrCyclicDependency   = errors.New("grove: cyclic dependency in migration groups")
)

Go Packages

On this page