From 08f3a5f69bbde3696370096a5154720a1bc372a4 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Sat, 11 May 2013 21:27:36 +0800 Subject: [PATCH] imporved README --- README.md | 293 +++++++++++++++++++++++++++---------------------- README_CN.md | 304 +++++++++++++++++++++++++++++---------------------- 2 files changed, 338 insertions(+), 259 deletions(-) diff --git a/README.md b/README.md index 6b5b90c6..fb88eb75 100644 --- a/README.md +++ b/README.md @@ -39,190 +39,223 @@ Drivers for Go's sql package which currently support database/sql includes: 1.Create a database engine just like sql.Open, commonly you just need create once. ```Go -import (_ "github.com/Go-SQL-Driver/MySQL" - "github.com/lunny/xorm") +import ( + _ "github.com/Go-SQL-Driver/MySQL" + "github.com/lunny/xorm" +) engine := xorm.Create("mysql", "root:123@/test?charset=utf8") ``` or ```Go - import (_ "github.com/mattn/go-sqlite3" - "github.com/lunny/xorm") - engine = xorm.Create("sqlite3", "./test.db") +import ( + _ "github.com/mattn/go-sqlite3" + "github.com/lunny/xorm" +) +engine = xorm.Create("sqlite3", "./test.db") ``` 2.Define a struct - - - type User struct { - Id int - Name string - Age int `xorm:"-"` - } - + +```Go +type User struct { + Id int + Name string + Age int `xorm:"-"` +} +``` 3.When you set up your program, you can use CreateTables to create database tables. +```Go +err := engine.CreateTables(&User{}) +// or err := engine.Map(&User{}, &Article{}) +// err = engine.CreateAll() +``` - err := engine.CreateTables(&User{}) - // or err := engine.Map(&User{}, &Article{}) - // err = engine.CreateAll() - -4.then, insert an struct to table - - id, err := engine.Insert(&User{Name:"lunny"}) +4.then, insert an struct to table +```Go +id, err := engine.Insert(&User{Name:"lunny"}) +``` or if you want to update records - - user := User{Name:"xlw"} - rows, err := engine.Update(&user, &User{Id:1}) - // or rows, err := engine.Where("id = ?", 1).Update(&user) - // or rows, err := engine.Id(1).Update(&user) - + +```Go +user := User{Name:"xlw"} +rows, err := engine.Update(&user, &User{Id:1}) +// or rows, err := engine.Where("id = ?", 1).Update(&user) +// or rows, err := engine.Id(1).Update(&user) +``` 5.Fetch a single object by user + +```Go +var user = User{Id:27} +err := engine.Get(&user) +// or err := engine.Id(27).Get(&user) - var user = User{Id:27} - err := engine.Get(&user) - // or err := engine.Id(27).Get(&user) - - var user = User{Name:"xlw"} - err := engine.Get(&user) +var user = User{Name:"xlw"} +err := engine.Get(&user) +``` 6.Fetch multipe objects, use Find： - var everyone []Userinfo - err := engine.Find(&everyone) +```Go +var everyone []Userinfo +err := engine.Find(&everyone) +``` 6.1 also you can use Where, Limit - var allusers []Userinfo - err := engine.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 +```Go +var allusers []Userinfo +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 - - var tenusers []Userinfo - err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0 + +```Go +var tenusers []Userinfo +err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0 +``` 6.3 or In function - var tenusers []Userinfo - err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5) +```Go +var tenusers []Userinfo +err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5) +``` 7.Delete - err := engine.Delete(&User{Id:1}) - // or err := engine.Id(1).Delete(&User{}) +```Go +err := engine.Delete(&User{Id:1}) +// or err := engine.Id(1).Delete(&User{}) +``` 8.Count - total, err := engine.Count(&User{Name:"xlw"}) +```Go +total, err := engine.Count(&User{Name:"xlw"}) +``` ##Execute SQL Of course, SQL execution is also provided. 1.if select then use Query - sql := "select * from userinfo" - results, err := engine.Query(sql) +```Go +sql := "select * from userinfo" +results, err := engine.Query(sql) +``` 2.if insert, update or delete then use Exec - sql = "update userinfo set username=? where id=?" - res, err := engine.Exec(sql, "xiaolun", 1) +```Go +sql = "update userinfo set username=? where id=?" +res, err := engine.Exec(sql, "xiaolun", 1) +``` ##Deep Use for deep usage, you should create a session, this func will create a database connection immediatelly - - session, err := engine.MakeSession() - defer session.Close() - if err != nil { - return - } - + +```Go +session, err := engine.MakeSession() +defer session.Close() +if err != nil { + return +} +``` 1.Fetch a single object by where + +```Go +var user Userinfo +session.Where("id=?", 27).Get(&user) - var user Userinfo - session.Where("id=?", 27).Get(&user) - - var user2 Userinfo - session.Where("name = ?", "john").Get(&user3) // more complex query - - var user3 Userinfo - session.Where("name = ? and age < ?", "john", 88).Get(&user4) // even more complex +var user2 Userinfo +session.Where("name = ?", "john").Get(&user3) // more complex query +var user3 Userinfo +session.Where("name = ? and age < ?", "john", 88).Get(&user4) // even more complex +``` 2.Fetch multiple objects + +```Go +var allusers []Userinfo +err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 - var allusers []Userinfo - err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 +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 - 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 - - var everyone []Userinfo - err := session.Find(&everyone) +var everyone []Userinfo +err := session.Find(&everyone) +``` 3.Transaction - // add Begin() before any action - session.Begin() - user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} - _, err = session.Insert(&user1) - if err != nil { - session.Rollback() - return - } - user2 := Userinfo{Username: "yyy"} - _, err = session.Where("id = ?", 2).Update(&user2) - if err != nil { - session.Rollback() - return - } +```Go +// add Begin() before any action +session.Begin() +user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} +_, err = session.Insert(&user1) +if err != nil { + session.Rollback() + 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 - } +_, err = session.Delete(&user2) +if err != nil { + session.Rollback() + return +} - // add Commit() after all actions - err = session.Commit() - if err != nil { - return - } +// add Commit() after all actions +err = session.Commit() +if err != nil { + return +} +``` 4.Mixed Transaction - // add Begin() before any action - session.Begin() - user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} - _, err = session.Insert(&user1) - if err != nil { - session.Rollback() - return - } - user2 := Userinfo{Username: "yyy"} - _, err = session.Where("id = ?", 2).Update(&user2) - if err != nil { - session.Rollback() - return - } +```Go +// add Begin() before any action +session.Begin() +user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} +_, err = session.Insert(&user1) +if err != nil { + session.Rollback() + return +} +user2 := Userinfo{Username: "yyy"} +_, 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 - } +_, 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 - } +// add Commit() after all actions +err = session.Commit() +if err != nil { + return +} +``` ##Mapping Rules 1.Struct and struct's fields name should be Pascal style, and the table and column's name default is SQL style. @@ -261,13 +294,15 @@ Another is use field tag, field tag support the below keywords which split with For Example - type Userinfo struct { - Uid int `xorm:"id pk not null autoincr"` - Username string - Departname string - Alias string `xorm:"-"` - Created time.Time - } +```Go +type Userinfo struct { + Uid int `xorm:"id pk not null autoincr"` + Username string + Departname string + Alias string `xorm:"-"` + Created time.Time +} +``` ##Documents Please visit [GoWalker](http://gowalker.org/github.com/lunny/xorm) @@ -276,9 +311,11 @@ Please visit [GoWalker](http://gowalker.org/github.com/lunny/xorm) Use space. - type User struct { - Name string `json:"name" xorm:"name"` - } +```Go +type User struct { + Name string `json:"name" xorm:"name"` +} +``` ## LICENSE diff --git a/README_CN.md b/README_CN.md index 75777248..a0b8ea00 100644 --- a/README_CN.md +++ b/README_CN.md @@ -37,185 +37,222 @@ xorm是一个Go语言的ORM库. 通过它可以使数据库操作非常简便。 1.创建数据库引擎，这个函数的参数和sql.Open相同，但不会立即创建连接 (例如: mysql) - import (_ "github.com/Go-SQL-Driver/MySQL" - "github.com/lunny/xorm") - engine := xorm.Create("mysql", "root:123@/test?charset=utf8") +```Go +import ( + _ "github.com/Go-SQL-Driver/MySQL" + "github.com/lunny/xorm" + ) +engine := xorm.Create("mysql", "root:123@/test?charset=utf8") +``` or - import (_ "github.com/mattn/go-sqlite3" - "github.com/lunny/xorm") - engine = xorm.Create("sqlite3", "./test.db") - +```Go +import ( + _ "github.com/mattn/go-sqlite3" + "github.com/lunny/xorm" + ) +engine = xorm.Create("sqlite3", "./test.db") +``` 2.定义一个结构体 - - type User struct { - Id int - Name string - Age int `xorm:"-"` - } +```Go +type User struct { + Id int + Name string + Age int `xorm:"-"` +} +``` 3.在程序初始化时，可能会需要创建表 - - err := engine.CreateTables(&User{}) - + +```Go +err := engine.CreateTables(&User{}) +``` 4.然后，可以将一个结构体作为一条记录插入到表中。 - - id, err := engine.Insert(&User{Name:"lunny"}) - + +```Go +id, err := engine.Insert(&User{Name:"lunny"}) +``` 或者执行更新操作： - - user := User{Name:"xlw"} - rows, err := engine.Update(&user, &User{Id:1}) - // rows, err := engine.Where("id = ?", 1).Update(&user) - // or rows, err := engine.Id(1).Update(&user) - + +```Go +user := User{Name:"xlw"} +rows, err := engine.Update(&user, &User{Id:1}) +// rows, err := engine.Where("id = ?", 1).Update(&user) +// or rows, err := engine.Id(1).Update(&user) +``` 5.获取单个对象，可以用Get方法： + +```Go +var user = User{Id:27} +err := engine.Get(&user) +// or err := engine.Id(27).Get(&user) - var user = User{Id:27} - err := engine.Get(&user) - // or err := engine.Id(27).Get(&user) - - var user = User{Name:"xlw"} - err := engine.Get(&user) +var user = User{Name:"xlw"} +err := engine.Get(&user) +``` 6.获取多个对象，可以用Find方法： - var everyone []Userinfo - err := engine.Find(&everyone) +```Go +var everyone []Userinfo +err := engine.Find(&everyone) +``` 6.1 你也可以使用Where和Limit方法设定条件和查询数量 - var allusers []Userinfo - err := engine.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 +```Go +var allusers []Userinfo +err := engine.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 +``` 6.2 用一个结构体作为查询条件也是允许的 - - var tenusers []Userinfo - err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0 + +```Go +var tenusers []Userinfo +err := engine.Limit(10).Find(&tenusers, &Userinfo{Name:"xlw"}) //Get All Name="xlw" limit 10 offset 0 +``` 6.3 也可以调用In函数 - var tenusers []Userinfo - err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5) +```Go +var tenusers []Userinfo +err := engine.In("id", 1, 3, 5).Find(&tenusers) //Get All id in (1, 3, 5) +``` 7.Delete方法 - err := engine.Delete(&User{Id:1}) - // or err := engine.Id(1).Delete(&User{}) +```Go +err := engine.Delete(&User{Id:1}) +// or err := engine.Id(1).Delete(&User{}) +``` 8.Count方法 - total, err := engine.Count(&User{Name:"xlw"}) +```Go +total, err := engine.Count(&User{Name:"xlw"}) +``` ##直接执行SQL语句 当然，如果你想直接使用SQL语句进行操作，也是允许的。 如果执行Select，请用Query() - sql := "select * from userinfo" - results, err := engine.Query(sql) +```Go +sql := "select * from userinfo" +results, err := engine.Query(sql) +``` 如果执行Insert， Update， Delete 等操作，请用Exec() - - sql = "update userinfo set username=? where id=?" - res, err := engine.Exec(sql, "xiaolun", 1) + +```Go +sql = "update userinfo set username=? where id=?" +res, err := engine.Exec(sql, "xiaolun", 1) +``` ##高级用法 更高级的用法，我们必须要使用session对象，session对象在创建时会立刻创建一个数据库连接。 - - session, err := engine.MakeSession() - defer session.Close() - if err != nil { - return - } - + +```Go +session, err := engine.MakeSession() +defer session.Close() +if err != nil { + return +} +``` 1.session对象同样也可以查询 + +```Go +var user Userinfo +session.Where("id=?", 27).Get(&user) - var user Userinfo - session.Where("id=?", 27).Get(&user) - - var user2 Userinfo - session.Where("name = ?", "john").Get(&user3) // more complex query - - var user3 Userinfo - session.Where("name = ? and age < ?", "john", 88).Get(&user4) // even more complex +var user2 Userinfo +session.Where("name = ?", "john").Get(&user3) // more complex query +var user3 Userinfo +session.Where("name = ? and age < ?", "john", 88).Get(&user4) // even more complex +``` 2.获取多个对象 + +```Go +var allusers []Userinfo +err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 - var allusers []Userinfo - err := session.Where("id > ?", "3").Limit(10,20).Find(&allusers) //Get id>3 limit 10 offset 20 +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 - 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 - - var everyone []Userinfo - err := session.Find(&everyone) +var everyone []Userinfo +err := session.Find(&everyone) +``` 3.事务处理 - // add Begin() before any action - session.Begin() - user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} - _, err = session.Insert(&user1) - if err != nil { - session.Rollback() - return - } - user2 := Userinfo{Username: "yyy"} - _, err = session.Where("id = ?", 2).Update(&user2) - if err != nil { - session.Rollback() - return - } +```Go +// add Begin() before any action +session.Begin() +user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} +_, err = session.Insert(&user1) +if err != nil { + session.Rollback() + 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 - } +_, err = session.Delete(&user2) +if err != nil { + session.Rollback() + return +} - // add Commit() after all actions - err = session.Commit() - if err != nil { - return - } +// add Commit() after all actions +err = session.Commit() +if err != nil { + return +} +``` -4.混合型事务，这个事务中，既有直接的SQL语句，又有其它方法： +4.混合型事务，这个事务中，既有直接的SQL语句，又有ORM方法： - // add Begin() before any action - session.Begin() - user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} - _, err = session.Insert(&user1) - if err != nil { - session.Rollback() - return - } - user2 := Userinfo{Username: "yyy"} - _, err = session.Where("id = ?", 2).Update(&user2) - if err != nil { - session.Rollback() - return - } +```Go +// add Begin() before any action +session.Begin() +user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()} +_, err = session.Insert(&user1) +if err != nil { + session.Rollback() + return +} +user2 := Userinfo{Username: "yyy"} +_, 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 - } +_, 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 - } +// add Commit() after all actions +err = session.Commit() +if err != nil { + return +} +``` ##映射规则 1.Struct 和 Struct 的field名字应该为Pascal式命名，默认的映射规则将转换成用下划线连接的命名规则，这个映射是自动进行的，当然，你可以通过修改Engine的成员Mapper来改变它。 @@ -254,13 +291,15 @@ UserInfo中的成员UserName将会自动对应名为user_name的字段。 例如： - type Userinfo struct { - Uid int `xorm:"id pk not null autoincr"` - Username string - Departname string - Alias string `xorm:"-"` - Created time.Time - } +```Go +type Userinfo struct { + Uid int `xorm:"id pk not null autoincr"` + Username string + Departname string + Alias string `xorm:"-"` + Created time.Time +} +``` ##文档 请访问 [GoWalker](http://gowalker.org/github.com/lunny/xorm) 查看详细文档 @@ -270,14 +309,17 @@ UserInfo中的成员UserName将会自动对应名为user_name的字段。 答案：使用空格分开 - type User struct { - Name string `json:"name" xorm:"name"` - } +```Go +type User struct { + Name string `json:"name" xorm:"name"` +} +``` + 2.问：xorm是否带有连接池 答案：database/sql默认就有连接池，因此xorm本身没有内建连接池，在使用过程中会自动调用database/sql的实现。 ## LICENSE - BSD License - [http://creativecommons.org/licenses/BSD/](http://creativecommons.org/licenses/BSD/) +BSD License +[http://creativecommons.org/licenses/BSD/](http://creativecommons.org/licenses/BSD/)