Simple and Powerful ORM for Go, support mysql,postgres,tidb,sqlite3,mssql,oracle
Latest commit fa23a97 Sep 23, 2018
Permalink
Failed to load latest commit information.
docs/images remove docs submodule (#568) Apr 12, 2017
examples 缺少sqlite库 (#1083) Aug 24, 2018
migrate just return error instead. (#1046) Jul 22, 2018
.gitignore enhancement: auto-transaction (#1093) Sep 17, 2018
CONTRIBUTING.md update contributing (#780) Nov 17, 2017
LICENSE copyright: added owner Sep 7, 2015
README.md add opencollective (#926) May 4, 2018
README_CN.md update readme Sep 21, 2018
cache_lru.go fix bug on cache delete (#703) Sep 9, 2017
cache_lru_test.go fix bug on cache delete (#703) Sep 9, 2017
cache_memory_store.go add some tests for tag and cache related with #330 May 27, 2017
cache_memory_store_test.go fix bug on cache delete (#703) Sep 9, 2017
cache_test.go Add support Engine Group (#748) Oct 16, 2017
circle.yml update CI Aug 9, 2018
context.go add PingContext support for go1.8+ (#766) Oct 31, 2017
context_test.go PingContext test (#1103) Sep 23, 2018
convert.go remove some unnecessary debug log and some refactor (#791) Dec 4, 2017
dialect_mssql.go fix time issues and add some tests for time (#604) Jun 2, 2017
dialect_mysql.go fix db default charset error (#1072) Aug 25, 2018
dialect_oracle.go bug fixed for mssql dialect Apr 5, 2017
dialect_postgres.go Change pgx driver (#996) Jun 6, 2018
dialect_postgres_test.go Change pgx driver (#996) Jun 6, 2018
dialect_sqlite3.go fix bug in sqlite db name parsing (#1096) Sep 12, 2018
doc.go refactor query functions (#689) Aug 27, 2017
engine.go Add more methods for EngineInterface (#1091) Sep 7, 2018
engine_cond.go add test and remove unused warn log (#886) Apr 11, 2018
engine_group.go Add more methods for EngineInterface (#1091) Sep 7, 2018
engine_group_policy.go Add support Engine Group (#748) Oct 16, 2017
engine_table.go fix tablename bug (#887) Apr 11, 2018
engine_table_test.go add test for tablename (#885) Apr 11, 2018
error.go add more test for join find (#922) May 2, 2018
gen_reserved.sh add gen_reserved.sh Sep 22, 2014
go.mod add vgo support Mar 22, 2018
helpers.go fix id condition not used bug (#882) Apr 11, 2018
helpers_test.go move lifetime to a split file so that go1.1 is also work with this fe… Jun 8, 2017
helpler_time.go fix time issues and add some tests for time (#604) Jun 2, 2017
interface.go Add more methods for EngineInterface (#1091) Sep 7, 2018
logger.go golint fix Jan 9, 2017
pg_reserved.txt add gen_reserved.sh Sep 22, 2014
processors.go improve processors (#743) Sep 30, 2017
processors_test.go Add tests for afterinsert (#755) Oct 24, 2017
rows.go Add SetSchema for engine (#876) Apr 10, 2018
rows_test.go Add SetSchema for engine (#876) Apr 10, 2018
session.go add more test for join find (#922) May 2, 2018
session_cols.go fix cols and distinct conflicts (#927) May 4, 2018
session_cols_test.go add test and remove unused warn log (#886) Apr 11, 2018
session_cond.go hide all undocument variables on session (#660) Jul 27, 2017
session_cond_test.go Add SetSchema for engine (#876) Apr 10, 2018
session_convert.go remove some unnecessary debug log and some refactor (#791) Dec 4, 2017
session_delete.go fix update map with table name (#888) Apr 11, 2018
session_delete_test.go Add support Engine Group (#748) Oct 16, 2017
session_exist.go Add SetSchema for engine (#876) Apr 10, 2018
session_exist_test.go Add SetSchema for engine (#876) Apr 10, 2018
session_find.go fix #997 group by (#1065) Aug 9, 2018
session_find_test.go fix #997 group by (#1065) Aug 9, 2018
session_get.go Propagate errors from SQL row reading (#1079) Aug 23, 2018
session_get_test.go fix id condition not used bug (#882) Apr 11, 2018
session_insert.go performance improvement via string builder (#1036) Jul 11, 2018
session_insert_test.go add test for insert anonymous struct (#904) Apr 19, 2018
session_iterate.go add buffer Iterate support (#729) Sep 19, 2017
session_iterate_test.go add buffer Iterate support (#729) Sep 19, 2017
session_pk_test.go add unvalid pk test (#1100) Sep 17, 2018
session_query.go fix #997 group by (#1065) Aug 9, 2018
session_query_test.go Add more test for query (#932) May 8, 2018
session_raw.go Exec support builder (#1064) Aug 9, 2018
session_raw_test.go Add SetSchema for engine (#876) Apr 10, 2018
session_schema.go add more tests for Sync2 (#925) May 4, 2018
session_schema_test.go add more tests for Sync2 (#925) May 4, 2018
session_stats.go refactor query functions (#689) Aug 27, 2017
session_stats_test.go Add test for count with orderby and limit (#880) Apr 10, 2018
session_test.go tests for close and add IsClosed() method (#659) Jul 26, 2017
session_tx.go add support for mulitple transactions on one session (#1015) Jun 20, 2018
session_tx_test.go add support for mulitple transactions on one session (#1015) Jun 20, 2018
session_update.go Fix genUpdateColumns() should not ignore soft delete column when unsc… Jul 26, 2018
session_update_test.go Fix genUpdateColumns() should not ignore soft delete column when unsc… Jul 26, 2018
statement.go fix #997 group by (#1065) Aug 9, 2018
statement_test.go Fix BUG: Update statement build function should ingore ONLYFROMDB fie… Jun 23, 2018
syslogger.go some golints fixed Dec 11, 2016
tag.go Add comment support on create table [mysql only currently] (#616) Jun 14, 2017
tag_cache_test.go fix update map with table name (#888) Apr 11, 2018
tag_extends_test.go Add SetSchema for engine (#876) Apr 10, 2018
tag_id_test.go Add support Engine Group (#748) Oct 16, 2017
tag_test.go add test for <- tag (#1099) Sep 17, 2018
tag_version_test.go refactor query functions (#689) Aug 27, 2017
test_mssql.sh fix time issues and add some tests for time (#604) Jun 2, 2017
test_mssql_cache.sh fix bug on cache delete (#703) Sep 9, 2017
test_mymysql.sh add mymysql tests (#656) Jul 25, 2017
test_mymysql_cache.sh fix bug on cache delete (#703) Sep 9, 2017
test_mysql.sh add more tests (#595) May 30, 2017
test_mysql_cache.sh fix bug on cache delete (#703) Sep 9, 2017
test_postgres.sh add more tests (#595) May 30, 2017
test_postgres_cache.sh fix bug on cache delete (#703) Sep 9, 2017
test_sqlite.sh add more tests (#595) May 30, 2017
test_sqlite_cache.sh fix bug on cache delete (#703) Sep 9, 2017
time_test.go Add support Engine Group (#748) Oct 16, 2017
transaction.go enhancement: auto-transaction (#1093) Sep 17, 2018
transancation_test.go enhancement: auto-transaction (#1093) Sep 17, 2018
types.go some gofmt & golint fixed Jan 9, 2017
types_null_test.go refactor query functions (#689) Aug 27, 2017
types_test.go Add SetSchema for engine (#876) Apr 10, 2018
xorm.go Add more methods for EngineInterface (#1091) Sep 7, 2018
xorm_test.go Add SetSchema for engine (#876) Apr 10, 2018

README.md

xorm

中文

Xorm is a simple and powerful ORM for Go.

CircleCI codecov Join the chat at https://img.shields.io/discord/323460943201959939.svg

Features

  • Struct <-> Table Mapping Support

  • Chainable APIs

  • Transaction Support

  • Both ORM and raw SQL operation Support

  • Sync database schema Support

  • Query Cache speed up

  • Database Reverse support, See Xorm Tool README

  • Simple cascade loading support

  • Optimistic Locking support

  • SQL Builder support via github.com/go-xorm/builder

  • Automatical Read/Write seperatelly

  • Postgres schema support

Drivers Support

Drivers for Go's sql package which currently support database/sql includes:

Installation

go get github.com/go-xorm/xorm

Documents

Quick Start

  • Create Engine
engine, err := xorm.NewEngine(driverName, dataSourceName)
  • Define a struct and Sync2 table struct to database
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))
  • Create Engine Group
dataSourceNameSlice := []string{masterDataSourceName, slave1DataSourceName, slave2DataSourceName}
engineGroup, err := xorm.NewEngineGroup(driverName, dataSourceNameSlice)
masterEngine, err := xorm.NewEngine(driverName, masterDataSourceName)
slave1Engine, err := xorm.NewEngine(driverName, slave1DataSourceName)
slave2Engine, err := xorm.NewEngine(driverName, slave2DataSourceName)
engineGroup, err := xorm.NewEngineGroup(masterEngine, []*Engine{slave1Engine, slave2Engine})

Then all place where engine you can just use engineGroup.

  • Query runs a SQL string, the returned results is []map[string][]byte, QueryString returns []map[string]string, QueryInterface returns []map[string]interface{}.
results, err := engine.Query("select * from user")
results, err := engine.Where("a = 1").Query()

results, err := engine.QueryString("select * from user")
results, err := engine.Where("a = 1").QueryString()

results, err := engine.QueryInterface("select * from user")
results, err := engine.Where("a = 1").QueryInterface()
  • Exec runs a SQL string, it returns affected and error
affected, err := engine.Exec("update user set age = ? where name = ?", age, name)
  • Insert one or multiple records to database
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 (),(),()
  • Get query one record from database
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

var name string
has, err := engine.Where("id = ?", id).Cols("name").Get(&name)
// SELECT name FROM user WHERE id = ?

var id int64
has, err := engine.Where("name = ?", name).Cols("id").Get(&id)
has, err := engine.SQL("select id from user").Get(&id)
// SELECT id FROM user WHERE name = ?

var valuesMap = make(map[string]string)
has, err := engine.Where("id = ?", id).Get(&valuesMap)
// SELECT * FROM user WHERE id = ?

var valuesSlice = make([]interface{}, len(cols))
has, err := engine.Where("id = ?", id).Cols(cols...).Get(&valuesSlice)
// SELECT col1, col2, col3 FROM user WHERE id = ?
  • Exist check if one record exist on table
has, err := testEngine.Exist(new(RecordExist))
// SELECT * FROM record_exist LIMIT 1

has, err = testEngine.Exist(&RecordExist{
		Name: "test1",
	})
// SELECT * FROM record_exist WHERE name = ? LIMIT 1

has, err = testEngine.Where("name = ?", "test1").Exist(&RecordExist{})
// SELECT * FROM record_exist WHERE name = ? LIMIT 1

has, err = testEngine.SQL("select * from record_exist where name = ?", "test1").Exist()
// select * from record_exist where name = ?

has, err = testEngine.Table("record_exist").Exist()
// SELECT * FROM record_exist LIMIT 1

has, err = testEngine.Table("record_exist").Where("name = ?", "test1").Exist()
// SELECT * FROM record_exist WHERE name = ? LIMIT 1
  • Find query multiple records from database, also you can use join and extends
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 10 offset 0

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 10 offset 0
  • Iterate and Rows query multiple records and record by record handle, there are two methods Iterate and Rows
err := engine.Iterate(&User{Name:name}, func(idx int, bean interface{}) error {
    user := bean.(*User)
    return nil
})
// SELECT * FROM user

err := engine.BufferSize(100).Iterate(&User{Name:name}, func(idx int, bean interface{}) error {
    user := bean.(*User)
    return nil
})
// SELECT * FROM user Limit 0, 100
// SELECT * FROM user Limit 101, 100

rows, err := engine.Rows(&User{Name:name})
// SELECT * FROM user
defer rows.Close()
bean := new(Struct)
for rows.Next() {
    err = rows.Scan(bean)
}
  • Update update one or more records, default will update non-empty and non-zero fields except when you use Cols, AllCols and so on.
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("id", 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 delete one or more records, Delete MUST have condition
affected, err := engine.Where(...).Delete(&user)
// DELETE FROM user Where ...

affected, err := engine.ID(2).Delete(&user)
// DELETE FROM user Where id = ?
  • Count count records
counts, err := engine.Count(&user)
// SELECT count(*) AS total FROM user
  • Sum sum functions
agesFloat64, err := engine.Sum(&user, "age")
// SELECT sum(age) AS total FROM user

agesInt64, err := engine.SumInt(&user, "age")
// SELECT sum(age) AS total FROM user

sumFloat64Slice, err := engine.Sums(&user, "age", "score")
// SELECT sum(age), sum(score) FROM user

sumInt64Slice, err := engine.SumsInt(&user, "age", "score")
// SELECT sum(age), sum(score) FROM user
  • Query conditions builder
err := engine.Where(builder.NotIn("a", 1, 2).And(builder.In("b", "c", "d", "e"))).Find(&users)
// SELECT id, name ... FROM user WHERE a NOT IN (?, ?) AND b IN (?, ?, ?)
  • Multiple operations in one go routine, no transation here but resue session memory
session := engine.NewSession()
defer session.Close()

user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()}
if _, err := session.Insert(&user1); err != nil {
    return err
}

user2 := Userinfo{Username: "yyy"}
if _, err := session.Where("id = ?", 2).Update(&user2); err != nil {
    return err
}

if _, err := session.Exec("delete from userinfo where username = ?", user2.Username); err != nil {
    return err
}

return nil
  • Transation should on one go routine. There is transaction and resue session memory
session := engine.NewSession()
defer session.Close()

// add Begin() before any action
if err := session.Begin(); err != nil {
    // if returned then will rollback automatically
    return err
}

user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()}
if _, err := session.Insert(&user1); err != nil {
    return err
}

user2 := Userinfo{Username: "yyy"}
if _, err := session.Where("id = ?", 2).Update(&user2); err != nil {
    return err
}

if _, err := session.Exec("delete from userinfo where username = ?", user2.Username); err != nil {
    return err
}

// add Commit() after all actions
return session.Commit()

Contributing

If you want to pull request, please see CONTRIBUTING. And we also provide Xorm on Google Groups to discuss.

Credits

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Changelog

  • v0.7.0

    • Some bugs fixed
  • v0.6.6

    • Some bugs fixed
  • v0.6.5

    • Postgres schema support
    • vgo support
    • Add FindAndCount
    • Database special params support via NewEngineWithParams
    • Some bugs fixed
  • v0.6.4

    • Automatical Read/Write seperatelly
    • Query/QueryString/QueryInterface and action with Where/And
    • Get support non-struct variables
    • BufferSize on Iterate
    • fix some other bugs.

More changes ...

Cases

LICENSE

BSD License http://creativecommons.org/licenses/BSD/