Documentation ¶
Overview ¶
Package ngorm is a Go Object relation mapper that focus on performance, maintainability, modularity, battle testing, extensibility , safety and developer friendliness.
Installation ¶
You can install with go get
go get -u github.com/ngorm/ngorm
Supported databases ¶
At the moment the following databases are supported
- ql
- postgresql
Example (BelongsTo) ¶
//One to many relationship db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() // Here one user can only have one profile. But one profile can belong // to multiple users. type Profile struct { model.Model Name string } type User struct { model.Model Profile Profile ProfileID int } _, err = db.Automigrate(&User{}, &Profile{}) if err != nil { log.Fatal(err) } u := User{ Profile: Profile{Name: "gernest"}, } // Creating the user with the Profile. The relation will // automatically be created and the user.ProfileID will be set to // the ID of hte created profile. err = db.Create(&u) if err != nil { log.Fatal(err) } fmt.Println(u.ProfileID == int(u.Profile.ID) && u.ProfileID != 0)
Output: true
Example (Migration) ¶
type Profile struct { model.Model Name string } type User struct { model.Model Profile Profile ProfileID int64 } db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() // you can inspect expected generated query s, err := db.AutomigrateSQL(&User{}, &Profile{}) if err != nil { log.Fatal(err) } fmt.Println(s.Q) // Or you can execute migrations like so _, err = db.Begin().Automigrate(&User{}, &Profile{}) if err != nil { log.Fatal(err) }
Output: BEGIN TRANSACTION; CREATE TABLE users (id int64,created_at time,updated_at time,deleted_at time,profile_id int64 ) ; CREATE INDEX idx_users_deleted_at ON users(deleted_at); CREATE TABLE profiles (id int64,created_at time,updated_at time,deleted_at time,name string ) ; CREATE INDEX idx_profiles_deleted_at ON profiles(deleted_at); COMMIT;
Index ¶
- type Association
- type DB
- func (db *DB) AddForeignKey(field string, dest string, onDelete string, onUpdate string) error
- func (db *DB) AddForeignKeySQL(field string, dest string, onDelete string, onUpdate string) (string, error)
- func (db *DB) AddIndex(indexName string, columns ...string) (sql.Result, error)
- func (db *DB) AddIndexSQL(indexName string, columns ...string) (*model.Expr, error)
- func (db *DB) AddUniqueIndex(indexName string, columns ...string) (sql.Result, error)
- func (db *DB) Assign(attrs ...interface{}) *DB
- func (db *DB) Association(column string) (*Association, error)
- func (db *DB) Attrs(attrs ...interface{}) *DB
- func (db *DB) Automigrate(models ...interface{}) (sql.Result, error)
- func (db *DB) AutomigrateSQL(models ...interface{}) (*model.Expr, error)
- func (db *DB) Begin() *DB
- func (db *DB) Close() error
- func (db *DB) Count(value interface{}) error
- func (db *DB) Create(value interface{}) error
- func (db *DB) CreateSQL(value interface{}) (*model.Expr, error)
- func (db *DB) CreateTable(models ...interface{}) (sql.Result, error)
- func (db *DB) CreateTableSQL(models ...interface{}) (*model.Expr, error)
- func (db *DB) Delete(value interface{}, where ...interface{}) error
- func (db *DB) DeleteSQL(value interface{}, where ...interface{}) (*model.Expr, error)
- func (db *DB) Dialect() dialects.Dialect
- func (db *DB) DropColumn(column string) (sql.Result, error)
- func (db *DB) DropTable(models ...interface{}) (sql.Result, error)
- func (db *DB) DropTableIfExists(values ...interface{}) error
- func (db *DB) DropTableSQL(models ...interface{}) (*model.Expr, error)
- func (db *DB) ExecTx(query string, args ...interface{}) (sql.Result, error)
- func (db *DB) Find(out interface{}, where ...interface{}) error
- func (db *DB) FindSQL(out interface{}, where ...interface{}) (*model.Expr, error)
- func (db *DB) First(out interface{}, where ...interface{}) error
- func (db *DB) FirstOrCreate(out interface{}, where ...interface{}) error
- func (db *DB) FirstOrInit(out interface{}, where ...interface{}) error
- func (db *DB) FirstSQL(out interface{}, where ...interface{}) (*model.Expr, error)
- func (db *DB) Group(query string) *DB
- func (db *DB) HasTable(value interface{}) bool
- func (db *DB) Having(query string, values ...interface{}) *DB
- func (db *DB) Joins(query string, args ...interface{}) *DB
- func (db *DB) Last(out interface{}, where ...interface{}) error
- func (db *DB) LastSQL(out interface{}, where ...interface{}) (*model.Expr, error)
- func (db *DB) Limit(limit interface{}) *DB
- func (db *DB) Model(value interface{}) *DB
- func (db *DB) ModifyColumn(column string, typ string) (sql.Result, error)
- func (db *DB) NewEngine() *engine.Engine
- func (db *DB) Not(query interface{}, args ...interface{}) *DB
- func (db *DB) Offset(offset interface{}) *DB
- func (db *DB) Omit(columns ...string) *DB
- func (db *DB) Or(query interface{}, args ...interface{}) *DB
- func (db *DB) Order(value interface{}, reorder ...bool) *DB
- func (db *DB) Ping() error
- func (db *DB) Pluck(column string, value interface{}) error
- func (db *DB) Preload(column string, conditions ...interface{}) *DB
- func (db *DB) Related(value interface{}, foreignKeys ...string) error
- func (db *DB) RemoveIndex(indexName string) error
- func (db *DB) SQLCommon() model.SQLCommon
- func (db *DB) Save(value interface{}) error
- func (db *DB) SaveSQL(value interface{}) (*model.Expr, error)
- func (db *DB) Select(query interface{}, args ...interface{}) *DB
- func (db *DB) Set(key string, value interface{}) *DB
- func (db *DB) SingularTable(enable bool)
- func (db *DB) Table(name string) *DB
- func (db *DB) Update(attrs ...interface{}) error
- func (db *DB) UpdateColumn(attrs ...interface{}) error
- func (db *DB) UpdateColumns(values interface{}) error
- func (db *DB) UpdateSQL(attrs ...interface{}) (*model.Expr, error)
- func (db *DB) Updates(values interface{}, ignoreProtectedAttrs ...bool) error
- func (db *DB) UpdatesSQL(values interface{}, ignoreProtectedAttrs ...bool) (*model.Expr, error)
- func (db *DB) Verbose(b bool)
- func (db *DB) Where(query interface{}, args ...interface{}) *DB
- type Opener
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Association ¶
type Association struct {
// contains filtered or unexported fields
}
Association provides utility functions for dealing with association queries
func (*Association) Append ¶
func (a *Association) Append(values ...interface{}) error
Append append new associations for many2many, has_many, replace current association for has_one, belongs_to
This wraps around Association.Save, verbatim meaning you can have the same effect with Save method.
func (*Association) Count ¶
func (a *Association) Count() (int, error)
Count return the count of current associations
func (*Association) Find ¶
func (a *Association) Find(v interface{}) error
Find find out all related associations
func (*Association) Save ¶
func (a *Association) Save(values ...interface{}) error
Save save passed values as associations. This expects to have a single value for a has_one, belongs_to relationships. You can pass one or more values for many_to_many relationship.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB provide an API for interacting with SQL databases using Go data structures.
func Open ¶
Open opens a database connection and returns *DB instance., dialect is the name of the driver that you want to use. The underlying connections are handled by database/sql package. Arguments that are accepted by database/sql Open function are valid here.
Not all databases are supported. There is still an ongoing efforts to add more databases but for now the following are the databases supported by this library,
The drivers for the libraries must be imported inside your application in the same package as you invoke this function.
Example
import _ "github.com/cznic/ql/driver" // imports ql driver
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() fmt.Println(db.Dialect().GetName())
Output: ql-mem
func OpenWithOpener ¶
OpenWithOpener uses the opener to initialize the dialects and establish database connection. In fact Open does not do anything by itself, it just calls this function with the default Opener.
Please see Open function for details. The only difference is here you need to pass an Opener. See the Opener interface for details about what the Opener is and what it is used for.
func (*DB) AddForeignKey ¶
AddForeignKey adds foreign key to an existing table.
func (*DB) AddForeignKeySQL ¶
func (db *DB) AddForeignKeySQL(field string, dest string, onDelete string, onUpdate string) (string, error)
AddForeignKeySQL generates sql to adds foreign key to an existing table.
func (*DB) AddIndexSQL ¶
AddIndexSQL generates SQL to add index for columns with given name
func (*DB) AddUniqueIndex ¶
AddUniqueIndex add unique index for columns with given name
func (*DB) Association ¶
func (db *DB) Association(column string) (*Association, error)
Association returns association object
func (*DB) Automigrate ¶
Automigrate creates tables that map to models if the tables don't exist yet in the database. This also takes care of situation where the models's fields have been updated(changed)
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Bar struct { ID int64 Say string } type Bun struct { ID int64 Dead bool } _, err = db.Automigrate(&Bar{}, &Bun{}) if err != nil { log.Fatal(err) } var names []string qdb := db.SQLCommon() rows, err := qdb.Query("select Name from __Table ") if err != nil { log.Fatal(err) } defer func() { _ = rows.Close() }() for rows.Next() { var n string err = rows.Scan(&n) if err != nil { log.Fatal(err) fmt.Println(err) } names = append(names, n) } if err := rows.Err(); err != nil { log.Fatal(err) } sort.Strings(names) for _, v := range names { fmt.Println(v) }
Output: bars buns
func (*DB) AutomigrateSQL ¶
AutomigrateSQL generates sql query for running migrations on models.
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Bar struct { ID int64 Say string } type Bun struct { ID int64 Dead bool } sql, err := db.AutomigrateSQL(&Bar{}, &Bun{}) if err != nil { log.Fatal(err) } fmt.Println(sql.Q)
Output: BEGIN TRANSACTION; CREATE TABLE bars (id int64,say string ) ; CREATE TABLE buns (id int64,dead bool ) ; COMMIT;
func (*DB) Begin ¶
Begin gives back a fresh copy of DB ready for chaining methods that operates on the same model..
func (*DB) Close ¶
Close closes the database connection and sends Done signal across all goroutines that subscribed to this instance context.
func (*DB) Count ¶
Count get how many records for a model
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Foo struct { ID int64 Stuff string } _, err = db.Automigrate(&Foo{}) if err != nil { log.Fatal(err) } sample := []string{"a", "b", "c", "d"} for _, v := range sample { err := db.Create(&Foo{Stuff: v}) if err != nil { log.Fatal(err) } } var stuffs int64 err = db.Model(&Foo{}).Count(&stuffs) if err != nil { log.Fatal(err) } fmt.Println(stuffs)
Output: 4
func (*DB) Create ¶
Create creates a new record.
You can hijack the execution of the generated SQL by overriding model.HookCreateExec hook.
func (*DB) CreateSQL ¶
CreateSQL generates SQl query for creating a new record/records for value. The end query is wrapped under for ql dialectTRANSACTION block.
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Bar struct { ID int64 Say string } b := Bar{Say: "hello"} sql, err := db.CreateSQL(&b) if err != nil { log.Fatal(err) } fmt.Println(sql.Q) fmt.Printf("$1=%v", sql.Args[0])
Output: BEGIN TRANSACTION; INSERT INTO bars (say) VALUES ($1); COMMIT; $1=hello
Example (ExtraOptions) ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Bar struct { ID int64 Say string } b := Bar{Say: "hello"} sql, err := db.Set(model.InsertOptions, "ON CONFLICT"). CreateSQL(&b) if err != nil { log.Fatal(err) } fmt.Println(sql.Q) fmt.Printf("$1=%v", sql.Args[0])
Output: BEGIN TRANSACTION; INSERT INTO bars (say) VALUES ($1) ON CONFLICT; COMMIT; $1=hello
func (*DB) CreateTable ¶
CreateTable creates new database tables that maps to the models.
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type User struct { ID int64 Name string Password string Email string } _, err = db.CreateTable(&User{}) if err != nil { log.Fatal(err) } fmt.Println(db.Dialect().HasTable("users"))
Output: true
func (*DB) CreateTableSQL ¶
CreateTableSQL return the sql query for creating tables for all the given models. The queries are wrapped in a TRANSACTION block.
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type User struct { ID int64 Name string Password string Email string } sql, err := db.CreateTableSQL(&User{}) if err != nil { log.Fatal(err) } e := ` BEGIN TRANSACTION; CREATE TABLE users (id int64,name string,password string,email string ) ; COMMIT; ` sql.Q = strings.TrimSpace(sql.Q) e = strings.TrimSpace(e) fmt.Println(sql.Q == e)
Output: true
func (*DB) Delete ¶
Delete delete value match given conditions, if the value has primary key, then will including the primary key as condition
func (*DB) DeleteSQL ¶
DeleteSQL generates SQL to delete value match given conditions, if the value has primary key, then will including the primary key as condition
func (*DB) DropColumn ¶
DropColumn drop a column
func (*DB) DropTable ¶
DropTable drops tables that are mapped to models. You can also pass the name of the table as astring and it will be handled.
func (*DB) DropTableIfExists ¶
DropTableIfExists drop table if it is exist
func (*DB) DropTableSQL ¶
DropTableSQL generates sql query for DROP TABLE. The generated query is wrapped under TRANSACTION block.
func (*DB) ExecTx ¶
ExecTx wraps the query execution in a Transaction. This ensure all operations are Rolled back in case the execution fails.
func (*DB) Find ¶
Find find records that match given conditions
Example ¶
type User struct { ID int64 Name string } db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() _, err = db.Automigrate(&User{}) if err != nil { log.Fatal(err) } v := []string{"gernest", "kemi", "helen"} for _, n := range v { err = db.Begin().Save(&User{Name: n}) if err != nil { log.Fatal(err) } } users := []User{} err = db.Begin().Find(&users) if err != nil { log.Fatal(err) } for _, u := range users { fmt.Println(u.Name) }
Output: helen kemi gernest
func (*DB) FirstOrCreate ¶
FirstOrCreate find first matched record or create a new one with given conditions (only works with struct, map conditions)
func (*DB) FirstOrInit ¶
FirstOrInit find first matched record or initialize a new one with given conditions (only works with struct, map conditions)
func (*DB) FirstSQL ¶
FirstSQL returns SQL query for retrieving the first record ordering by primary key.
func (*DB) HasTable ¶
HasTable returns true if there is a table for the given value, the value can either be a string representing a table name or a ngorm model.
func (*DB) LastSQL ¶
LastSQL returns SQL query for retrieving the last record ordering by primary key.
func (*DB) Model ¶
Model sets value as the database model. This model will be used for future calls on the returned DB e.g
db.Model(&user).Update("name","hero")
You don't have to call db.Begin().Model() since this calls Begin automatically for you. It is safe for chaining.
func (*DB) ModifyColumn ¶
ModifyColumn modify column to type
func (*DB) Offset ¶
Offset specify the number of records to skip before starting to return the records
func (*DB) Omit ¶
Omit specify fields that you want to ignore when saving to database for creating, updating
func (*DB) Order ¶
Order specify order when retrieve records from database, set reorder to `true` to overwrite defined conditions
db.Order("name DESC") db.Order("name DESC", true) // reorder
func (*DB) Pluck ¶
Pluck used to query single column from a model as a map
var ages []int64 db.Find(&users).Pluck("age", &ages)
func (*DB) Preload ¶
Preload preload associations with given conditions
db.Preload("Orders", "state NOT IN (?)", "cancelled").Find(&users)
func (*DB) RemoveIndex ¶
RemoveIndex remove index with name
func (*DB) Save ¶
Save update value in database, if the value doesn't have primary key, will insert it
func (*DB) SaveSQL ¶
SaveSQL generates SQL query for saving/updating database record for value.
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Foo struct { ID int64 Stuff string } f := Foo{ID: 10, Stuff: "twenty"} sql, err := db.SaveSQL(&f) if err != nil { log.Fatal(err) } fmt.Println(sql.Q) fmt.Printf("$1=%v\n", sql.Args[0]) fmt.Printf("$2=%v", sql.Args[1])
Output: BEGIN TRANSACTION; UPDATE foos SET stuff = $1 WHERE id = $2; COMMIT; $1=twenty $2=10
func (*DB) Select ¶
Select specify fields that you want to retrieve from database when querying, by default, will select all fields; When creating/updating, specify fields that you want to save to database
func (*DB) SingularTable ¶
SingularTable enables or disables singular tables name. By default this is disabled, meaning table names are in plural.
Model | Plural table name ---------------------------- Session | sessions User | users Model | Singular table name ---------------------------- Session | session User | user
func (*DB) UpdateColumn ¶
UpdateColumn update attributes without callbacks
func (*DB) UpdateColumns ¶
UpdateColumns update attributes without
func (*DB) UpdateSQL ¶
UpdateSQL generates SQL that will be executed when you use db.Update
Example ¶
db, err := Open("ql-mem", "test.db") if err != nil { log.Fatal(err) } defer func() { _ = db.Close() }() type Foo struct { ID int64 Stuff string } f := Foo{ID: 10, Stuff: "twenty"} sql, err := db.Model(&f).UpdateSQL("stuff", "hello") if err != nil { log.Fatal(err) } fmt.Println(sql.Q) fmt.Printf("$1=%v\n", sql.Args[0]) fmt.Printf("$2=%v", sql.Args[1])
Output: BEGIN TRANSACTION; UPDATE foos SET stuff = $1 WHERE id = $2; COMMIT; $1=hello $2=10
func (*DB) UpdatesSQL ¶
UpdatesSQL generates sql that will be used when you run db.UpdatesSQL
Directories ¶
Path | Synopsis |
---|---|
Package builder contains functions for SQL building.
|
Package builder contains functions for SQL building. |
Package dialects defines a uniform interface for creating custom support for different SQL databases.
|
Package dialects defines a uniform interface for creating custom support for different SQL databases. |
Package engine defines the core structure that drives the ngorm API.
|
Package engine defines the core structure that drives the ngorm API. |
Package fixture contains all stuctures neesessary for consinstent testing on a wide range of SQL database dialects.
|
Package fixture contains all stuctures neesessary for consinstent testing on a wide range of SQL database dialects. |
Package hooks contains callbacks/hooks used by ngorm.
|
Package hooks contains callbacks/hooks used by ngorm. |
Package model defines structures that are shared through out ngorm.
|
Package model defines structures that are shared through out ngorm. |
Package regexes exposes pre compiled regular expressions that are used by ngorm.
|
Package regexes exposes pre compiled regular expressions that are used by ngorm. |
Package scope defines functions that operates on engine.Engine and enables operating on model values easily.
|
Package scope defines functions that operates on engine.Engine and enables operating on model values easily. |
Package search contains search functions for ngorm.
|
Package search contains search functions for ngorm. |
Package util contains utility functions that are used in dirrent places of the codebase.
|
Package util contains utility functions that are used in dirrent places of the codebase. |