/README.md

  1Beedb
  2=====
  3
  4:exclamation: **IMPORTANT:** Beedb is being deprecated in favor of [Beego.orm](https://github.com/astaxie/beego/tree/master/orm) :exclamation:
  5
  6Beedb is an ORM for Go. It lets you map Go structs to tables in a database. It's intended to be very lightweight, doing very little beyond what you really want. For example, when fetching data, instead of re-inventing a query syntax, we just delegate your query to the underlying database, so you can write the "where" clause of your SQL statements directly. This allows you to have more flexibility while giving you a convenience layer. But beedb also has some smart defaults, for those times when complex queries aren't necessary.
  7
  8Right now, it interfaces with Mysql/SQLite/PostgreSQL/DB2/MS ADODB/ODBC/Oracle. The goal however is to add support for other databases in the future, including maybe MongoDb or NoSQL?
  9
 10Relationship-support is not implemented, for this we will recommend you to use [Beego.orm](https://github.com/astaxie/beego/tree/master/orm).
 11
 12All in all, it's not entirely ready for advanced use yet, but it's getting there.
 13
 14Drivers for Go's sql package which support database/sql includes:
 15
 16Mysql:[github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv)`[*]`
 17
 18Mysql:[github.com/Go-SQL-Driver/MySQL](https://github.com/Go-SQL-Driver/MySQL)`[*]`
 19
 20PostgreSQL:[github.com/bmizerany/pq](https://github.com/bmizerany/pq)`[*]`
 21
 22SQLite:[github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)`[*]`
 23
 24DB2: [bitbucket.org/phiggins/go-db2-cli](https://bitbucket.org/phiggins/go-db2-cli)
 25
 26MS ADODB: [github.com/mattn/go-adodb](https://github.com/mattn/go-adodb)`[*]`
 27
 28ODBC: [bitbucket.org/miquella/mgodbc](https://bitbucket.org/miquella/mgodbc)`[*]`
 29
 30Oracle: [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8)
 31
 32Drivers marked with a `[*]` are tested with Beedb
 33
 34### API Interface
 35[wiki/API-Interface](https://github.com/astaxie/beedb/wiki/API-Interface)
 36
 37### Installing Beedb
 38    go get github.com/astaxie/beedb
 39
 40### How do we use it?
 41
 42Open a database link(may be will support ConnectionPool in the future)
 43
 44```go
 45db, err := sql.Open("mymysql", "test/xiemengjun/123456")
 46if err != nil {
 47	panic(err)
 48}
 49orm := beedb.New(db)
 50```
 51
 52with PostgreSQL,
 53
 54```go
 55orm := beedb.New(db, "pg")
 56```
 57
 58Open Debug log, turn on the debug
 59
 60```go
 61beedb.OnDebug=true
 62```
 63
 64Model a struct after a table in the db
 65
 66```go
 67type Userinfo struct {
 68	Uid		int	`beedb:"PK" sql:"UID" tname:"USER_INFO"` //if the table's PrimaryKey is not "Id", use this tag
 69	Username	string `sql:"USERNAME"`
 70	Departname	string `sql:"DEPARTNAME"`
 71	Created		time.Time `sql:"CREATED"`
 72}
 73```
 74
 75###***Caution***
 76The structs Name 'UserInfo' will turn into the table name 'USER_INFO', as defined by the **tname** tag.
 77If the key 'UserName' will turn into the select colum 'USERNAME' because of the **sql** tag.
 78
 79
 80Create an object and save it
 81
 82```go
 83var saveone Userinfo
 84saveone.Username = "Test Add User"
 85saveone.Departname = "Test Add Departname"
 86saveone.Created = time.Now()
 87orm.Save(&saveone)
 88```
 89
 90Saving new and existing objects
 91
 92```go
 93saveone.Username = "Update Username"
 94saveone.Departname = "Update Departname"
 95saveone.Created = time.Now()
 96orm.Save(&saveone)  //now saveone has the primarykey value it will update
 97```
 98
 99Fetch a single object
100
101```go
102var user Userinfo
103orm.Where("uid=?", 27).Find(&user)
104
105var user2 Userinfo
106orm.Where(3).Find(&user2) // this is shorthand for the version above
107
108var user3 Userinfo
109orm.Where("name = ?", "john").Find(&user3) // more complex query
110
111var user4 Userinfo
112orm.Where("name = ? and age < ?", "john", 88).Find(&user4) // even more complex
113```
114
115Fetch multiple objects
116
117```go
118var allusers []Userinfo
119err := orm.Where("id > ?", "3").Limit(10,20).FindAll(&allusers) //Get id>3 limit 10 offset 20
120
121var tenusers []Userinfo
122err := orm.Where("id > ?", "3").Limit(10).FindAll(&tenusers) //Get id>3 limit 10  if omit offset the default is 0
123
124var everyone []Userinfo
125err := orm.FindAll(&everyone)
126```
127
128Find result as Map
129
130```go
131//Original SQL Backinfo resultsSlice []map[string][]byte
132//default PrimaryKey id
133a, _ := orm.SetTable("userinfo").SetPK("uid").Where(2).Select("uid,username").FindMap()
134```
135
136Update with Map
137
138```go
139t := make(map[string]interface{})
140var j interface{}
141j = "astaxie"
142t["username"] = j
143//update one
144orm.SetTable("userinfo").SetPK("uid").Where(2).Update(t)
145```
146
147Update batch with Map
148```go
149orm.SetTable("userinfo").Where("uid>?", 3).Update(t)
150```
151
152Insert data with Map
153
154```go
155add := make(map[string]interface{})
156j = "astaxie"
157add["username"] = j
158j = "cloud develop"
159add["departname"] = j
160j = "2012-12-02"
161add["created"] = j
162orm.SetTable("userinfo").Insert(add)
163```
164
165Insert batch with map
166
167```go
168addslice := make([]map[string]interface{})
169add:=make(map[string]interface{})
170add2:=make(map[string]interface{})
171j = "astaxie"
172add["username"] = j
173j = "cloud develop"
174add["departname"] = j
175j = "2012-12-02"
176add["created"] = j
177j = "astaxie2"
178add2["username"] = j
179j = "cloud develop2"
180add2["departname"] = j
181j = "2012-12-02"
182add2["created"] = j
183addslice =append(addslice, add, add2)
184orm.SetTable("userinfo").Insert(addslice)
185```
186
187Join Table
188
189```go
190a, _ := orm.SetTable("userinfo").Join("LEFT", "userdeatail", "userinfo.uid=userdeatail.uid").Where("userinfo.uid=?", 1).Select("userinfo.uid,userinfo.username,userdeatail.profile").FindMap()
191```
192
193Group By And Having
194
195```go
196a, _ := orm.SetTable("userinfo").GroupBy("username").Having("username='astaxie'").FindMap()
197```
198
199Nesting Models (inline)
200
201```go
202type SQLModel struct {
203	Id       int       `beedb:"PK" sql:"id"`
204	Created  time.Time `sql:"created"`
205	Modified time.Time `sql:"modified"`
206}
207type User struct {
208	SQLModel `sql:",inline"`
209	Name     string `sql:"name" tname:"fn_group"`
210	Auth     int    `sql:"auth"`
211}
212// the SQL table has the columns: id, name, auth, created, modified
213// They are marshalled and unmarshalled automatically because of the inline keyword
214```
215
216## LICENSE
217
218 BSD License
219 [http://creativecommons.org/licenses/BSD/](http://creativecommons.org/licenses/BSD/)