doc.go 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. // Copyright 2013 - 2016 The XORM Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD
  3. // license that can be found in the LICENSE file.
  4. /*
  5. Package xorm is a simple and powerful ORM for Go.
  6. Installation
  7. Make sure you have installed Go 1.5+ and then:
  8. go get github.com/go-xorm/xorm
  9. Create Engine
  10. Firstly, we should new an engine for a database
  11. engine, err := xorm.NewEngine(driverName, dataSourceName)
  12. Method NewEngine's parameters is the same as sql.Open. It depends
  13. drivers' implementation.
  14. Generally, one engine for an application is enough. You can set it as package variable.
  15. Raw Methods
  16. XORM also support raw SQL execution:
  17. 1. query a SQL string, the returned results is []map[string][]byte
  18. results, err := engine.Query("select * from user")
  19. 2. execute a SQL string, the returned results
  20. affected, err := engine.Exec("update user set .... where ...")
  21. ORM Methods
  22. There are 8 major ORM methods and many helpful methods to use to operate database.
  23. 1. Insert one or multiple records to database
  24. affected, err := engine.Insert(&struct)
  25. // INSERT INTO struct () values ()
  26. affected, err := engine.Insert(&struct1, &struct2)
  27. // INSERT INTO struct1 () values ()
  28. // INSERT INTO struct2 () values ()
  29. affected, err := engine.Insert(&sliceOfStruct)
  30. // INSERT INTO struct () values (),(),()
  31. affected, err := engine.Insert(&struct1, &sliceOfStruct2)
  32. // INSERT INTO struct1 () values ()
  33. // INSERT INTO struct2 () values (),(),()
  34. 2. Query one record or one variable from database
  35. has, err := engine.Get(&user)
  36. // SELECT * FROM user LIMIT 1
  37. var id int64
  38. has, err := engine.Table("user").Where("name = ?", name).Get(&id)
  39. // SELECT id FROM user WHERE name = ? LIMIT 1
  40. 3. Query multiple records from database
  41. var sliceOfStructs []Struct
  42. err := engine.Find(&sliceOfStructs)
  43. // SELECT * FROM user
  44. var mapOfStructs = make(map[int64]Struct)
  45. err := engine.Find(&mapOfStructs)
  46. // SELECT * FROM user
  47. var int64s []int64
  48. err := engine.Table("user").Cols("id").Find(&int64s)
  49. // SELECT id FROM user
  50. 4. Query multiple records and record by record handle, there two methods, one is Iterate,
  51. another is Rows
  52. err := engine.Iterate(...)
  53. // SELECT * FROM user
  54. rows, err := engine.Rows(...)
  55. // SELECT * FROM user
  56. defer rows.Close()
  57. bean := new(Struct)
  58. for rows.Next() {
  59. err = rows.Scan(bean)
  60. }
  61. 5. Update one or more records
  62. affected, err := engine.Id(...).Update(&user)
  63. // UPDATE user SET ...
  64. 6. Delete one or more records, Delete MUST has condition
  65. affected, err := engine.Where(...).Delete(&user)
  66. // DELETE FROM user Where ...
  67. 7. Count records
  68. counts, err := engine.Count(&user)
  69. // SELECT count(*) AS total FROM user
  70. counts, err := engine.SQL("select count(*) FROM user").Count()
  71. // select count(*) FROM user
  72. 8. Sum records
  73. sumFloat64, err := engine.Sum(&user, "id")
  74. // SELECT sum(id) from user
  75. sumFloat64s, err := engine.Sums(&user, "id1", "id2")
  76. // SELECT sum(id1), sum(id2) from user
  77. sumInt64s, err := engine.SumsInt(&user, "id1", "id2")
  78. // SELECT sum(id1), sum(id2) from user
  79. Conditions
  80. The above 8 methods could use with condition methods chainable.
  81. Attention: the above 8 methods should be the last chainable method.
  82. 1. ID, In
  83. engine.ID(1).Get(&user) // for single primary key
  84. // SELECT * FROM user WHERE id = 1
  85. engine.ID(core.PK{1, 2}).Get(&user) // for composite primary keys
  86. // SELECT * FROM user WHERE id1 = 1 AND id2 = 2
  87. engine.In("id", 1, 2, 3).Find(&users)
  88. // SELECT * FROM user WHERE id IN (1, 2, 3)
  89. engine.In("id", []int{1, 2, 3}).Find(&users)
  90. // SELECT * FROM user WHERE id IN (1, 2, 3)
  91. 2. Where, And, Or
  92. engine.Where().And().Or().Find()
  93. // SELECT * FROM user WHERE (.. AND ..) OR ...
  94. 3. OrderBy, Asc, Desc
  95. engine.Asc().Desc().Find()
  96. // SELECT * FROM user ORDER BY .. ASC, .. DESC
  97. engine.OrderBy().Find()
  98. // SELECT * FROM user ORDER BY ..
  99. 4. Limit, Top
  100. engine.Limit().Find()
  101. // SELECT * FROM user LIMIT .. OFFSET ..
  102. engine.Top(5).Find()
  103. // SELECT TOP 5 * FROM user // for mssql
  104. // SELECT * FROM user LIMIT .. OFFSET 0 //for other databases
  105. 5. SQL, let you custom SQL
  106. var users []User
  107. engine.SQL("select * from user").Find(&users)
  108. 6. Cols, Omit, Distinct
  109. var users []*User
  110. engine.Cols("col1, col2").Find(&users)
  111. // SELECT col1, col2 FROM user
  112. engine.Cols("col1", "col2").Where().Update(user)
  113. // UPDATE user set col1 = ?, col2 = ? Where ...
  114. engine.Omit("col1").Find(&users)
  115. // SELECT col2, col3 FROM user
  116. engine.Omit("col1").Insert(&user)
  117. // INSERT INTO table (non-col1) VALUES ()
  118. engine.Distinct("col1").Find(&users)
  119. // SELECT DISTINCT col1 FROM user
  120. 7. Join, GroupBy, Having
  121. engine.GroupBy("name").Having("name='xlw'").Find(&users)
  122. //SELECT * FROM user GROUP BY name HAVING name='xlw'
  123. engine.Join("LEFT", "userdetail", "user.id=userdetail.id").Find(&users)
  124. //SELECT * FROM user LEFT JOIN userdetail ON user.id=userdetail.id
  125. More usage, please visit http://xorm.io/docs
  126. */
  127. package xorm