Simple and Powerful ORM for Go, support mysql,postgres,tidb,sqlite3,sqlite,mssql,oracle,cockroach https://xorm.io
Go to file
appleboy d19b4e6a94
All checks were successful
test mariadb / test mariadb (pull_request) Successful in 13m37s
test mssql / test mssql (pull_request) Successful in 13m37s
test mssql / test mssql with collation (pull_request) Successful in 14m17s
test cockroach / test cockroach (pull_request) Successful in 14m47s
test mysql / test mysql (pull_request) Successful in 12m49s
test mysql8 / test mysql8 (pull_request) Successful in 13m23s
test postgres / test postgres (pull_request) Successful in 13m14s
test sqlite / unit test & test sqlite (pull_request) Successful in 13m24s
test tidb / test tidb (pull_request) Successful in 11m27s
refactor: ensure non-null values in migration table creation
- Change the migration table creation to not allow null values for the column

Signed-off-by: appleboy <appleboy.tw@gmail.com>
2024-03-17 10:39:23 +08:00
.gitea/workflows Update ci (#2432) 2024-03-15 14:11:47 +00:00
caches Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
contexts Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
convert Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
core Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
dialects Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
internal Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
log Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
migrate refactor: ensure non-null values in migration table creation 2024-03-17 10:39:23 +08:00
names Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
schemas Fix bug when join with alias start with `a` (#2343) 2023-10-25 11:01:46 +00:00
tags Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
tests Support not drop index when sync (#2429) 2024-03-15 03:13:09 +00:00
.changelog.yml Add changelog for v1.0.0 (#1614) 2020-03-22 06:28:25 +00:00
.gitignore Add ignore 2023-07-26 18:46:36 +08:00
.golangci.yml Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
CHANGELOG.md add changelog for 1.3.2 2022-09-03 15:14:19 +08:00
CONTRIBUTING.md replace GitHub links: xorm has been moved to gitea.com (#2126) 2022-03-31 14:26:05 +08:00
doc.go update go version to v1.17 in .drone.yml (#2219) 2023-02-12 11:16:53 +08:00
engine_group_policy.go Fix lint errors (#1631) 2020-03-26 04:41:02 +00:00
engine_group.go Fix master/slave bug (#2004) 2021-07-22 11:07:53 +08:00
engine.go Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
error.go Improve codes (#1630) 2020-03-26 13:24:11 +00:00
go.mod Use github.com/microsoft/go-mssqldb instead of old mssqldb repository (#2386) (#2390) 2024-01-16 07:56:04 +00:00
go.sum Use github.com/microsoft/go-mssqldb instead of old mssqldb repository (#2386) (#2390) 2024-01-16 07:56:04 +00:00
interface.go Add Sync options to ignore constrains and indices (#2320) 2023-08-09 03:28:52 +00:00
LICENSE copyright: added owner 2015-09-06 23:43:06 -04:00
Makefile Fix mssql get indexes bug when collation is not default with collation test for mssql (#2387) (#2389) 2023-12-31 14:39:33 +00:00
processors.go Move processor function into one file (#1637) 2020-03-28 02:23:37 +00:00
README_CN.md Use github.com/microsoft/go-mssqldb instead of old mssqldb repository (#2386) (#2390) 2024-01-16 07:56:04 +00:00
README.md Use github.com/microsoft/go-mssqldb instead of old mssqldb repository (#2386) (#2390) 2024-01-16 07:56:04 +00:00
rows.go Fix a serious bug when using rows and reuse the session (#2309) 2023-07-25 08:37:12 +00:00
scan.go some improvement (#2136) 2022-04-22 10:16:35 +08:00
session_cols.go Move statement as a sub package (#1564) 2020-02-28 12:29:08 +00:00
session_cond.go Move statement as a sub package (#1564) 2020-02-28 12:29:08 +00:00
session_delete.go move sql geneartion for update to statement (#2300) 2023-07-21 16:25:58 +00:00
session_exist.go refactor insert condition generation (#1998) 2021-07-20 13:46:24 +08:00
session_find.go Performance Optimization: reduce slice2Bean calling times of strings.ToLower and map creation times (#2255) 2023-07-12 09:53:19 +00:00
session_get.go Fix typo in session_get.go (#2398) 2024-01-22 08:06:32 +00:00
session_insert.go Fix the issue of incorrect insertion of data in non UTC time zone zero for numeric types (#2413) 2024-02-25 16:16:56 +00:00
session_iterate.go Fix #2393 (#2395) 2024-01-15 14:06:34 +00:00
session_raw.go Filter support passing context (#2200) (#2270) 2023-05-31 01:43:24 +00:00
session_schema.go Add missing index hint parameter (#2378) 2023-12-19 04:54:04 +00:00
session_stats.go Return error if count returned no row (#2298) 2023-07-20 14:48:29 +00:00
session_tx.go Add README and fix some lints (#2079) 2021-12-14 09:00:35 +08:00
session_update.go Refactor write update (#2310) 2023-07-25 10:49:55 +00:00
session.go Performance Optimization: reduce slice2Bean calling times of strings.ToLower and map creation times (#2255) 2023-07-12 09:53:19 +00:00
sync.go Support not drop index when sync (#2429) 2024-03-15 03:13:09 +00:00

xorm

中文

Xorm is a simple and powerful ORM for Go.

Build Status Join the chat at https://img.shields.io/discord/323460943201959939.svg

Notice

v1.0.0 has some break changes from v0.8.2.

  • Removed some non gonic function name Id, Sql, please use ID, SQL instead.
  • Removed the dependent from xorm.io/core and moved the codes to xorm.io/xorm/core, xorm.io/xorm/names, xorm.io/xorm/schemas and others.
  • Renamed some interface names. i.e. core.IMapper -> names.Mapper, core.ILogger -> log.Logger.

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 via xorm.io/reverse
  • Simple cascade loading support
  • Optimistic Locking support
  • SQL Builder support via xorm.io/builder
  • Automatical Read/Write seperatelly
  • Postgres schema support
  • Context Cache support
  • Support log/SQLLog context

Drivers Support

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

Installation

go get xorm.io/xorm

Documents

Quick Start

  • Create Engine

Firstly, we should new an engine for a database.

engine, err := xorm.NewEngine(driverName, dataSourceName)
  • Define a struct and Sync 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.Sync(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 (),(),()

affected, err := engine.Table("user").Insert(map[string]interface{}{
    "name": "lunny",
    "age": 18,
})
// INSERT INTO user (name, age) values (?,?)

affected, err := engine.Table("user").Insert([]map[string]interface{}{
    {
        "name": "lunny",
        "age": 18,
    },
    {
        "name": "lunny2",
        "age": 19,
    },
})
// INSERT INTO user (name, age) 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.Table(&user).Where("id = ?", id).Cols("name").Get(&name)
// SELECT name FROM user WHERE id = ?

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

var id int64
var name string
has, err := engine.Table(&user).Cols("id", "name").Get(&id, &name)
// SELECT id, name FROM user LIMIT 1

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

var valuesSlice = make([]interface{}, len(cols))
has, err := engine.Table(&user).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

You can use rows which is similiar with sql.Rows

rows, err := engine.Rows(&User{Name:name})
// SELECT * FROM user
defer rows.Close()
bean := new(Struct)
for rows.Next() {
    err = rows.Scan(bean)
}

or

rows, err := engine.Cols("name", "age").Rows(&User{Name:name})
// SELECT * FROM user
defer rows.Close()
for rows.Next() {
    var name string
    var age int
    err = rows.Scan(&name, &age)
}
  • 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 = ?

affected, err := engine.Table("user").Where(...).Delete()
// DELETE FROM user WHERE ...
  • Count count records
counts, err := engine.Count(&user)
// SELECT count(*) AS total FROM user
  • FindAndCount combines function Find with Count which is usually used in query by page
var users []User
counts, err := engine.FindAndCount(&users)
  • 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 transaction 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
  • Transaction should be 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()
  • Or you can use Transaction to replace above codes.
res, err := engine.Transaction(func(session *xorm.Session) (interface{}, error) {
    user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.Now()}
    if _, err := session.Insert(&user1); err != nil {
        return nil, err
    }

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

    if _, err := session.Exec("delete from userinfo where username = ?", user2.Username); err != nil {
        return nil, err
    }
    return nil, nil
})
  • Context Cache, if enabled, current query result will be cached on session and be used by next same statement on the same session.
	sess := engine.NewSession()
	defer sess.Close()

	var context = xorm.NewMemoryContextCache()

	var c2 ContextGetStruct
	has, err := sess.ID(1).ContextCache(context).Get(&c2)
	assert.NoError(t, err)
	assert.True(t, has)
	assert.EqualValues(t, 1, c2.Id)
	assert.EqualValues(t, "1", c2.Name)
	sql, args := sess.LastSQL()
	assert.True(t, len(sql) > 0)
	assert.True(t, len(args) > 0)

	var c3 ContextGetStruct
	has, err = sess.ID(1).ContextCache(context).Get(&c3)
	assert.NoError(t, err)
	assert.True(t, has)
	assert.EqualValues(t, 1, c3.Id)
	assert.EqualValues(t, "1", c3.Name)
	sql, args = sess.LastSQL()
	assert.True(t, len(sql) == 0)
	assert.True(t, len(args) == 0)

Contributing

If you want to pull request, please see CONTRIBUTING. And you can also go to Xorm on discourse 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

You can find all the changelog here

Cases

LICENSE

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