database

README

dao/database generics helpers

This folder contains the Storm-backed database layer used across the project.

The file database_generics.go adds typed (generic) helper functions that reduce DAO boilerplate by avoiding any/[]any results and repeated type assertions.

Why these are functions (not methods)

These helpers are package-level functions because Go does not allow type parameters on methods of a non-generic type (e.g. func (db *DB) Get[T any](...)).

So usage is:

• database.GetTyped[T](db, field, value)
• database.GetAllTyped[T](db, ...)
• database.GetAllWhereTyped[T](db, field, value)

Requirements / constraints

• db must be a valid *database.DB (typically returned from database.Connect(...)).
• T must be a non-pointer struct type (e.g. MyRecord, not *MyRecord).
  • Storm expects a pointer destination internally, but the type parameter should be the struct.
• field is a fields.Field and must exist on T for the *Where* helpers.

Functions

GetTyped[T any](db *DB, field fields.Field, value any) (T, error)

Fetches a single record where field == value.

• Returns error when not found (Storm’s ErrNotFound or wrapped upstream).

Example:

import (
    "github.com/mt1976/frantic-core/dao/database"
    "github.com/mt1976/frantic-core/dao/fields"
)

type User struct {
    ID   int    `storm:"id,increment"`
    Key  string `storm:"unique"`
    Name string
}

var UserFields = struct {
    ID  fields.Field
    Key fields.Field
}{
    ID:  "ID",
    Key: "Key",
}

func loadUser(db *database.DB, key string) (User, error) {
    return database.GetTyped[User](db, UserFields.Key, key)
}

GetAllTyped[T any](db *DB, options ...func(*index.Options)) ([]T, error)

Fetches all records of type T.

• The optional options are passed through to Storm’s All (ordering, limits, etc.).

Example:

import (
    "github.com/asdine/storm/v3/index"
    "github.com/mt1976/frantic-core/dao/database"
)

func loadAllUsers(db *database.DB) ([]User, error) {
    // No options
    return database.GetAllTyped[User](db)

    // With options (example only — depends on Storm’s index.Options)
    // return database.GetAllTyped[User](db, func(o *index.Options) {
    //     o.Skip = 0
    //     o.Limit = 100
    // })
}

GetAllWhereTyped[T any](db *DB, field fields.Field, value any) ([]T, error)

Fetches all records of type T where field == value.

• Validates that the field exists on T and that value has a suitable type.
• If Storm returns ErrNotFound, this helper returns an empty slice ([]T{}) and nil error.

Example:

import (
    "github.com/mt1976/frantic-core/dao/database"
)

type Order struct {
    ID     int    `storm:"id,increment"`
    Status string `storm:"index"`
}

var OrderFields = struct {
    Status fields.Field
}{
    Status: "Status",
}

func loadOpenOrders(db *database.DB) ([]Order, error) {
    return database.GetAllWhereTyped[Order](db, OrderFields.Status, "OPEN")
}

Common pitfalls

• Using *T instead of T:
  • database.GetTyped[*User](...) is invalid by design and will return an invalid-type error.
• Wrong field name:
  • GetAllWhereTyped checks the field exists on the struct and errors early.
• Wrong value type:
  • If field is an int field but you pass a string, it will error.

Where this is used

A concrete example DAO that uses these helpers is the TemplateStoreV2 implementation:

• GetBy uses database.GetTyped[TemplateStore](...)
• GetAll uses database.GetAllTyped[TemplateStore](...)
• GetAllWhere uses database.GetAllWhereTyped[TemplateStore](...)

See:

• dao/test/templateStoreV2/templateStoreV2.go

Documentation

Overview

Package database provides low-level database connectivity and helpers used by the DAO layer.

Index

• func GetAllTyped[T any](db *DB, options ...func(*index.Options)) ([]T, error)
• func GetAllWhereTyped[T any](db *DB, field entities.Field, value any) ([]T, error)
• func GetTyped[T any](db *DB, field entities.Field, value any) (T, error)
• type DB
  • func Connect(table any, options ...Option) *DB
  • func ConnectToNamedDB(name string, options ...Option) *DB
  • func (db *DB) Backup(loc string)
  • func (db *DB) Count(data any) (int, error)
  • func (db *DB) CountWhere(field entities.Field, value any, to any) (int, error)
  • func (db *DB) Create(data any) error
  • func (db *DB) Delete(data any) error
  • func (db *DB) Disconnect()
  • func (db *DB) Drop(data any) error
  • func (db *DB) Get(field entities.Field, value, to any) (any, error)
  • func (db *DB) GetAll(to any, options ...func(*index.Options)) ([]any, error)
  • func (db *DB) GetAllWhere(field entities.Field, value, to any) ([]any, error)
  • func (db *DB) Reconnect()
  • func (db *DB) Retrieve(field entities.Field, value, to any) (any, error)
  • func (db *DB) Update(data any) error
• type Option
  • func WithCacheKey(field entities.Field) Option
  • func WithCaching(enabled bool) Option
  • func WithEncryption(enabled bool) Option
  • func WithNameSpace(name string) Option
  • func WithPoolSize(size int) Option
  • func WithTimeout(seconds int) Option
  • func WithVerbose(enabled bool) Option

Functions

func GetAllTyped

func GetAllTyped[T any](db *DB, options ...func(*index.Options)) ([]T, error)

GetAllTyped retrieves all records for type T and returns a typed slice.

NOTE: T is expected to be a struct type (not a pointer).

func GetAllWhereTyped

func GetAllWhereTyped[T any](db *DB, field entities.Field, value any) ([]T, error)

GetAllWhereTyped retrieves all matching records for type T filtered by field/value.

NOTE: T is expected to be a struct type (not a pointer).

func GetTyped

func GetTyped[T any](db *DB, field entities.Field, value any) (T, error)

GetTyped retrieves a single record from the database and returns it as a concrete type.

NOTE: Go does not currently allow methods with type parameters, so these helpers are package-level functions.

T is expected to be a struct type (not a pointer). Storm expects a pointer to a struct destination; if you call this with a pointer type, it will return an invalid-type error.

Types

type DB

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

DB represents a database connection and its configuration

func Connect

func Connect(table any, options ...Option) *DB

Connect establishes a database connection with the provided options It is the primary function to initiate a connection using various configuration options.

func ConnectToNamedDB

func ConnectToNamedDB(name string, options ...Option) *DB

ConnectToNamedDB establishes a database connection to a named database DEPRECATED: ConnectToNamedDB - Use Connect with WithNameSpace option instead

func (*DB) Backup

func (db *DB) Backup(loc string)

Backup creates a backup of the database to the specified location It disconnects the database, performs the backup, and then reconnects. The backup process is timed and logged.

func (*DB) Count

func (db *DB) Count(data any) (int, error)

Count returns the total number of records of the specified type in the database.

Parameters:

• data: A pointer to the struct representing the type whose records are to be counted.

Returns:

• int: The total number of records.
• error: An error object if any issues occur during the counting process; otherwise, nil.

func (*DB) CountWhere

func (db *DB) CountWhere(field entities.Field, value any, to any) (int, error)

CountWhere returns the number of records that match the specified fields.Field and value.

Parameters:

• fields.FieldName: The fields.Field to be used for filtering records.
• value: The value of the specified fields.Field to filter records.
• to: A pointer to the struct representing the type whose records are to be counted.

Returns:

• int: The number of records that match the specified criteria.
• error: An error object if any issues occur during the counting process; otherwise, nil.

func (*DB) Create

func (db *DB) Create(data any) error

Create adds a new record to the database.

Parameters:

• data: A pointer to the struct representing the record to be created.

Returns:

• error: An error object if any issues occur during the creation process; otherwise, nil.

func (*DB) Delete

func (db *DB) Delete(data any) error

Delete removes the specified record from the database.

Parameters:

• data: A pointer to the struct representing the record to be deleted.

Returns:

• error: An error object if any issues occur during the deletion process; otherwise, nil.

func (*DB) Disconnect

func (db *DB) Disconnect()

Disconnect closes the database connection and removes it from the connection pool It uses a timing mechanism to log the duration of the disconnection process. If disconnection fails, it logs the error and panics with a wrapped disconnect error.

func (*DB) Drop

func (db *DB) Drop(data any) error

Drop removes the entire bucket or collection associated with the specified struct from the database.

Parameters:

• data: A pointer to the struct representing the type whose bucket or collection is to be dropped.

Returns:

• error: An error object if any issues occur during the drop process; otherwise, nil.

func (*DB) Get

func (db *DB) Get(field entities.Field, value, to any) (any, error)

Get retrieves a single record from the database based on the specified fields.Field and value.

Parameters:

• fields.Field: The fields.Field to be used for filtering the record.
• value: The value of the specified fields.Field to filter the record.
• to: A pointer to the struct where the retrieved record will be stored.

Returns:

• any: The retrieved record.
• error: An error object if any issues occur during the retrieval process; otherwise, nil.

func (*DB) GetAll

func (db *DB) GetAll(to any, options ...func(*index.Options)) ([]any, error)

GetAll retrieves all records of the specified type from the database.

Parameters:

• to: A pointer to a slice where the retrieved records will be stored.

Returns:

• []any: A slice of all retrieved records.
• error: An error object if any issues occur during the retrieval process; otherwise, nil.

func (*DB) GetAllWhere

func (db *DB) GetAllWhere(field entities.Field, value, to any) ([]any, error)

GetAllWhere retrieves all TemplateStore records that match the specified fields.Field and value.

Parameters:

• fields.Field: The fields.Field to be used for filtering records.
• value: The value of the specified fields.Field to filter records.

Returns:

• []TemplateStore: A slice of TemplateStore records that match the specified criteria.
• error: An error object if any issues occur during the retrieval process; otherwise, nil.

func (*DB) Reconnect

func (db *DB) Reconnect()

func (*DB) Retrieve

func (db *DB) Retrieve(field entities.Field, value, to any) (any, error)

Retrieve retrieves a single record from the database based on the specified fields.Field and value.

Parameters:

• fields.Field: The fields.Field to be used for filtering the record.
• value: The value of the specified fields.Field to filter the record.
• to: A pointer to the struct where the retrieved record will be stored.

Returns:

• any: The retrieved record.
• error: An error object if any issues occur during the retrieval process; otherwise, nil.

DEPRECATED: Use Get instead.

func (*DB) Update

func (db *DB) Update(data any) error

Update modifies an existing record in the database.

Parameters:

• data: A pointer to the struct representing the record to be updated.

Returns:

• error: An error object if any issues occur during the update process; otherwise, nil.

type Option

type Option func(*connectionConfig)

Option is a function that configures the database connection

func WithCacheKey

func WithCacheKey(field entities.Field) Option

WithCacheKey sets the cache key fields.Fields.Field for the database connection

func WithCaching

func WithCaching(enabled bool) Option

WithCaching enables or disables caching for the database connection

func WithEncryption

func WithEncryption(enabled bool) Option

WithEncryption enables or disables encryption for the database connection By default, encryption is disabled. Reserved for Future use.

func WithNameSpace

func WithNameSpace(name string) Option

WithNameSpace sets the namespace (database name) for the connection

func WithPoolSize

func WithPoolSize(size int) Option

WithPoolSize sets the maximum connection pool size

func WithTimeout

func WithTimeout(seconds int) Option

WithTimeout sets the connection timeout in seconds

func WithVerbose

func WithVerbose(enabled bool) Option

WithVerbose enables or disables verbose logging for the database connection