database

package
v1.0.0-rc.2 Latest Latest
Warning

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

Go to latest
Published: Oct 2, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source
const KindStruct = reflect.Struct

Variables

This section is empty.

Functions

func Drivers

func Drivers() []string

Drivers returns the sorted list of registered driver names.

func Expired

func Expired(deadline time.Time) bool

Expired reports whether a deadline has passed. The zero time never expires.

func ExpiryFor

func ExpiryFor(ttl time.Duration) time.Time

ExpiryFor converts a ttl into an absolute deadline; zero means no deadline.

func FormatDeadline

func FormatDeadline(deadline time.Time) string

FormatDeadline renders a deadline for a string-typed store.

func NewStruct

func NewStruct(typ reflect.Type) reflect.Value

func ParseDeadline

func ParseDeadline(s string) time.Time

ParseDeadline is the inverse of FormatDeadline. An empty or unparsable value means no deadline, so a corrupt companion entry cannot hide the data.

func Register

func Register(name string, dbType DbType)

Register associates a driver name with a DbType. It is intended to be called from a backend package's init function. Registering the same name twice is a no-op; registering a name that maps to a different DbType panics, since that indicates a programming error rather than a runtime condition.

func ScanRows

func ScanRows[T any](rows *sql.Rows, schema *CachedSchema) ([]T, error)

ScanRows reads every row into a T. T may be the struct type or a pointer to it. Columns absent from the schema are discarded.

func TypeOf

func TypeOf(v any) reflect.Type

func TypeOfT

func TypeOfT[T any]() reflect.Type

TypeOfT returns the struct type of T, dereferencing pointer types. It is the type-safe counterpart of TypeOf for generic code paths.

func UnwrapValueOf

func UnwrapValueOf(v any) reflect.Value

Types

type CachedSchema

type CachedSchema struct {
	Type       reflect.Type
	Fields     []FieldInfo
	Insertable []FieldInfo
	PKIndex    int
	FieldMap   map[string]FieldInfo

	InsertColsMysql  string
	InsertPlaceMysql string
	InsertColsPG     string
	InsertPlacePG    string
}

func GetOrBuildSchema

func GetOrBuildSchema(typ reflect.Type) *CachedSchema

func SchemaOfT

func SchemaOfT[T any]() *CachedSchema

SchemaOfT returns the cached schema for T, building it on first use.

func (*CachedSchema) BuildAssignments

func (s *CachedSchema) BuildAssignments(v reflect.Value, fields []string, quote func(string) string, paramStyle string, startIdx int) ([]string, []any, error)

BuildAssignments renders the SET clause assigning the named fields from v.

paramStyle "pg" numbers placeholders from startIdx, because a PostgreSQL UPDATE binds the SET arguments before the WHERE ones. Other styles use a bare "?" and ignore startIdx.

func (*CachedSchema) BuildInsertQueryMysql

func (s *CachedSchema) BuildInsertQueryMysql(tableName string) string

func (*CachedSchema) BuildInsertQueryPG

func (s *CachedSchema) BuildInsertQueryPG(tableName string) string

func (*CachedSchema) BuildWhereClause

func (s *CachedSchema) BuildWhereClause(val reflect.Value, whereFields []string, paramStyle string) (string, []any, error)

func (*CachedSchema) ExtractValues

func (s *CachedSchema) ExtractValues(val reflect.Value) []any

type Config

type Config struct {
	Type       string
	NullAble   bool
	Identity   bool
	PrimaryKey bool
	Unique     bool
}

type Database

type Database[T any] interface {
	Create(string, map[string]Config) error
	GetTable(string, T) (Table[T], error)
	DeleteTable(string) error

	// Close releases resources such as connection pools. Backends holding
	// none return nil. Safe to call more than once.
	Close() error
}

type DbType

type DbType int
const (
	MySQL DbType = iota
	PostgreSQL
	SQLite
	Redis
	Memory
	Bloom
	Mixture
)

func Lookup

func Lookup(name string) (DbType, bool)

Lookup resolves a driver name to its DbType.

type FieldInfo

type FieldInfo struct {
	Index       int
	ColumnName  string
	IsAutoInc   bool
	IsNullable  bool
	IsPrimary   bool
	IsUnique    bool
	GoFieldName string
	GoKind      reflect.Kind
}

type FieldNotFoundError

type FieldNotFoundError struct {
	Name string
}

func (*FieldNotFoundError) Error

func (e *FieldNotFoundError) Error() string

type Options

type Options struct {
	// Order sorts the result, applied in the order given.
	Order []Order
	// Limit caps the row count; zero or less means no cap.
	Limit int
	// Offset skips rows.
	Offset int
}

Options narrows and orders a read. The zero value means "everything".

func (Options) LimitClause

func (o Options) LimitClause() string

LimitClause renders the LIMIT/OFFSET pair, which every SQL dialect here spells the same way.

func (Options) OrderBy

func (o Options) OrderBy(schema *CachedSchema, quote func(string) string) (string, bool)

OrderBy renders the ORDER BY clause and reports whether there is one.

func (Options) Validate

func (o Options) Validate(schema *CachedSchema) error

Validate rejects names that are not real columns. Sort keys and limits cannot be bound as parameters, so this is what keeps a caller-supplied name out of the query as raw SQL.

type Order

type Order struct {
	Column string
	Desc   bool
}

Order is one sort key.

func Asc

func Asc(column string) Order

func Ascending

func Ascending(column string) []Order

Ascending and Descending are ready-made single-key order slices.

func Desc

func Desc(column string) Order

func Descending

func Descending(column string) []Order

type ScanTypeError

type ScanTypeError struct {
	Got reflect.Type
}

ScanTypeError reports rows that could not be materialised into T.

func (*ScanTypeError) Error

func (e *ScanTypeError) Error() string

type Table

type Table[T any] interface {
	// Ins inserts one row.
	Ins(val T, ttl time.Duration) error

	// Get reads the rows matching whereFields, whose values are taken from
	// val. An empty whereFields matches every row. opts narrows and orders the
	// result.
	Get(val T, whereFields []string, opts Options, ttl time.Duration) ([]T, error)

	// Set updates rows where the columns named in whereFields equal their
	// values in old, assigning the columns named in setFields the values in
	// updated. Passing the same model for both is the common case.
	Set(old, updated T, whereFields, setFields []string, ttl time.Duration) error

	// Del removes the rows matching whereFields, whose values are taken from
	// val.
	Del(val T, whereFields []string, ttl time.Duration) error
}

Table is the CRUD surface of one table.

Read and write options are kept separate on purpose: whereFields name the columns whose values come from the passed model, while setFields name the columns to assign. That split is what lets Set distinguish "match on the old value" from "write the new one" without the caller having to remember which fields to exclude.

The ttl argument of Ins and Set sets a deadline; see ExpiryFor for the semantics. It is ignored on reads and on Del.

Directories

Path Synopsis
Package factory constructs a database backend by name or by type.
Package factory constructs a database backend by name or by type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL