database

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetAllTyped added in v1.7.0 

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 added in v1.7.0 

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 added in v1.7.0 

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 added in v1.6.0 

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 added in v1.6.0 

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 added in v1.2.30 

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 added in v1.5.0 

type Option func(*connectionConfig)

Option is a function that configures the database connection

func WithCacheKey added in v1.5.0 

func WithCacheKey(field entities.Field) Option

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

func WithCaching added in v1.5.0 

func WithCaching(enabled bool) Option

WithCaching enables or disables caching for the database connection

func WithEncryption added in v1.5.0 

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 added in v1.5.0 

func WithNameSpace(name string) Option

WithNameSpace sets the namespace (database name) for the connection

func WithPoolSize added in v1.5.0 

func WithPoolSize(size int) Option

WithPoolSize sets the maximum connection pool size

func WithTimeout added in v1.5.0 

func WithTimeout(seconds int) Option

WithTimeout sets the connection timeout in seconds

func WithVerbose added in v1.5.0 

func WithVerbose(enabled bool) Option

WithVerbose enables or disables verbose logging for the database connection

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.