diff --git a/README.md b/README.md index b89f7666..7d237d60 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Xorm is a simple and powerful ORM for Go. * Struct <-> Table Mapping Support * Chainable APIs - + * Transaction Support * Both ORM and raw SQL operation Support @@ -72,7 +72,7 @@ Drivers for Go's sql package which currently support database/sql includes: # Installation -If you have [gopm](https://github.com/gpmgo/gopm) installed, +If you have [gopm](https://github.com/gpmgo/gopm) installed, gopm get github.com/go-xorm/xorm @@ -88,6 +88,148 @@ Or * [GoWalker](http://gowalker.org/github.com/go-xorm/xorm) +# Quick Start + +## Create Engine + +```Go +engine, err := xorm.NewEngine(driverName, dataSourceName) +``` + +## Define a struct and Sync2 table struct to database + +```Go +type User struct { + Id int64 + Name string + Salt string + Age int + Passwd string `xorm:"varchar(200)"` + Created time.Time `xorm:"created"` + Updated time.Time `xorm:"updated"` +} + +err := engine.Sync2(new(User)) +``` + +## Query a SQL string, the returned results is []map[string][]byte + +```Go +results, err := engine.Query("select * from user") +``` + +## Execute a SQL string, the returned results + +```Go +affected, err := engine.Exec("update user set age = ? where name = ?", age, name) +``` + +## Insert one or multipe records to database + +```Go +affected, err := engine.Insert(&user) +// INSERT INTO struct () values () +affected, err := engine.Insert(&user1, &user2) +// INSERT INTO struct1 () values () +// INSERT INTO struct2 () values () +affected, err := engine.Insert(&users) +// INSERT INTO struct () values (),(),() +affected, err := engine.Insert(&user1, &users) +// INSERT INTO struct1 () values () +// INSERT INTO struct2 () values (),(),() +``` + +## Query one record from database + +```Go +has, err := engine.Get(&user) +// SELECT * FROM user LIMIT 1 +has, err := engine.Where("name = ?", name).Desc("id").Get(&user) +// SELECT * FROM user WHERE name = ? ORDER BY id DESC LIMIT 1 +``` + +## Query multiple records from database, also you can use join and extends + +```Go + var users []User + err := engine.Where("name = ?", name).And("age > 10").Limit(10, 0).Find(&users) + // SELECT * FROM user WHERE name = ? AND age > 10 limit 0 offset 10 + + type Detail struct { + Id int64 + UserId int64 `xorm:"index"` + } + + type UserDetail struct { + User `xorm:"extends"` + Detail `xorm:"extends"` + } + + var users []UserDetail + err := engine.Table("user").Select("user.*, detail.*") + Join("INNER", "detail", "detail.user_id = user.id"). + Where("user.name = ?", name).Limit(10, 0). + Find(&users) + // SELECT user.*, detail.* FROM user INNER JOIN detail WHERE user.name = ? limit 0 offset 10 +``` + +## Query multiple records and record by record handle, there two methods Iterate and Rows + +```Go +err := engine.Iterate(&User{Name:name}, func(idx int, bean interface{}) error { + user := bean.(*User) + return nil +}) +// SELECT * FROM user + +rows, err := engine.Rows(&User{Name:name}) +// SELECT * FROM user +defer rows.Close() +bean := new(Struct) +for rows.Next() { + err = rows.Scan(bean) +} +``` + +## Update one or more records, default will update non-empty and non-zero fields except to use Cols, AllCols and etc. + +```Go +affected, err := engine.Id(1).Update(&user) +// UPDATE user SET ... Where id = ? + +affected, err := engine.Update(&user, &User{Name:name}) +// UPDATE user SET ... Where name = ? + +var ids = []int64{1, 2, 3} +affected, err := engine.In(ids).Update(&user) +// UPDATE user SET ... Where id IN (?, ?, ?) + +// force update indicated columns by Cols +affected, err := engine.Id(1).Cols("age").Update(&User{Name:name, Age: 12}) +// UPDATE user SET age = ?, updated=? Where id = ? + +// force NOT update indicated columns by Omit +affected, err := engine.Id(1).Omit("name").Update(&User{Name:name, Age: 12}) +// UPDATE user SET age = ?, updated=? Where id = ? + +affected, err := engine.Id(1).AllCols().Update(&user) +// UPDATE user SET name=?,age=?,salt=?,passwd=?,updated=? Where id = ? +``` + +## Delete one or more records, Delete MUST has conditon + +```Go +affected, err := engine.Where(...).Delete(&user) +// DELETE FROM user Where ... +``` + +## Count records + +```Go +counts, err := engine.Count(&user) +// SELECT count(*) AS total FROM user +``` + # Cases * [github.com/m3ng9i/qreader](https://github.com/m3ng9i/qreader) diff --git a/README_CN.md b/README_CN.md index d3954382..df2b75b8 100644 --- a/README_CN.md +++ b/README_CN.md @@ -20,7 +20,7 @@ xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作 * 支持使用Id, In, Where, Limit, Join, Having, Table, Sql, Cols等函数和结构体等方式作为条件 -* 支持级联加载Struct +* 支持级联加载Struct * 支持缓存 @@ -58,7 +58,7 @@ xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作 * sql.NullString支持 * ForUpdate 支持 * bug修正 - + * **v0.4.3** * Json 字段类型支持 * oracle实验性支持 @@ -68,10 +68,10 @@ xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作 ## 安装 -推荐使用 [gopm](https://github.com/gpmgo/gopm) 进行安装: +推荐使用 [gopm](https://github.com/gpmgo/gopm) 进行安装: gopm get github.com/go-xorm/xorm - + 或者您也可以使用go工具进行安装: go get github.com/go-xorm/xorm @@ -84,8 +84,149 @@ xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作 * [Godoc代码文档](http://godoc.org/github.com/go-xorm/xorm) +# 快速开始 -## 案例 +## 第一步创建引擎,driverName, dataSourceName和database/sql接口相同 + +```Go +engine, err := xorm.NewEngine(driverName, dataSourceName) +``` + +## 定义一个和表同步的结构体,并且自动同步结构体到数据库 + +```Go +type User struct { + Id int64 + Name string + Salt string + Age int + Passwd string `xorm:"varchar(200)"` + Created time.Time `xorm:"created"` + Updated time.Time `xorm:"updated"` +} + +err := engine.Sync2(new(User)) +``` + +## 最原始的也支持SQL语句查询,返回的结果类型为 []map[string][]byte + +```Go +results, err := engine.Query("select * from user") +``` + +## 执行一个SQL语句 + +```Go +affected, err := engine.Exec("update user set age = ? where name = ?", age, name) +``` + +## 插入一条或者多条记录 + +```Go +affected, err := engine.Insert(&user) +// INSERT INTO struct () values () +affected, err := engine.Insert(&user1, &user2) +// INSERT INTO struct1 () values () +// INSERT INTO struct2 () values () +affected, err := engine.Insert(&users) +// INSERT INTO struct () values (),(),() +affected, err := engine.Insert(&user1, &users) +// INSERT INTO struct1 () values () +// INSERT INTO struct2 () values (),(),() +``` + +## 查询单条记录 + +```Go +has, err := engine.Get(&user) +// SELECT * FROM user LIMIT 1 +has, err := engine.Where("name = ?", name).Desc("id").Get(&user) +// SELECT * FROM user WHERE name = ? ORDER BY id DESC LIMIT 1 +``` + +## 查询多条记录,当然可以使用Join和extends来组合使用 + +```Go + var users []User + err := engine.Where("name = ?", name).And("age > 10").Limit(10, 0).Find(&users) + // SELECT * FROM user WHERE name = ? AND age > 10 limit 0 offset 10 + + type Detail struct { + Id int64 + UserId int64 `xorm:"index"` + } + + type UserDetail struct { + User `xorm:"extends"` + Detail `xorm:"extends"` + } + + var users []UserDetail + err := engine.Table("user").Select("user.*, detail.*") + Join("INNER", "detail", "detail.user_id = user.id"). + Where("user.name = ?", name).Limit(10, 0). + Find(&users) + // SELECT user.*, detail.* FROM user INNER JOIN detail WHERE user.name = ? limit 0 offset 10 +``` + +## 根据条件遍历数据库,可以有两种方式: Iterate and Rows + +```Go +err := engine.Iterate(&User{Name:name}, func(idx int, bean interface{}) error { + user := bean.(*User) + return nil +}) +// SELECT * FROM user + +rows, err := engine.Rows(&User{Name:name}) +// SELECT * FROM user +defer rows.Close() +bean := new(Struct) +for rows.Next() { + err = rows.Scan(bean) +} +``` + +## 更新数据,除非使用Cols,AllCols函数指明,默认只更新非空和非0的字段 + +```Go +affected, err := engine.Id(1).Update(&user) +// UPDATE user SET ... Where id = ? + +affected, err := engine.Update(&user, &User{Name:name}) +// UPDATE user SET ... Where name = ? + +var ids = []int64{1, 2, 3} +affected, err := engine.In(ids).Update(&user) +// UPDATE user SET ... Where id IN (?, ?, ?) + +// force update indicated columns by Cols +affected, err := engine.Id(1).Cols("age").Update(&User{Name:name, Age: 12}) +// UPDATE user SET age = ?, updated=? Where id = ? + +// force NOT update indicated columns by Omit +affected, err := engine.Id(1).Omit("name").Update(&User{Name:name, Age: 12}) +// UPDATE user SET age = ?, updated=? Where id = ? + +affected, err := engine.Id(1).AllCols().Update(&user) +// UPDATE user SET name=?,age=?,salt=?,passwd=?,updated=? Where id = ? +``` + +## 删除记录,需要注意,删除必须至少有一个条件,否则会报错。要清空数据库可以用EmptyTable + +```Go +affected, err := engine.Where(...).Delete(&user) +// DELETE FROM user Where ... +``` + +## 获取记录条数 + +```Go +counts, err := engine.Count(&user) +// SELECT count(*) AS total FROM user +``` + +# 案例 * [github.com/m3ng9i/qreader](https://github.com/m3ng9i/qreader) diff --git a/VERSION b/VERSION index 348ae384..041712a5 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -xorm v0.4.4.1225 +xorm v0.4.4.1230