README
¶
grimoire
Grimoire is a database access layer inspired by Ecto. It features a flexible query API and built-in validation. It currently supports MySQL, PostgreSQL, and SQLite3 but a custom adapter can be implemented easily using the Adapter interface.
Features:
- Query Builder
- Association Preloading
- Struct style create and update
- Changeset Style create and update
- Builtin validation using changeset
- Multi adapter support
- Logger
Motivation
Common go ORM accepts struct as a value for modifying records which has a problem of unable to differentiate between an empty, nil, or undefined value. It's a tricky problem especially when you want to have an endpoint that supports partial updates. Grimoire attempts to solve that problem by integrating Changeset system inspired from Elixir's Ecto. Changeset is a form like entity which allows us to not only solve that problem but also help us with casting, validations, and constraints check.
Install
go get github.com/Fs02/grimoire
Quick Start
package main
import (
"time"
"github.com/Fs02/grimoire"
"github.com/Fs02/grimoire/adapter/mysql"
"github.com/Fs02/grimoire/changeset"
"github.com/Fs02/grimoire/params"
)
type Product struct {
ID int
Name string
Price int
CreatedAt time.Time
UpdatedAt time.Time
}
// ChangeProduct prepares data before database operation.
// Such as casting value to appropriate types and perform validations.
func ChangeProduct(product interface{}, params params.Params) *changeset.Changeset {
ch := changeset.Cast(product, params, []string{"name", "price"})
changeset.ValidateRequired(ch, []string{"name", "price"})
changeset.ValidateMin(ch, "price", 100)
return ch
}
func main() {
// initialize mysql adapter.
adapter, err := mysql.Open("root@(127.0.0.1:3306)/db?charset=utf8&parseTime=True&loc=Local")
if err != nil {
panic(err)
}
defer adapter.Close()
// initialize grimoire's repo.
repo := grimoire.New(adapter)
var product Product
// Inserting Products.
// Changeset is used when creating or updating your data.
ch := ChangeProduct(product, params.Map{
"name": "shampoo",
"price": 1000,
})
if ch.Error() != nil {
// handle error
}
// Changeset can also be created directly from json string.
jsonch := ChangeProduct(product, params.ParseJSON(`{
"name": "soap",
"price": 2000,
}`))
// Create products with changeset and return the result to &product,
if err = repo.From("products").Insert(&product, ch); err != nil {
// handle error
}
// or panic when insertion pailed
repo.From("products").MustInsert(&product, jsonch)
// Querying Products.
// Find a product with id 1.
repo.From("products").Find(1).MustOne(&product)
// Updating Products.
// Update products with id=1.
repo.From("products").Find(1).MustUpdate(&product, ch)
// Deleting Products.
// Delete Product with id=1.
repo.From("products").Find(1).MustDelete()
}
Examples
Documentation
Guides: https://fs02.github.io/grimoire
API Documentation: https://godoc.org/github.com/Fs02/grimoire
License
Released under the MIT License
Documentation
¶
Overview ¶
Package grimoire is a data access layer and validation for go.
Grimoire is a database access layer inspired by Ecto's changeset system. It features flexible query API and builtin validation. It currently supports MySQL, PostgreSQL and SQLite3 but a custom adapter can be implemented easily using the Adapter interface.
Example ¶
package main
import (
"time"
"github.com/Fs02/grimoire"
"github.com/Fs02/grimoire/adapter/mysql"
"github.com/Fs02/grimoire/changeset"
"github.com/Fs02/grimoire/params"
)
type Product struct {
ID int
Name string
Price int
CreatedAt time.Time
UpdatedAt time.Time
}
// ChangeProduct prepares data before database operation.
// Such as casting value to appropriate types and perform validations.
func ChangeProduct(product interface{}, params params.Params) *changeset.Changeset {
ch := changeset.Cast(product, params, []string{"name", "price"})
changeset.ValidateRequired(ch, []string{"name", "price"})
changeset.ValidateMin(ch, "price", 100)
return ch
}
func main() {
// initialize mysql adapter.
adapter, err := mysql.Open("root@(127.0.0.1:3306)/db?charset=utf8&parseTime=True&loc=Local")
if err != nil {
panic(err)
}
defer adapter.Close()
// initialize grimoire's repo.
repo := grimoire.New(adapter)
var product Product
// Inserting Products.
// Changeset is used when creating or updating your data.
ch := ChangeProduct(product, params.Map{
"name": "shampoo",
"price": 1000,
})
if ch.Error() != nil {
// handle error
}
// Changeset can also be created directly from json string.
jsonch := ChangeProduct(product, params.ParseJSON(`{
"name": "soap",
"price": 2000,
}`))
// Create products with changeset and return the result to &product,
if err = repo.From("products").Insert(&product, ch); err != nil {
// handle error
}
// or panic when insertion pailed
repo.From("products").MustInsert(&product, jsonch)
// Querying Products.
// Find a product with id 1.
repo.From("products").Find(1).MustOne(&product)
// Updating Products.
// Update products with id=1.
repo.From("products").Find(1).MustUpdate(&product, ch)
// Deleting Products.
// Delete Product with id=1.
repo.From("products").Find(1).MustDelete()
}
Index ¶
- func DefaultLogger(query string, duration time.Duration, err error)
- func Log(logger []Logger, statement string, duration time.Duration, err error)
- type Adapter
- type Logger
- type Query
- func (query Query) Aggregate(mode string, field string, out interface{}) error
- func (query Query) All(record interface{}) error
- func (query Query) Count() (int, error)
- func (query Query) Delete() error
- func (query Query) Distinct() Query
- func (query Query) Find(id interface{}) Query
- func (query Query) FindBy(col string, val interface{}) Query
- func (query Query) Group(fields ...string) Query
- func (query Query) Having(condition ...c.Condition) Query
- func (query Query) Insert(record interface{}, chs ...*changeset.Changeset) error
- func (query Query) Join(collection string, condition ...c.Condition) Query
- func (query Query) JoinWith(mode string, collection string, condition ...c.Condition) Query
- func (query Query) Limit(limit int) Query
- func (query Query) Lock(lock ...string) Query
- func (query Query) MustAggregate(mode string, field string, out interface{})
- func (query Query) MustAll(record interface{})
- func (query Query) MustCount() int
- func (query Query) MustDelete()
- func (query Query) MustInsert(record interface{}, chs ...*changeset.Changeset)
- func (query Query) MustOne(record interface{})
- func (query Query) MustPreload(record interface{}, field string)
- func (query Query) MustSave(record interface{})
- func (query Query) MustUpdate(record interface{}, chs ...*changeset.Changeset)
- func (query Query) Offset(offset int) Query
- func (query Query) One(record interface{}) error
- func (query Query) OrHaving(condition ...c.Condition) Query
- func (query Query) OrWhere(condition ...c.Condition) Query
- func (query Query) Order(order ...c.Order) Query
- func (query Query) Preload(record interface{}, field string) error
- func (query Query) Save(record interface{}) error
- func (query Query) Select(fields ...string) Query
- func (query Query) Set(field string, value interface{}) Query
- func (query Query) Update(record interface{}, chs ...*changeset.Changeset) error
- func (query Query) Where(condition ...c.Condition) Query
- type Repo
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultLogger ¶
DefaultLogger log query suing standard log library.
Types ¶
type Adapter ¶
type Adapter interface {
All(Query, interface{}, ...Logger) (int, error)
Aggregate(Query, interface{}, ...Logger) error
Insert(Query, map[string]interface{}, ...Logger) (interface{}, error)
InsertAll(Query, []string, []map[string]interface{}, ...Logger) ([]interface{}, error)
Update(Query, map[string]interface{}, ...Logger) error
Delete(Query, ...Logger) error
Begin() (Adapter, error)
Commit() error
Rollback() error
}
Adapter interface
type Query ¶
type Query struct {
Collection string
Fields []string
AggregateField string
AggregateMode string
AsDistinct bool
JoinClause []c.Join
Condition c.Condition
GroupFields []string
HavingCondition c.Condition
OrderClause []c.Order
OffsetResult int
LimitResult int
LockClause string
Changes map[string]interface{}
// contains filtered or unexported fields
}
Query defines information about query generated by query builder.
func (Query) Lock ¶ added in v1.3.0
Lock query using pessimistic locking. Lock expression can be specified as first parameter, default to FOR UPDATE.
func (Query) MustAggregate ¶
MustAggregate calculate aggregate over the given field. It'll panic if any error eccured.
func (Query) MustAll ¶
func (query Query) MustAll(record interface{})
MustAll retrieves all results that match the query. It'll panic if any error eccured.
func (Query) MustCount ¶
MustCount retrieves count of results that match the query. It'll panic if any error eccured.
func (Query) MustDelete ¶
func (query Query) MustDelete()
MustDelete deletes all results that match the query. It'll panic if any error eccured.
func (Query) MustInsert ¶
MustInsert records to database. It'll panic if any error occurred.
func (Query) MustOne ¶
func (query Query) MustOne(record interface{})
MustOne retrieves one result that match the query. If no result found, it'll panic.
func (Query) MustPreload ¶
MustPreload loads association with given query. It'll panic if any error occurred.
func (Query) MustSave ¶
func (query Query) MustSave(record interface{})
MustSave puts a record to database. It'll panic if any error eccured.
func (Query) MustUpdate ¶
MustUpdate records in database. It'll panic if any error occurred.
func (Query) One ¶
One retrieves one result that match the query. If no result found, it'll return not found error.
func (Query) OrHaving ¶
OrHaving behaves exactly the same as having except it combines with any previous expression by using an OR.
func (Query) OrWhere ¶
OrWhere behaves exactly the same as where except it combines with any previous expression by using an OR.
func (Query) Save ¶
Save a record to database. If condition exist, it will try to update the record, otherwise it'll insert it. Save ignores id from record.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
adapter
|
|
|
mysql
Package mysql wraps mysql driver as an adapter for grimoire.
|
Package mysql wraps mysql driver as an adapter for grimoire. |
|
postgres
Package postgres wraps postgres (pq) driver as an adapter for grimoire.
|
Package postgres wraps postgres (pq) driver as an adapter for grimoire. |
|
specs
Package specs defines test specifications for grimoire's adapter.
|
Package specs defines test specifications for grimoire's adapter. |
|
sql
Package sql is general sql adapter that wraps database/sql.
|
Package sql is general sql adapter that wraps database/sql. |
|
sqlite3
Package sqlite3 wraps go-sqlite3 driver as an adapter for grimoire.
|
Package sqlite3 wraps go-sqlite3 driver as an adapter for grimoire. |
|
Package c defines function for building condition in query.
|
Package c defines function for building condition in query. |
|
Package changeset used to cast and validate data before saving it to the database.
|
Package changeset used to cast and validate data before saving it to the database. |
|
Package errors wraps driver and changeset error as a grimoire's error.
|
Package errors wraps driver and changeset error as a grimoire's error. |
|
Package params defines different types of params used for changeset input.
|
Package params defines different types of params used for changeset input. |