data

package module
v0.28.0 Latest Latest
Warning

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

Go to latest
Published: May 20, 2026 License: MIT Imports: 20 Imported by: 5

README

data

data 是 infrago 的模块

包定位

  • 类型:模块
  • 作用:统一数据访问模块,负责 SQL/Mongo 风格查询抽象。

主要功能

  • 对上提供统一模块接口
  • 对下通过驱动接口接入具体后端
  • 支持按配置切换驱动实现
  • 支持数据库内自增序列 Sequence

序列编号

DataBase 现在支持:

db := data.Base("main")
defer db.Close()

id, err := db.Sequence("order.no", 1000, 1)
ids, err := db.SequenceMany("order.no", 3, 1000, 1)

语义:

  • 第一次调用某个 key:返回 offset
  • 之后每次:返回 current + step
  • offset 只在序列首次创建时生效
  • step == 0 时按 1 处理
  • SequenceMany 一次原子领取一段编号,例如 [1000, 1001, 1002]

实现方式:

  • SQL 驱动使用内部表 _infrago_sequences
  • MongoDB 驱动使用内部集合 _infrago_sequences

快速接入

import _ "github.com/infrago/data"
[data]
driver = "default"

驱动实现接口列表

以下接口由驱动实现(来自模块 driver.go):

Driver
  • Connect(*Instance) (Connection, error)
Connection
  • Open() error
  • Close() error
  • Health() Health
  • DB() *sql.DB
  • Dialect() Dialect
Dialect
  • Name() string
  • Quote(string) string
  • Placeholder(int) string
  • SupportsILike() bool
  • SupportsReturning() bool

全局配置项(所有配置键)

配置段:[data]

  • 未检测到配置键(请查看模块源码的 configure 逻辑)

说明

  • setting 一般用于向具体驱动透传专用参数
  • 多实例配置请参考模块源码中的 Config/configure 处理逻辑

Documentation

Index

Constants

View Source
const (
	MutationInsert = "insert"
	MutationUpdate = "update"
	MutationDelete = "delete"
	MutationUpsert = "upsert"

	// Short op aliases (kept for concise usage).
	INSERT = MutationInsert
	UPDATE = MutationUpdate
	DEL    = MutationDelete
	UPSERT = MutationUpsert
)
View Source
const NAME = "DATA"

Variables

View Source
var (
	ErrNotFound        = errors.New("data: not found")
	ErrConflict        = errors.New("data: conflict")
	ErrDuplicate       = errors.New("data: duplicate")
	ErrForeignKey      = errors.New("data: foreign key")
	ErrUnsupported     = errors.New("data: unsupported")
	ErrInvalidQuery    = errors.New("data: invalid query")
	ErrInvalidUpdate   = errors.New("data: invalid update")
	ErrInvalidSequence = errors.New("data: invalid sequence")
	ErrTxFailed        = errors.New("data: tx failed")
	ErrValidation      = errors.New("data: validation")
	ErrDriver          = errors.New("data: driver")
	ErrTimeout         = errors.New("data: timeout")
	ErrCanceled        = errors.New("data: canceled")
)

Functions

func BindBinaryValue added in v0.26.0

func BindBinaryValue(value Any) (Any, bool)

func BindJSONValue added in v0.26.0

func BindJSONValue(value Any) (Any, bool)

func BindTextValue added in v0.26.0

func BindTextValue(value Any) (Any, bool)

func BindTimeValue added in v0.26.0

func BindTimeValue(value Any) (Any, bool)

func BuildGroupBy added in v0.7.0

func BuildGroupBy(fields []string, dialect Dialect) string

func BuildLimitOffset added in v0.7.0

func BuildLimitOffset(q Query, startIndex int, dialect Dialect, args *[]Any) string

func BuildOrderBy added in v0.7.0

func BuildOrderBy(q Query, dialect Dialect) string

func CacheToken added in v0.7.0

func CacheToken(name string, tables []string) string

func CamelFieldPath added in v0.7.0

func CamelFieldPath(field string) string

func DecodeBinaryValue added in v0.26.0

func DecodeBinaryValue(value Any) (Any, bool)

func DecodeJSONValue added in v0.26.0

func DecodeJSONValue(value Any) (Any, bool)

func DecodePGArrayValue added in v0.26.0

func DecodePGArrayValue(cfg Var, value Any) (Any, bool)

func DecodeTextValue added in v0.26.0

func DecodeTextValue(value Any) (Any, bool)

func DecodeTimeValue added in v0.26.0

func DecodeTimeValue(value Any) (Any, bool)

func EmitMutation added in v0.7.0

func EmitMutation(base, table, op string, rows int64, key Any, keys []Any, data Map, where Map)

func Error added in v0.7.0

func Error(op string, code error, err error) error

func ErrorKind added in v0.7.0

func ErrorKind(err error) string

func Field

func Field(name string, field string, extends ...Any) Var

func Fields

func Fields(name string, keys []string, extends ...Vars) Vars

func GenerateTableKeys added in v0.7.0

func GenerateTableKeys(tableName string, table Table) string

GenerateTableKeys emits a compact Go constant block for table field names. It helps projects avoid manual string literals in query/update code.

func IsArrayVar added in v0.26.0

func IsArrayVar(cfg Var) bool

func IsBinaryVar added in v0.26.0

func IsBinaryVar(cfg Var) bool

func IsDecimalVar added in v0.26.0

func IsDecimalVar(cfg Var) bool

func IsJSONVar added in v0.26.0

func IsJSONVar(cfg Var) bool

func IsTimeVar added in v0.26.0

func IsTimeVar(cfg Var) bool

func IsUUIDVar added in v0.26.0

func IsUUIDVar(cfg Var) bool

func Migrate added in v0.7.0

func Migrate(names ...string) error

func MigrateDown added in v0.7.0

func MigrateDown(steps int) error

func MigrateDownOn added in v0.7.0

func MigrateDownOn(base string, steps int) error

func MigrateOn added in v0.7.0

func MigrateOn(base string, names ...string) error

func MigrateUp added in v0.7.0

func MigrateUp(versions ...string) error

func MigrateUpOn added in v0.7.0

func MigrateUpOn(base string, versions ...string) error

func Models

func Models() map[string]Model

func Option

func Option(name string, field string, key string) Any

func Options

func Options(name string, field string) Map

func QuerySignature added in v0.7.0

func QuerySignature(q Query) string

func Sequence added in v0.21.0

func Sequence(key string, offset, step int64, names ...string) (int64, error)

func SequenceMany added in v0.21.0

func SequenceMany(key string, count, offset, step int64, names ...string) ([]int64, error)

func SnakeFieldPath added in v0.7.0

func SnakeFieldPath(field string) string

func Tables

func Tables() map[string]Table

func TouchTableCache added in v0.7.0

func TouchTableCache(name, table string) uint64

func Views

func Views() map[string]View

Types

type Agg added in v0.7.0

type Agg struct {
	Alias string
	Op    string
	Field string
}

type AndExpr added in v0.7.0

type AndExpr struct{ Items []Expr }

type ArrayBinder added in v0.26.0

type ArrayBinder interface {
	BindArray(any) any
}

type Capabilities added in v0.7.0

type Capabilities struct {
	Dialect       string `json:"dialect"`
	ILike         bool   `json:"ilike"`
	Returning     bool   `json:"returning"`
	Join          bool   `json:"join"`
	Group         bool   `json:"group"`
	Having        bool   `json:"having"`
	Aggregate     bool   `json:"aggregate"`
	KeysetAfter   bool   `json:"keyset_after"`
	JsonContains  bool   `json:"json_contains"`
	ArrayOverlap  bool   `json:"array_overlap"`
	JsonElemMatch bool   `json:"json_elem_match"`
}

func GetCapabilities added in v0.7.0

func GetCapabilities(names ...string) (Capabilities, error)

type Cascade added in v0.12.0

type Cascade struct {
	Table      string
	ForeignKey string
}

type CmpExpr added in v0.7.0

type CmpExpr struct {
	Field string
	Op    string
	Value Any
}

type Config

type Config struct {
	Driver      string
	Url         string
	Schema      string
	Mapping     bool
	MaxOpen     int
	MaxIdle     int
	MaxLifetime time.Duration
	MaxIdleTime time.Duration
	ReadOnly    bool
	Trash       TrashOptions
	Watcher     Map
	Migrate     MigrateOptions
	Setting     Map
}

type Configs

type Configs map[string]Config

type Connection added in v0.7.0

type Connection interface {
	Open() error
	Close() error
	Health() Health
	DB() *sql.DB
	Dialect() Dialect
}

type DataBase

type DataBase interface {
	Close() error
	WithContext(context.Context) DataBase
	WithTimeout(time.Duration) DataBase
	Begin() error
	Commit() error
	Rollback() error
	Tx(TxFunc) Res
	TxReadOnly(TxFunc) Res
	Migrate(...string)
	MigratePlan(...string) MigrateReport
	MigrateDiff(...string) MigrateReport
	MigrateUp(...string)
	MigrateDown(int)
	MigrateTo(string)
	MigrateDownTo(string)
	Capabilities() Capabilities
	Error() error
	ClearError()
	Sequence(string, int64, int64) (int64, error)
	SequenceMany(string, int64, int64, int64) ([]int64, error)

	Table(string) DataTable
	View(string) DataView
	Model(string) DataModel

	Raw(string, ...Any) []Map
	Exec(string, ...Any) int64
	Parse(...Any) (string, []Any)
}

func Base

func Base(names ...string) DataBase

type DataError added in v0.7.0

type DataError struct {
	Op   string
	Code error
	Err  error
	Kind string
}

func (*DataError) Error added in v0.7.0

func (e *DataError) Error() string

func (*DataError) Is added in v0.7.0

func (e *DataError) Is(target error) bool

func (*DataError) Unwrap added in v0.7.0

func (e *DataError) Unwrap() error

type DataModel

type DataModel interface {
	First(...Any) Map
	Query(...Any) []Map
	Scan(ScanFunc, ...Any) Res
	ScanN(int64, ScanFunc, ...Any) Res
	Slice(offset, limit int64, args ...Any) (int64, []Map)
}

type DataTable

type DataTable interface {
	Insert(Map) Map
	InsertMany([]Map) []Map
	Upsert(Map, ...Any) Map
	UpsertMany([]Map, ...Any) []Map
	Update(Map, ...Any) Map
	UpdateMany(Map, ...Any) int64
	Remove(...Any) Map
	RemoveMany(...Any) int64
	Restore(...Any) Map
	RestoreMany(...Any) int64
	Delete(...Any) Map
	DeleteMany(...Any) int64

	Entity(Any) Map
	Count(...Any) int64
	Aggregate(...Any) []Map
	First(...Any) Map
	Query(...Any) []Map
	Scan(ScanFunc, ...Any) Res
	ScanN(int64, ScanFunc, ...Any) Res
	Slice(offset, limit int64, args ...Any) (int64, []Map)
	Group(field string, args ...Any) []Map
}

type DataView

type DataView interface {
	Count(...Any) int64
	Aggregate(...Any) []Map
	First(...Any) Map
	Query(...Any) []Map
	Scan(ScanFunc, ...Any) Res
	ScanN(int64, ScanFunc, ...Any) Res
	Slice(offset, limit int64, args ...Any) (int64, []Map)
	Group(field string, args ...Any) []Map
}

type DeleteWatcher added in v0.7.0

type DeleteWatcher struct {
	Name   string
	Desc   string
	Action func(Mutation)
}

type Dialect added in v0.7.0

type Dialect interface {
	Name() string
	Quote(string) string
	Placeholder(int) string
	SupportsILike() bool
	SupportsReturning() bool
}

type Driver

type Driver interface {
	Connect(*Instance) (Connection, error)
}

type ErrorClassifier added in v0.26.0

type ErrorClassifier interface {
	ClassifyError(error) error
}

type ExistsExpr added in v0.7.0

type ExistsExpr struct {
	Field string
	Yes   bool
}

type Expr added in v0.7.0

type Expr interface {
	// contains filtered or unexported methods
}

type FieldRef added in v0.7.0

type FieldRef string

func Ref added in v0.7.0

func Ref(field string) FieldRef

type Health

type Health struct {
	Workload int64
}

type Index added in v0.7.0

type Index struct {
	Name   string
	Fields []string
	Unique bool
}

type InsertWatcher added in v0.7.0

type InsertWatcher struct {
	Name   string
	Desc   string
	Action func(Mutation)
}

type Instance

type Instance struct {
	Name    string
	Config  Config
	Setting Map
	// contains filtered or unexported fields
}

type Join added in v0.7.0

type Join struct {
	From         string
	Alias        string
	Type         string
	LocalField   string
	ForeignField string
	On           Expr
}

type MigrateAction added in v0.7.0

type MigrateAction struct {
	Kind   string         `json:"kind"`
	Target string         `json:"target"`
	SQL    string         `json:"sql,omitempty"`
	Apply  bool           `json:"apply"`
	Risk   string         `json:"risk,omitempty"`
	Detail string         `json:"detail,omitempty"`
	Diffs  []MigrateDelta `json:"diffs,omitempty"`
}

type MigrateDelta added in v0.26.0

type MigrateDelta struct {
	Field  string `json:"field"`
	Kind   string `json:"kind"`
	From   string `json:"from,omitempty"`
	To     string `json:"to,omitempty"`
	Apply  bool   `json:"apply"`
	Risk   string `json:"risk,omitempty"`
	Detail string `json:"detail,omitempty"`
}

type MigrateOptions added in v0.7.0

type MigrateOptions struct {
	Startup     string
	Mode        string
	DryRun      bool
	DiffOnly    bool
	Concurrent  bool
	Timeout     time.Duration
	LockTimeout time.Duration
	Retry       int
	RetryDelay  time.Duration
	Jitter      time.Duration
}

type MigrateReport added in v0.7.0

type MigrateReport struct {
	Mode    string          `json:"mode"`
	DryRun  bool            `json:"dryRun"`
	Actions []MigrateAction `json:"actions"`
}

func MigrateDiff added in v0.7.0

func MigrateDiff(names ...string) (MigrateReport, error)

func MigrateDiffOn added in v0.7.0

func MigrateDiffOn(base string, names ...string) (MigrateReport, error)

func MigratePlan added in v0.7.0

func MigratePlan(names ...string) (MigrateReport, error)

func MigratePlanOn added in v0.7.0

func MigratePlanOn(base string, names ...string) (MigrateReport, error)

type Migration added in v0.7.0

type Migration struct {
	Version string
	Name    string
	Desc    string
	Up      func(DataBase) error
	Down    func(DataBase) error
}

func Migrations added in v0.7.0

func Migrations(names ...string) []Migration

func (Migration) Checksum added in v0.7.0

func (m Migration) Checksum() string

type Model

type Model struct {
	Name    string
	Desc    string
	Schema  string
	Model   string
	Key     string
	Fields  Vars
	Setting Map
}

func GetModel

func GetModel(name string) *Model

type Module

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

func (*Module) Base

func (m *Module) Base(names ...string) DataBase

func (*Module) Close added in v0.7.0

func (m *Module) Close()

func (*Module) Config

func (m *Module) Config(global Map)

func (*Module) Field

func (m *Module) Field(name, field string, extends ...Any) Var

func (*Module) Fields

func (m *Module) Fields(name string, keys []string, extends ...Vars) Vars

func (*Module) GetCapabilities added in v0.7.0

func (m *Module) GetCapabilities(names ...string) (Capabilities, error)

func (*Module) ModelConfig

func (m *Module) ModelConfig(name string) *Model

func (*Module) Models

func (m *Module) Models() map[string]Model

func (*Module) Open added in v0.7.0

func (m *Module) Open()

func (*Module) Option

func (m *Module) Option(name, field, key string) Any

func (*Module) Options

func (m *Module) Options(name, field string) Map

func (*Module) PoolStats added in v0.7.0

func (m *Module) PoolStats(names ...string) []PoolStats

func (*Module) Register

func (m *Module) Register(name string, value Any)

func (*Module) RegisterConfig added in v0.7.0

func (m *Module) RegisterConfig(name string, cfg Config)

func (*Module) RegisterConfigs added in v0.7.0

func (m *Module) RegisterConfigs(configs Configs)

func (*Module) RegisterDeleteWatcher added in v0.7.0

func (m *Module) RegisterDeleteWatcher(name string, watcher DeleteWatcher)

func (*Module) RegisterDriver added in v0.7.0

func (m *Module) RegisterDriver(name string, driver Driver)

func (*Module) RegisterInsertWatcher added in v0.7.0

func (m *Module) RegisterInsertWatcher(name string, watcher InsertWatcher)

func (*Module) RegisterMigration added in v0.7.0

func (m *Module) RegisterMigration(name string, migration Migration)

func (*Module) RegisterModel added in v0.7.0

func (m *Module) RegisterModel(name string, model Model)

func (*Module) RegisterTable added in v0.7.0

func (m *Module) RegisterTable(name string, table Table)

func (*Module) RegisterUpdateWatcher added in v0.7.0

func (m *Module) RegisterUpdateWatcher(name string, watcher UpdateWatcher)

func (*Module) RegisterUpsertWatcher added in v0.7.0

func (m *Module) RegisterUpsertWatcher(name string, watcher UpsertWatcher)

func (*Module) RegisterView added in v0.7.0

func (m *Module) RegisterView(name string, view View)

func (*Module) RegisterWatcher added in v0.7.0

func (m *Module) RegisterWatcher(name string, watcher Watcher)

func (*Module) RegisterWatchers added in v0.7.0

func (m *Module) RegisterWatchers(items Watchers)

func (*Module) Setup added in v0.7.0

func (m *Module) Setup()

func (*Module) Start added in v0.7.0

func (m *Module) Start()

func (*Module) Stats added in v0.7.0

func (m *Module) Stats(names ...string) Stats

func (*Module) Stop added in v0.7.0

func (m *Module) Stop()

func (*Module) TableConfig

func (m *Module) TableConfig(name string) *Table

func (*Module) Tables

func (m *Module) Tables() map[string]Table

func (*Module) ViewConfig

func (m *Module) ViewConfig(name string) *View

func (*Module) Views

func (m *Module) Views() map[string]View

type Mutation added in v0.7.0

type Mutation struct {
	Base  string    `json:"base"`
	Table string    `json:"table"`
	Op    string    `json:"op"`
	Rows  int64     `json:"rows"`
	Key   Any       `json:"key,omitempty"`
	Keys  []Any     `json:"keys,omitempty"`
	Data  Map       `json:"data,omitempty"`
	Where Map       `json:"where,omitempty"`
	At    time.Time `json:"at"`
}

type NotExpr added in v0.7.0

type NotExpr struct{ Item Expr }

type NullExpr added in v0.7.0

type NullExpr struct {
	Field string
	Yes   bool
}

type OrExpr added in v0.7.0

type OrExpr struct{ Items []Expr }

type ParameterLimiter added in v0.26.0

type ParameterLimiter interface {
	MaxParams() int
}

type PlanOptions added in v0.7.0

type PlanOptions struct {
	Enable   bool
	Capacity int
	TTL      time.Duration
}

type PoolStats added in v0.7.0

type PoolStats struct {
	Name         string  `json:"name"`
	Driver       string  `json:"driver"`
	Open         int     `json:"open"`
	InUse        int     `json:"inUse"`
	Idle         int     `json:"idle"`
	WaitCount    int64   `json:"waitCount"`
	WaitDuration int64   `json:"waitDurationMs"`
	MaxOpen      int     `json:"maxOpen"`
	Queries      int64   `json:"queries"`
	Writes       int64   `json:"writes"`
	Errors       int64   `json:"errors"`
	CacheHit     int64   `json:"cacheHit"`
	CacheRate    float64 `json:"cacheRate"`
	Slow         int64   `json:"slow"`
	SlowAvgMs    int64   `json:"slowAvgMs"`
	SlowP50Ms    int64   `json:"slowP50Ms"`
	SlowP95Ms    int64   `json:"slowP95Ms"`
}

func GetPoolStats added in v0.7.0

func GetPoolStats(names ...string) []PoolStats

type Query added in v0.7.0

type Query struct {
	Select      []string
	Filter      Expr
	Sort        []Sort
	Limit       int64
	Offset      int64
	After       Map
	WithCount   bool
	WithDeleted bool
	OnlyDeleted bool
	Unscoped    bool
	Unsafe      bool
	Batch       int64
	Group       []string
	Aggs        []Agg
	Having      Expr
	Joins       []Join

	RawWhere  string
	RawParams []Any
}

func Parse added in v0.7.0

func Parse(args ...Any) (Query, error)

func ParseQuery added in v0.7.0

func ParseQuery(args ...Any) (Query, error)

type RawExpr added in v0.7.0

type RawExpr struct {
	SQL    string
	Params []Any
}

type SQLBuilder added in v0.7.0

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

func NewSQLBuilder added in v0.7.0

func NewSQLBuilder(d Dialect) *SQLBuilder

func (*SQLBuilder) Args added in v0.7.0

func (b *SQLBuilder) Args() []Any

func (*SQLBuilder) CompileExpr added in v0.7.0

func (b *SQLBuilder) CompileExpr(e Expr) (string, error)

func (*SQLBuilder) CompileWhere added in v0.7.0

func (b *SQLBuilder) CompileWhere(q Query) (string, []Any, error)

type ScanFunc added in v0.7.0

type ScanFunc func(Map) Res

type Sort added in v0.7.0

type Sort struct {
	Field string
	Desc  bool
}

type Stats added in v0.7.0

type Stats struct {
	Queries     int64   `json:"queries"`
	Writes      int64   `json:"writes"`
	Errors      int64   `json:"errors"`
	Slow        int64   `json:"slow"`
	CacheHit    int64   `json:"cacheHit"`
	CacheMiss   int64   `json:"cacheMiss"`
	CacheFlight int64   `json:"cacheFlight"`
	CacheWait   int64   `json:"cacheWait"`
	CacheRate   float64 `json:"cacheRate"`
	SlowAvgMs   int64   `json:"slowAvgMs"`
	SlowP50Ms   int64   `json:"slowP50Ms"`
	SlowP95Ms   int64   `json:"slowP95Ms"`
	ChangeIn    int64   `json:"changeIn"`
	ChangeDrop  int64   `json:"changeDrop"`
	ChangeFail  int64   `json:"changeFail"`
}

func GetStats added in v0.7.0

func GetStats(names ...string) Stats

type Table

type Table struct {
	Name     string
	Desc     string
	Schema   string
	Table    string
	Key      string
	Fields   Vars
	Indexes  []Index
	Cascades []Cascade
	Setting  Map
}

func GetTable

func GetTable(name string) *Table

type TrashOptions added in v0.12.0

type TrashOptions struct {
	Enable  bool
	Field   string
	Value   string
	Cascade string
}

type TrueExpr added in v0.7.0

type TrueExpr struct{}

type TxFunc added in v0.7.0

type TxFunc func(DataBase) Res

type UpdateWatcher added in v0.7.0

type UpdateWatcher struct {
	Name   string
	Desc   string
	Action func(Mutation)
}

type UpsertWatcher added in v0.7.0

type UpsertWatcher struct {
	Name   string
	Desc   string
	Action func(Mutation)
}

type ValueBinder added in v0.26.0

type ValueBinder interface {
	BindValue(Var, any) (any, bool)
}

type ValueDecoder added in v0.26.0

type ValueDecoder interface {
	DecodeValue(Var, any) (any, bool)
}

type View

type View struct {
	Name    string
	Desc    string
	Schema  string
	View    string
	Key     string
	Fields  Vars
	Setting Map
}

func GetView

func GetView(name string) *View

type Watcher added in v0.7.0

type Watcher struct {
	Name   string
	Desc   string
	Action func(Mutation)
	Insert func(Mutation)
	Update func(Mutation)
	Upsert func(Mutation)
	Delete func(Mutation)
}

type Watchers added in v0.7.0

type Watchers map[string]Watcher

Jump to

Keyboard shortcuts

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