github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/go-xorm/xorm/README.md (about)

     1  [中文](https://github.com/go-xorm/xorm/blob/master/README_CN.md)
     2  
     3  Xorm is a simple and powerful ORM for Go.
     4  
     5  [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/go-xorm/xorm?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
     6  
     7  [![Build Status](https://drone.io/github.com/go-xorm/tests/status.png)](https://drone.io/github.com/go-xorm/tests/latest)
     8  
     9  # Notice
    10  
    11  The last master version is not backwards compatible. You should use `engine.ShowSQL()` and `engine.Logger().SetLevel()` instead of `engine.ShowSQL = `, `engine.ShowInfo = ` and so on.
    12  
    13  # Features
    14  
    15  * Struct <-> Table Mapping Support
    16  
    17  * Chainable APIs
    18  
    19  * Transaction Support
    20  
    21  * Both ORM and raw SQL operation Support
    22  
    23  * Sync database schema Support
    24  
    25  * Query Cache speed up
    26  
    27  * Database Reverse support, See [Xorm Tool README](https://github.com/go-xorm/cmd/blob/master/README.md)
    28  
    29  * Simple cascade loading support
    30  
    31  * Optimistic Locking support
    32  
    33  * SQL Builder support via [github.com/go-xorm/builder](https://github.com/go-xorm/builder)
    34  
    35  # Drivers Support
    36  
    37  Drivers for Go's sql package which currently support database/sql includes:
    38  
    39  * Mysql: [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
    40  
    41  * MyMysql: [github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv)
    42  
    43  * Postgres: [github.com/lib/pq](https://github.com/lib/pq)
    44  
    45  * Tidb: [github.com/pingcap/tidb](https://github.com/pingcap/tidb)
    46  
    47  * SQLite: [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
    48  
    49  * MsSql: [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
    50  
    51  * MsSql: [github.com/lunny/godbc](https://github.com/lunny/godbc)
    52  
    53  * Oracle: [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8) (experiment)
    54  
    55  # Changelog
    56  
    57  * **v0.6.0**
    58      * remove support for ql
    59      * add query condition builder support via [github.com/go-xorm/builder](https://github.com/go-xorm/builder), so `Where`, `And`, `Or` 
    60  methods can use `builder.Cond` as parameter
    61      * add Sum, SumInt, SumInt64 and NotIn methods
    62      * some bugs fixed
    63  
    64  * **v0.5.0**
    65      * logging interface changed
    66      * some bugs fixed
    67  
    68  * **v0.4.5**
    69      * many bugs fixed
    70      * extends support unlimited deepth
    71      * Delete Limit support
    72  
    73  * **v0.4.4**
    74      * ql database expriment support
    75      * tidb database expriment support
    76      * sql.NullString and etc. field support
    77      * select ForUpdate support
    78      * many bugs fixed
    79  
    80  [More changes ...](https://github.com/go-xorm/manual-en-US/tree/master/chapter-16)
    81  
    82  # Installation
    83  
    84  If you have [gopm](https://github.com/gpmgo/gopm) installed,
    85  
    86  	gopm get github.com/go-xorm/xorm
    87  
    88  Or
    89  
    90  	go get github.com/go-xorm/xorm
    91  
    92  # Documents
    93  
    94  * [Manual](http://xorm.io/docs)
    95  
    96  * [GoDoc](http://godoc.org/github.com/go-xorm/xorm)
    97  
    98  * [GoWalker](http://gowalker.org/github.com/go-xorm/xorm)
    99  
   100  # Quick Start
   101  
   102  * Create Engine
   103  
   104  ```Go
   105  engine, err := xorm.NewEngine(driverName, dataSourceName)
   106  ```
   107  
   108  * Define a struct and Sync2 table struct to database
   109  
   110  ```Go
   111  type User struct {
   112      Id int64
   113      Name string
   114      Salt string
   115      Age int
   116      Passwd string `xorm:"varchar(200)"`
   117      Created time.Time `xorm:"created"`
   118      Updated time.Time `xorm:"updated"`
   119  }
   120  
   121  err := engine.Sync2(new(User))
   122  ```
   123  
   124  * Query a SQL string, the returned results is []map[string][]byte
   125  
   126  ```Go
   127  results, err := engine.Query("select * from user")
   128  ```
   129  
   130  * Execute a SQL string, the returned results
   131  
   132  ```Go
   133  affected, err := engine.Exec("update user set age = ? where name = ?", age, name)
   134  ```
   135  
   136  * Insert one or multiple records to database
   137  
   138  ```Go
   139  affected, err := engine.Insert(&user)
   140  // INSERT INTO struct () values ()
   141  affected, err := engine.Insert(&user1, &user2)
   142  // INSERT INTO struct1 () values ()
   143  // INSERT INTO struct2 () values ()
   144  affected, err := engine.Insert(&users)
   145  // INSERT INTO struct () values (),(),()
   146  affected, err := engine.Insert(&user1, &users)
   147  // INSERT INTO struct1 () values ()
   148  // INSERT INTO struct2 () values (),(),()
   149  ```
   150  
   151  * Query one record from database
   152  
   153  ```Go
   154  has, err := engine.Get(&user)
   155  // SELECT * FROM user LIMIT 1
   156  has, err := engine.Where("name = ?", name).Desc("id").Get(&user)
   157  // SELECT * FROM user WHERE name = ? ORDER BY id DESC LIMIT 1
   158  ```
   159  
   160  * Query multiple records from database, also you can use join and extends
   161  
   162  ```Go
   163  var users []User
   164  err := engine.Where("name = ?", name).And("age > 10").Limit(10, 0).Find(&users)
   165  // SELECT * FROM user WHERE name = ? AND age > 10 limit 0 offset 10
   166  
   167  type Detail struct {
   168      Id int64
   169      UserId int64 `xorm:"index"`
   170  }
   171  
   172  type UserDetail struct {
   173      User `xorm:"extends"`
   174      Detail `xorm:"extends"`
   175  }
   176  
   177  var users []UserDetail
   178  err := engine.Table("user").Select("user.*, detail.*")
   179      Join("INNER", "detail", "detail.user_id = user.id").
   180      Where("user.name = ?", name).Limit(10, 0).
   181      Find(&users)
   182  // SELECT user.*, detail.* FROM user INNER JOIN detail WHERE user.name = ? limit 0 offset 10
   183  ```
   184  
   185  * Query multiple records and record by record handle, there are two methods Iterate and Rows
   186  
   187  ```Go
   188  err := engine.Iterate(&User{Name:name}, func(idx int, bean interface{}) error {
   189      user := bean.(*User)
   190      return nil
   191  })
   192  // SELECT * FROM user
   193  
   194  rows, err := engine.Rows(&User{Name:name})
   195  // SELECT * FROM user
   196  defer rows.Close()
   197  bean := new(Struct)
   198  for rows.Next() {
   199      err = rows.Scan(bean)
   200  }
   201  ```
   202  
   203  * Update one or more records, default will update non-empty and non-zero fields except when you use Cols, AllCols and so on.
   204  
   205  ```Go
   206  affected, err := engine.Id(1).Update(&user)
   207  // UPDATE user SET ... Where id = ?
   208  
   209  affected, err := engine.Update(&user, &User{Name:name})
   210  // UPDATE user SET ... Where name = ?
   211  
   212  var ids = []int64{1, 2, 3}
   213  affected, err := engine.In("id", ids).Update(&user)
   214  // UPDATE user SET ... Where id IN (?, ?, ?)
   215  
   216  // force update indicated columns by Cols
   217  affected, err := engine.Id(1).Cols("age").Update(&User{Name:name, Age: 12})
   218  // UPDATE user SET age = ?, updated=? Where id = ?
   219  
   220  // force NOT update indicated columns by Omit
   221  affected, err := engine.Id(1).Omit("name").Update(&User{Name:name, Age: 12})
   222  // UPDATE user SET age = ?, updated=? Where id = ?
   223  
   224  affected, err := engine.Id(1).AllCols().Update(&user)
   225  // UPDATE user SET name=?,age=?,salt=?,passwd=?,updated=? Where id = ?
   226  ```
   227  
   228  * Delete one or more records, Delete MUST have condition
   229  
   230  ```Go
   231  affected, err := engine.Where(...).Delete(&user)
   232  // DELETE FROM user Where ...
   233  affected, err := engine.Id(2).Delete(&user)
   234  ```
   235  
   236  * Count records
   237  
   238  ```Go
   239  counts, err := engine.Count(&user)
   240  // SELECT count(*) AS total FROM user
   241  ```
   242  
   243  * Query conditions builder
   244  
   245  ```Go
   246  err := engine.Where(builder.NotIn("a", 1, 2).And(builder.In("b", "c", "d", "e"))).Find(&users)
   247  // SELECT id, name ... FROM user WHERE a NOT IN (?, ?) AND b IN (?, ?, ?)
   248  ```
   249  
   250  # Cases
   251  
   252  * [github.com/m3ng9i/qreader](https://github.com/m3ng9i/qreader)
   253  
   254  * [Wego](http://github.com/go-tango/wego)
   255  
   256  * [Docker.cn](https://docker.cn/)
   257  
   258  * [Gogs](http://try.gogits.org) - [github.com/gogits/gogs](http://github.com/gogits/gogs)
   259  
   260  * [Gorevel](http://gorevel.cn/) - [github.com/goofcc/gorevel](http://github.com/goofcc/gorevel)
   261  
   262  * [Gowalker](http://gowalker.org) - [github.com/Unknwon/gowalker](http://github.com/Unknwon/gowalker)
   263  
   264  * [Gobuild.io](http://gobuild.io) - [github.com/shxsun/gobuild](http://github.com/shxsun/gobuild)
   265  
   266  * [Sudo China](http://sudochina.com) - [github.com/insionng/toropress](http://github.com/insionng/toropress)
   267  
   268  * [Godaily](http://godaily.org) - [github.com/govc/godaily](http://github.com/govc/godaily)
   269  
   270  * [YouGam](http://www.yougam.com/)
   271  
   272  * [GoCMS - github.com/zzboy/GoCMS](https://github.com/zzdboy/GoCMS)
   273  
   274  * [GoBBS - gobbs.domolo.com](http://gobbs.domolo.com/)
   275  
   276  * [go-blog](http://wangcheng.me) - [github.com/easykoo/go-blog](https://github.com/easykoo/go-blog)
   277  
   278  # Discuss
   279  
   280  Please visit [Xorm on Google Groups](https://groups.google.com/forum/#!forum/xorm)
   281  
   282  # Contributing
   283  
   284  If you want to pull request, please see [CONTRIBUTING](https://github.com/go-xorm/xorm/blob/master/CONTRIBUTING.md)
   285  
   286  # LICENSE
   287  
   288   BSD License
   289   [http://creativecommons.org/licenses/BSD/](http://creativecommons.org/licenses/BSD/)