HiPoweredDev
/
xorm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' of github.com:lunny/xorm

This commit is contained in:
Lunny Xiao 2013-08-29 10:25:27 +08:00
parent b742ca6f3b 129fb27830
commit d2507a900f
1 changed files with 294 additions and 294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

588
README.md
View File

@ -2,211 +2,211 @@
[中文](https://github.com/lunny/xorm/blob/master/README_CN.md) [中文](https://github.com/lunny/xorm/blob/master/README_CN.md)
xorm is a simple and powerful ORM for Go. It makes dabatabse operating simple. xorm is a simple and powerful ORM for Go. It makes dabatabse operating simple.
[![Build Status](https://drone.io/github.com/lunny/xorm/status.png)](https://drone.io/github.com/lunny/xorm/latest) [![Build Status](https://drone.io/github.com/lunny/xorm/status.png)](https://drone.io/github.com/lunny/xorm/latest)
## Drivers Support ## Drivers Support
Drivers for Go's sql package which currently support database/sql includes: Drivers for Go's sql package which currently support database/sql includes:
* Mysql: [github.com/Go-SQL-Driver/MySQL](https://github.com/Go-SQL-Driver/MySQL) * Mysql: [github.com/Go-SQL-Driver/MySQL](https://github.com/Go-SQL-Driver/MySQL)
* MyMysql: [github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv) * MyMysql: [github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv)
* SQLite: [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) * SQLite: [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
* Postgres: [github.com/bylevel/pg](https://github.com/bylevel/pg) * Postgres: [github.com/bylevel/pq](https://github.com/bylevel/pq)
## Changelog ## Changelog
* **v0.1.9** : Added postgres and mymysql supported; Added ` and ? supported on Raw SQL even if postgres; Added Cols, StoreEngine, Charset function, Added many column data type supported, please see [Mapping Rules](#mapping). * **v0.1.9** : Added postgres and mymysql supported; Added ` and ? supported on Raw SQL even if postgres; Added Cols, StoreEngine, Charset function, Added many column data type supported, please see [Mapping Rules](#mapping).
* **v0.1.8** : Added union index and union unique supported, please see [Mapping Rules](#mapping). * **v0.1.8** : Added union index and union unique supported, please see [Mapping Rules](#mapping).
* **v0.1.7** : Added IConnectPool interface and NoneConnectPool, SysConnectPool, SimpleConnectPool the three implements. You can choose one of them and the default is SysConnectPool. You can customrize your own connection pool. struct Engine added Close method, It should be invoked before system exit. * **v0.1.7** : Added IConnectPool interface and NoneConnectPool, SysConnectPool, SimpleConnectPool the three implements. You can choose one of them and the default is SysConnectPool. You can customrize your own connection pool. struct Engine added Close method, It should be invoked before system exit.
* **v0.1.6** : Added conversion interface support; added struct derive support; added single mapping support * **v0.1.6** : Added conversion interface support; added struct derive support; added single mapping support
* **v0.1.5** : Added multi threads support; added Sql() function for struct query; Get function changed return inteface; MakeSession and Create are instead with NewSession and NewEngine. * **v0.1.5** : Added multi threads support; added Sql() function for struct query; Get function changed return inteface; MakeSession and Create are instead with NewSession and NewEngine.
* **v0.1.4** : Added simple cascade load support; added more data type supports. * **v0.1.4** : Added simple cascade load support; added more data type supports.
* **v0.1.3** : Find function now supports both slice and map; Add Table function for multi tables and temperory tables support * **v0.1.3** : Find function now supports both slice and map; Add Table function for multi tables and temperory tables support
* **v0.1.2** : Insert function now supports both struct and slice pointer parameters, batch inserting and auto transaction * **v0.1.2** : Insert function now supports both struct and slice pointer parameters, batch inserting and auto transaction
* **v0.1.1** : Add Id, In functions and improved README * **v0.1.1** : Add Id, In functions and improved README
* **v0.1.0** : Inital release. * **v0.1.0** : Inital release.
## Features ## Features
* Struct<->Table Mapping Supports, both name mapping and filed tags mapping * Struct<->Table Mapping Supports, both name mapping and filed tags mapping
* Database Transaction Support * Database Transaction Support
* Both ORM and SQL Operation Support * Both ORM and SQL Operation Support
* Simply usage * Simply usage
* Support Id, In, Where, Limit, Join, Having, Sql functions and sturct as query conditions * Support Id, In, Where, Limit, Join, Having, Sql functions and sturct as query conditions
* Support simple cascade load just like Hibernate for Java * Support simple cascade load just like Hibernate for Java
## Installing xorm
## Installing xorm
go get github.com/lunny/xorm go get github.com/lunny/xorm
## Quick Start ## Quick Start
1.Create a database engine just like sql.Open, commonly you just need create once. Please notice, Create function will be deprecated, use NewEngine instead. 1.Create a database engine just like sql.Open, commonly you just need create once. Please notice, Create function will be deprecated, use NewEngine instead.
```Go ```Go
import ( import (
_ "github.com/Go-SQL-Driver/MySQL" _ "github.com/Go-SQL-Driver/MySQL"
"github.com/lunny/xorm" "github.com/lunny/xorm"
) )
err, engine := xorm.NewEngine("mysql", "root:123@/test?charset=utf8") engine, err := xorm.NewEngine("mysql", "root:123@/test?charset=utf8")
defer engine.Close()
```
or
```Go
import (
_ "github.com/mattn/go-sqlite3"
"github.com/lunny/xorm"
)
err, engine = xorm.NewEngine("sqlite3", "./test.db")
defer engine.Close() defer engine.Close()
``` ```
1.1.If you want to show all generated SQL or
```Go ```Go
engine.ShowSQL = true import (
``` _ "github.com/mattn/go-sqlite3"
1.2 If you want to use your own connection pool "github.com/lunny/xorm"
```Go )
err = engine.SetPool(NewSimpleConnectPool()) engine, err = xorm.NewEngine("sqlite3", "./test.db")
``` defer engine.Close()
```
1.1.If you want to show all generated SQL
```Go
engine.ShowSQL = true
```
1.2 If you want to use your own connection pool
```Go
err = engine.SetPool(NewSimpleConnectPool())
```
2.Define a struct 2.Define a struct
```Go ```Go
type User struct { type User struct {
Id int Id int
Name string Name string
Age int `xorm:"-"` Age int `xorm:"-"`
} }
``` ```
2.1.More mapping rules, please see [Mapping Rules](#mapping) 2.1.More mapping rules, please see [Mapping Rules](#mapping)
3.When you set up your program, you can use CreateTables to create database tables. 3.When you set up your program, you can use CreateTables to create database tables.
```Go ```Go
err := engine.CreateTables(&User{}) err := engine.CreateTables(&User{})
// or err := engine.Map(&User{}, &Article{}) // or err := engine.Map(&User{}, &Article{})
// err = engine.CreateAll() // err = engine.CreateAll()
``` ```
4.then, insert a struct to table, if success, User.Id will be set to id 4.then, insert a struct to table, if success, User.Id will be set to id
```Go ```Go
id, err := engine.Insert(&User{Name:"lunny"}) id, err := engine.Insert(&User{Name:"lunny"})
``` ```
or if you want to update records or if you want to update records
```Go ```Go
user := User{Name:"xlw"} user := User{Name:"xlw"}
rows, err := engine.Update(&user, &User{Id:1}) rows, err := engine.Update(&user, &User{Id:1})
// or rows, err := engine.Where("id = ?", 1).Update(&user) // or rows, err := engine.Where("id = ?", 1).Update(&user)
// or rows, err := engine.Id(1).Update(&user) // or rows, err := engine.Id(1).Update(&user)
``` ```
5.Fetch a single object by user 5.Fetch a single object by user
```Go ```Go
var user = User{Id:27} var user = User{Id:27}
has, err := engine.Get(&user) has, err := engine.Get(&user)
// or has, err := engine.Id(27).Get(&user) // or has, err := engine.Id(27).Get(&user)
var user = User{Name:"xlw"} var user = User{Name:"xlw"}
has, err := engine.Get(&user) has, err := engine.Get(&user)
``` ```
6.Fetch multipe objects into a slice or a map, use Find： 6.Fetch multipe objects into a slice or a map, use Find：
```Go ```Go
var everyone []Userinfo var everyone []Userinfo
err := engine.Find(&everyone) err := engine.Find(&everyone)
users := make(map[int64]Userinfo) users := make(map[int64]Userinfo)
err := engine.Find(&users) err := engine.Find(&users)
``` ```
6.1 also you can use Where, Limit 6.1 also you can use Where, Limit
```Go ```Go
var allusers []Userinfo var allusers []Userinfo
err := engine.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 err := engine.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20
``` ```
6.2 or you can use a struct query 6.2 or you can use a struct query
```Go ```Go
var tenusers []Userinfo var tenusers []Userinfo
err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0 err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0
``` ```
6.3 or In function 6.3 or In function
```Go ```Go
var tenusers []Userinfo var tenusers []Userinfo
err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5) err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5)
``` ```
6.4 The default will query all columns of a table. Use Cols function if you want to select some columns 6.4 The default will query all columns of a table. Use Cols function if you want to select some columns
```Go ```Go
var tenusers []Userinfo var tenusers []Userinfo
err := engine.Cols("id", "name").Find(&tenusers) //Find only id and name err := engine.Cols("id", "name").Find(&tenusers) //Find only id and name
``` ```
7.Delete 7.Delete
```Go ```Go
err := engine.Delete(&User{Id:1}) err := engine.Delete(&User{Id:1})
// or err := engine.Id(1).Delete(&User{}) // or err := engine.Id(1).Delete(&User{})
``` ```
8.Count 8.Count
```Go ```Go
total, err := engine.Count(&User{Name:"xlw"}) total, err := engine.Count(&User{Name:"xlw"})
``` ```
## Execute SQL ## Execute SQL
Of course, SQL execution is also provided. Of course, SQL execution is also provided.
1.if select then use Query 1.if select then use Query
```Go ```Go
sql := "select * from userinfo" sql := "select * from userinfo"
results, err := engine.Query(sql) results, err := engine.Query(sql)
``` ```
2.if insert, update or delete then use Exec 2.if insert, update or delete then use Exec
```Go ```Go
sql = "update userinfo set username=? where id=?" sql = "update userinfo set username=? where id=?"
res, err := engine.Exec(sql, "xiaolun", 1) res, err := engine.Exec(sql, "xiaolun", 1)
``` ```
## Advanced Usage
## Advanced Usage
for deep usage, you should create a session, this func will create a database connection immediatelly.Please notice, MakeSession will be deprecated last, use NewSession instead for deep usage, you should create a session, this func will create a database connection immediatelly.Please notice, MakeSession will be deprecated last, use NewSession instead
```Go ```Go
session := engine.NewSession() session := engine.NewSession()
defer session.Close() defer session.Close()
@ -214,7 +214,7 @@ defer session.Close()
``` ```
1.Fetch a single object by where 1.Fetch a single object by where
```Go ```Go
var user Userinfo var user Userinfo
session.Where("id=?", 27).Get(&user) session.Where("id=?", 27).Get(&user)
@ -227,7 +227,7 @@ session.Where("name = ? and age > ?", "john", 88).Get(&userOldJohn) // even more
``` ```
2.Fetch multiple objects 2.Fetch multiple objects
```Go ```Go
var allusers []Userinfo var allusers []Userinfo
err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20
@ -236,156 +236,156 @@ var tenusers []Userinfo
err := session.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 if omit offset the default is 0 err := session.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 if omit offset the default is 0
var everyone []Userinfo var everyone []Userinfo
err := session.Find(&everyone) err := session.Find(&everyone)
``` ```
3.Transaction 3.Transaction
```Go ```Go
// add Begin() before any action // add Begin() before any action
err := session.Begin() err := session.Begin()
user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()}
_, err = session.Insert(&user1) _, err = session.Insert(&user1)
if err != nil { if err != nil {
session.Rollback() session.Rollback()
return return
}
user2 := Userinfo{Username: "yyy"}
_, err = session.Where("id = ?", 2).Update(&user2)
if err != nil {
session.Rollback()
return
}
_, err = session.Delete(&user2)
if err != nil {
session.Rollback()
return
}
// add Commit() after all actions
err = session.Commit()
if err != nil {
return
} }
``` user2 := Userinfo{Username: "yyy"}
_, err = session.Where("id = ?", 2).Update(&user2)
4.Mixed Transaction if err != nil {
session.Rollback()
```Go return
// add Begin() before any action }
err := session.Begin()
user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} _, err = session.Delete(&user2)
_, err = session.Insert(&user1) if err != nil {
if err != nil { session.Rollback()
session.Rollback() return
return }
}
user2 := Userinfo{Username: "yyy"} // add Commit() after all actions
_, err = session.Where("id = ?", 2).Update(&user2) err = session.Commit()
if err != nil { if err != nil {
session.Rollback() return
return }
} ```
_, err = session.Exec("delete from userinfo where username = ?", user2.Username) 4.Mixed Transaction
if err != nil {
session.Rollback() ```Go
return // add Begin() before any action
} err := session.Begin()
user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()}
// add Commit() after all actions _, err = session.Insert(&user1)
err = session.Commit() if err != nil {
if err != nil { session.Rollback()
return return
} }
``` user2 := Userinfo{Username: "yyy"}
5.Derive mapping _, err = session.Where("id = ?", 2).Update(&user2)
if err != nil {
session.Rollback()
return
}
_, err = session.Exec("delete from userinfo where username = ?", user2.Username)
if err != nil {
session.Rollback()
return
}
// add Commit() after all actions
err = session.Commit()
if err != nil {
return
}
```
5.Derive mapping
Please see derive.go in examples folder. Please see derive.go in examples folder.
## Mapping Rules ## Mapping Rules
<a name="mapping" id="mapping"></a> <a name="mapping" id="mapping"></a>
1.Struct and struct's fields name should be Pascal style, and the table and column's name default is SQL style. 1.Struct and struct's fields name should be Pascal style, and the table and column's name default is SQL style.
For example: For example:
The struct's Name 'UserInfo' will turn into the table name 'user_info', the same as the keyname. If the keyname is 'UserName' will turn into the select colum 'user_name' The struct's Name 'UserInfo' will turn into the table name 'user_info', the same as the keyname. If the keyname is 'UserName' will turn into the select colum 'user_name'
2.If You want change the mapping rules, you have two methods. One is to implement your own Map struct interface according IMapper, you can find the interface in mapper.go and set it to engine.Mapper 2.If You want change the mapping rules, you have two methods. One is to implement your own Map struct interface according IMapper, you can find the interface in mapper.go and set it to engine.Mapper
Another is use field tag, field tag support the below keywords which split with space: Another is use field tag, field tag support the below keywords which split with space:
<table> <table>
<tr> <tr>
<td>name</td><td>column name, if no this name, the name is auto generated according field name and mapper rule.</td> <td>name</td><td>column name, if no this name, the name is auto generated according field name and mapper rule.</td>
</tr> </tr>
<tr> <tr>
<td>pk</td><td>the field is a primary key</td> <td>pk</td><td>the field is a primary key</td>
</tr> </tr>
<tr> <tr>
<td>more than 30 column type supported, please see [Column Type](https://github.com/lunny/xorm/blob/master/COLUMNTYPE.md)</td><td>column type</td> <td>more than 30 column type supported, please see [Column Type](https://github.com/lunny/xorm/blob/master/COLUMNTYPE.md)</td><td>column type</td>
</tr> </tr>
<tr> <tr>
<td>autoincr</td><td>auto incrment</td> <td>autoincr</td><td>auto incrment</td>
</tr> </tr>
<tr> <tr>
<td>[not ]null</td><td>if column can be null value</td> <td>[not ]null</td><td>if column can be null value</td>
</tr> </tr>
<tr> <tr>
<td>unique or unique(uniquename)</td><td>unique or union unique as uniquename</td> <td>unique or unique(uniquename)</td><td>unique or union unique as uniquename</td>
</tr> </tr>
<tr> <tr>
<td>index or index(indexname)</td><td>index or union index as indexname</td> <td>index or index(indexname)</td><td>index or union index as indexname</td>
</tr> </tr>
<tr> <tr>
<td>extends</td><td>used in anonymous struct means mapping this struct's fields to table</td> <td>extends</td><td>used in anonymous struct means mapping this struct's fields to table</td>
</tr> </tr>
<tr> <tr>
<td>-</td><td>this field is not map as a table column</td> <td>-</td><td>this field is not map as a table column</td>
</tr> </tr>
</table> </table>
For Example For Example
```Go ```Go
type Userinfo struct { type Userinfo struct {
Uid int `xorm:"id pk not null autoincr"` Uid int `xorm:"id pk not null autoincr"`
Username string `xorm:"unique"` Username string `xorm:"unique"`
Departname string Departname string
Alias string `xorm:"-"` Alias string `xorm:"-"`
Created time.Time Created time.Time
} }
``` ```
3.For customize table name, use Table() function, for example: 3.For customize table name, use Table() function, for example:
```Go ```Go
// batch create tables // batch create tables
for i := 0; i < 10; i++ { for i := 0; i < 10; i++ {
engine.Table(fmt.Sprintf("user_%v", i)).CreateTable(&Userinfo{}) engine.Table(fmt.Sprintf("user_%v", i)).CreateTable(&Userinfo{})
} }
// insert into table according id // insert into table according id
user := Userinfo{Uid: 25, Username:"sslfs"} user := Userinfo{Uid: 25, Username:"sslfs"}
engine.Table(fmt.Sprintf("user_%v", user.Uid % 10)).Insert(&user) engine.Table(fmt.Sprintf("user_%v", user.Uid % 10)).Insert(&user)
``` ```
## Documents ## Documents
Please visit [GoWalker](http://gowalker.org/github.com/lunny/xorm) Please visit [GoWalker](http://gowalker.org/github.com/lunny/xorm)
## FAQ ## FAQ
1.How the xorm tag use both with json? 1.How the xorm tag use both with json?
Use space. Use space.
```Go ```Go
type User struct { type User struct {
Name string `json:"name" xorm:"name"` Name string `json:"name" xorm:"name"`
} }
``` ```
## LICENSE ## LICENSE