data

package module
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Feb 28, 2026 License: MIT Imports: 20 Imported by: 0

README

data

bamgoo data module with Mongo-like Map query DSL and SQL drivers.

Naming Mapping

Disabled by default. Enable in config to map camelCase <-> snake_case automatically.

[data]
mapping = true

Query DSL

  • compare: $eq $ne $gt $gte $lt $lte $in $nin
  • json/array: $contains $overlap $elemMatch
  • logic: $and $or $nor $not
  • text: $like $ilike $regex
  • options: $select $sort $limit $offset $after $group $having $join $agg $unsafe

Sort Notes

  • Single-field sort: use Map
  • Multi-field sort: use []Map to preserve order
// single-field
rows1 := db.Table("article").Query(base.Map{
  "$sort": base.Map{"id": base.DESC},
})
_ = rows1

// multi-field (ordered)
rows2 := db.Table("article").Query(base.Map{
  "$sort": []base.Map{
    {"id": base.ASC},
    {"views": base.DESC},
  },
})
_ = rows2

Update DSL

  • $set
  • $inc
  • $unset
  • $push
  • $pull
  • $addToSet
  • $setPath
  • $unsetPath

Driver Notes

  • pgsql: native support for $contains/$overlap/$elemMatch (json/array operators).
  • mysql: uses JSON functions for $contains/$overlap/$elemMatch.
  • sqlite: $contains fallback is string-search; $overlap/$elemMatch are not supported directly.

Capabilities

caps, _ := data.GetCapabilities()
fmt.Println(caps)
// {Dialect:sqlite ILike:false Returning:false Join:true ...}

Join Example

rows, err := db.View("order").Query(base.Map{
  "$select": []string{"order.id", "order.amount", "user.name"},
  "$join": []base.Map{
    {
      "from": "user",
      "alias": "user",
      "type": "left",
      "localField": "order.user_id",
      "foreignField": "user.id",
    },
  },
  "user.status": "active",
  "$sort": base.Map{"order.id": base.ASC},
  "$limit": 20,
})
_ = rows
_ = err

Keyset Pagination ($after)

page1, _ := db.Table("user").Query(base.Map{
  "$sort": base.Map{"id": base.ASC},
  "$limit": 20,
})

page2, _ := db.Table("user").Query(base.Map{
  "$sort": base.Map{"id": base.ASC},
  "$after": base.Map{"id": page1[len(page1)-1]["id"]},
  "$limit": 20,
})

Aggregate Example

rows, _ := db.View("order").Aggregate(base.Map{
  "status": "paid",
  "$group": []string{"user_id"},
  "$agg": base.Map{
    "total_amount": base.Map{"sum": "amount"},
    "avg_amount":   base.Map{"avg": "amount"},
    "cnt":          base.Map{"count": "*"},
  },
  "$having": base.Map{
    "total_amount": base.Map{"$gt": 100},
  },
  "$sort": base.Map{"total_amount": base.DESC},
})
_ = rows

Slice (total + items)

total, items := db.Table("user").Slice(0, 20, base.Map{
  "status": "active",
  "$sort": base.Map{"id": base.DESC},
})
if db.Error() != nil {
  return
}
_ = total
_ = items

Tx / Batch

_ = db.Tx(func(tx data.DataBase) error {
  _, err := tx.Table("user").InsertMany([]base.Map{
    {"name": "A"},
    {"name": "B"},
  })
  return err
})

Safety Guard

By default, full-table Update/Delete is blocked unless query has filter.

_, err := db.Table("user").Delete(base.Map{
  "$unsafe": true,
})
_ = err

Join Field Ref

rows, _ := db.View("order").Query(base.Map{
  "$join": []base.Map{
    {"from": "user", "alias": "u", "on": base.Map{
      "order.user_id": base.Map{"$eq": "$field:u.id"},
    }},
  },
})
_ = rows

JSON/Array Example

users, _ := db.Table("user").Query(base.Map{
  "tags": base.Map{"$contains": []string{"go"}},
  "$sort": base.Map{"id": base.ASC},
})
_ = users

Example

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

item, _ := db.Table("user").Upsert(base.Map{
  "$set": base.Map{"name": "Alice"},
  "$inc": base.Map{"login_times": 1},
}, base.Map{"id": 1001})

_ = item

rows, _ := db.View("order").Aggregate(base.Map{
  "$group": []string{"user_id"},
  "$agg": base.Map{
    "total": base.Map{"sum": "amount"},
    "cnt":   base.Map{"count": "*"},
  },
  "$having": base.Map{"total": base.Map{"$gt": 100}},
})

_ = rows

Documentation

Index

Constants

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

Variables

View Source
var (
	ErrNotFound      = errors.New("data: not found")
	ErrConflict      = errors.New("data: conflict")
	ErrUnsupported   = errors.New("data: unsupported")
	ErrInvalidQuery  = errors.New("data: invalid query")
	ErrInvalidUpdate = errors.New("data: invalid update")
	ErrTxFailed      = errors.New("data: tx failed")
	ErrValidation    = errors.New("data: validation")
	ErrDriver        = errors.New("data: driver")
	ErrTimeout       = errors.New("data: timeout")
)

Functions

func BuildGroupBy

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

func BuildLimitOffset

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

func BuildOrderBy

func BuildOrderBy(q Query, dialect Dialect) string

func CacheToken added in v0.3.0

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

func CamelFieldPath added in v0.2.0

func CamelFieldPath(field string) string

func EmitMutation added in v0.3.0

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

func Error added in v0.3.0

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

func ErrorKind added in v0.3.0

func ErrorKind(err error) string

func Field added in v0.5.0

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

func Fields added in v0.5.0

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

func GenerateTableKeys added in v0.1.1

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 Migrate added in v0.2.0

func Migrate(names ...string) error

func MigrateDown added in v0.2.0

func MigrateDown(steps int) error

func MigrateDownOn added in v0.2.0

func MigrateDownOn(base string, steps int) error

func MigrateOn added in v0.2.0

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

func MigrateUp added in v0.2.0

func MigrateUp(versions ...string) error

func MigrateUpOn added in v0.2.0

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

func Models

func Models() map[string]Model

func Option added in v0.5.0

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

func Options added in v0.5.0

func Options(name string, field string) Map

func QuerySignature added in v0.3.0

func QuerySignature(q Query) string

func RegisterConfig

func RegisterConfig(name string, cfg Config)

func RegisterDeleteWatcher added in v0.3.0

func RegisterDeleteWatcher(name string, watcher DeleteWatcher)

func RegisterDriver

func RegisterDriver(name string, driver Driver)

func RegisterInsertWatcher added in v0.3.0

func RegisterInsertWatcher(name string, watcher InsertWatcher)

func RegisterMigration added in v0.2.0

func RegisterMigration(name string, migration Migration)

func RegisterModel

func RegisterModel(name string, model Model)

func RegisterTable

func RegisterTable(name string, table Table)

func RegisterUpdateWatcher added in v0.3.0

func RegisterUpdateWatcher(name string, watcher UpdateWatcher)

func RegisterUpsertWatcher added in v0.3.0

func RegisterUpsertWatcher(name string, watcher UpsertWatcher)

func RegisterView

func RegisterView(name string, view View)

func RegisterWatcher added in v0.3.0

func RegisterWatcher(name string, watcher Watcher)

func RegisterWatchers added in v0.3.0

func RegisterWatchers(items Watchers)

func SnakeFieldPath added in v0.2.0

func SnakeFieldPath(field string) string

func Tables

func Tables() map[string]Table

func TouchTableCache added in v0.3.0

func TouchTableCache(name, table string) uint64

func Views

func Views() map[string]View

Types

type Agg

type Agg struct {
	Alias string
	Op    string
	Field string
}

type AndExpr

type AndExpr struct{ Items []Expr }

type Capabilities

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

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

type CmpExpr

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
	Watcher     Map
	Migrate     MigrateOptions
	Setting     Map
}

type Configs

type Configs map[string]Config

type Connection

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) error
	TxReadOnly(TxFunc) error
	Migrate(...string)
	MigratePlan(...string) MigrateReport
	MigrateDiff(...string) MigrateReport
	MigrateUp(...string)
	MigrateDown(int)
	MigrateTo(string)
	MigrateDownTo(string)
	Capabilities() Capabilities
	Error() error
	ClearError()

	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

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

func (*DataError) Error

func (e *DataError) Error() string

func (*DataError) Is

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

func (*DataError) Unwrap

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
	Change(Map, Map) Map
	Remove(...Any) Map
	Update(Map, ...Any) int64
	Delete(...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.3.0

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

type Dialect

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 ExistsExpr

type ExistsExpr struct {
	Field string
	Yes   bool
}

type Expr

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

type FieldRef

type FieldRef string

func Ref

func Ref(field string) FieldRef

type Health

type Health struct {
	Workload int64
}

type Index added in v0.1.1

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

type InsertWatcher added in v0.3.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

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

type MigrateAction added in v0.2.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"`
}

type MigrateOptions added in v0.2.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.2.0

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

func MigrateDiff added in v0.2.0

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

func MigrateDiffOn added in v0.2.0

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

func MigratePlan added in v0.2.0

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

func MigratePlanOn added in v0.2.0

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

type Migration added in v0.2.0

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

func Migrations added in v0.2.0

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

func (Migration) Checksum added in v0.2.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 added in v0.5.0

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

func (m *Module) Close()

func (*Module) Config

func (m *Module) Config(global Map)

func (*Module) Field added in v0.5.0

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

func (*Module) Fields added in v0.5.0

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

func (*Module) GetCapabilities

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

func (*Module) ModelConfig added in v0.5.0

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

func (*Module) Models

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

func (*Module) Open

func (m *Module) Open()

func (*Module) Option added in v0.5.0

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

func (*Module) Options added in v0.5.0

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

func (*Module) PoolStats added in v0.3.0

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

func (*Module) Register

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

func (*Module) RegisterConfig

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

func (*Module) RegisterConfigs

func (m *Module) RegisterConfigs(configs Configs)

func (*Module) RegisterDeleteWatcher added in v0.3.0

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

func (*Module) RegisterDriver

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

func (*Module) RegisterInsertWatcher added in v0.3.0

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

func (*Module) RegisterMigration added in v0.2.0

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

func (*Module) RegisterModel

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

func (*Module) RegisterTable

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

func (*Module) RegisterUpdateWatcher added in v0.3.0

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

func (*Module) RegisterUpsertWatcher added in v0.3.0

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

func (*Module) RegisterView

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

func (*Module) RegisterWatcher added in v0.3.0

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

func (*Module) RegisterWatchers added in v0.3.0

func (m *Module) RegisterWatchers(items Watchers)

func (*Module) Setup

func (m *Module) Setup()

func (*Module) Start

func (m *Module) Start()

func (*Module) Stats

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

func (*Module) Stop

func (m *Module) Stop()

func (*Module) TableConfig added in v0.5.0

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

func (*Module) Tables

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

func (*Module) ViewConfig added in v0.5.0

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

func (*Module) Views

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

type Mutation added in v0.3.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"`
	Data  Map       `json:"data,omitempty"`
	Where Map       `json:"where,omitempty"`
	At    time.Time `json:"at"`
}

type NotExpr

type NotExpr struct{ Item Expr }

type NullExpr

type NullExpr struct {
	Field string
	Yes   bool
}

type OrExpr

type OrExpr struct{ Items []Expr }

type PlanOptions added in v0.2.0

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

type PoolStats added in v0.3.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.3.0

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

type Query

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

	RawWhere  string
	RawParams []Any
}

func Parse

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

func ParseQuery

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

type RawExpr

type RawExpr struct {
	SQL    string
	Params []Any
}

type SQLBuilder

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

func NewSQLBuilder

func NewSQLBuilder(d Dialect) *SQLBuilder

func (*SQLBuilder) Args

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

func (*SQLBuilder) CompileExpr

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

func (*SQLBuilder) CompileWhere

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

type ScanFunc added in v0.2.0

type ScanFunc func(Map) Res

type Sort

type Sort struct {
	Field string
	Desc  bool
}

type Stats

type Stats struct {
	Queries    int64   `json:"queries"`
	Writes     int64   `json:"writes"`
	Errors     int64   `json:"errors"`
	Slow       int64   `json:"slow"`
	CacheHit   int64   `json:"cacheHit"`
	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

func GetStats(names ...string) Stats

type Table

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

func GetTable added in v0.5.0

func GetTable(name string) *Table

type TrueExpr

type TrueExpr struct{}

type TxFunc

type TxFunc func(DataBase) error

type UpdateWatcher added in v0.3.0

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

type UpsertWatcher added in v0.3.0

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

type View

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

func GetView added in v0.5.0

func GetView(name string) *View

type Watcher added in v0.3.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.3.0

type Watchers map[string]Watcher

Jump to

Keyboard shortcuts

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