Table of Contents 1. Introduction 2. 建 Orm 引擎 3. 定 表 体 i. 名称映射 ii. 前 映射, 后 映射和 存映射 iii. 使用 Table 和 Tag 改 名称映射 iv. Column 属性定 v. Go 与字段 型 表 4. 表 操作 i. 取数据 信息 ii. 表操作 iii. 建索引和唯一索引 iv. 同步数据 v. 出 入 SQL 脚本 5. 插入数据 i. 建 Created 6. 和 数据 i. 条件方法 ii. 开关方法 iii. Get 方法 iv. Find 方法 v. Iterate 方法 vi. Count 方法 vii. Rows 方法 7. 更新数据 i. Version ii. 更新 Updated 8. 除数据 i. 除 Deleted 9. 行 SQL 10. 行 SQL 命令 11. 事 理 12. 存 13. 事件 14. xorm 工具 15. 常 16. 案例 17. 更新日志
xorm xorm 是一个 而强大的 Go 言 ORM. 通 它可以使数据 操作非常 便 xorm 的目 并不是 你完全不去学 SQL, 我 SQL 并不会 ORM 所替代, 但是 ORM 将可以解决 大部分的 SQL 需求 xorm 支持 种 格的混用 特性 支持 Struct 和数据 表之 的灵活映射, 并支持自 同步表 事 支持 支持原始 SQL 句和 ORM 操作的混合 行 使用 写来 化 用 支持使用 Id, In, Where, Limit, Join, Having, Table, Sql, Cols 等函数和 体等方式作 条件 支持 加 Struct 支持 LRU 存 ( 支持 memory, memcache, leveldb, redis 存 Store) 和 Redis 存 支持反, 即根据数据 自 生成 xorm 的 体 支持事件 支持 created, updated, deleted 和 version 版本 ( 即 ) 支持 xorm 当前支持的 和数据 如下 : Mysql: github.com/go-sql-driver/mysql MyMysql: github.com/ziutek/mymysql/godrv SQLite: github.com/mattn/go-sqlite3 Postgres: github.com/lib/pq MsSql: github.com/denisenkom/go-mssqldb MsSql: github.com/lunny/godbc 安装 推荐使用 gopm 行安装 : gopm get github.com/go-xorm/xorm 或者您也可以使用 go 工具 行安装 : go get github.com/go-xorm/xorm
文档 操作指南 GoWalker 代 文档 Godoc 代 文档 加入 QQ 群 :280360085 行 献 如果您也想 Xorm 献您的力量, 看 CONTRIBUTING LICENSE BSD License http://creativecommons.org/licenses/bsd/
建 Orm 引擎 在 xorm 里面, 可以同 存在多个 Orm 引擎, 一个 Orm 引擎称 Engine Engine 通 用 xorm.newengine 生成, 如 : import ( _ "github.com/go-sql-driver/mysql" "github.com/go-xorm/xorm" ) var engine *xorm.engine func main() { var err error engine, err = xorm.newengine("mysql", "root:123@/test?charset=utf8") } or import ( _ "github.com/mattn/go-sqlite3" "github.com/go-xorm/xorm" ) var engine *xorm.engine func main() { var err error engine, err = xorm.newengine("sqlite3", "./test.db") } 一般情况下如果只操作一个数据, 只需要 建一个 Engine 即可 Engine 是 GoRutine 安全的 于有大量数据并且需要分区的 用, 也可以根据 来 建多个 Engine, 比如 : var err error for i:=0;i<5;i++ { engines[i], err = xorm.newengine("sqlite3", fmt.sprintf("./test%d.db", i)) } engine 可以通 engine.close 来手 关, 但是一般情况下可以不用关, 在程序退出 会自 关 NewEngine 入的参数和 sql.open 入的参数完全相同, 因此, 在使用某个 前, 看此 中关于 入参数的 明文 档 以下 各个 的 接符 的文档 接 : sqlite3 mysql dsn mymysql postgres 在 engine 建完成后可以 行一些 置, 如 : 1., 警告以及 等 示 置, 默 如下均 false engine.showsql = true, 会在控制台打印出生成的 SQL 句 ; engine.showdebug = true, 会在控制台打印 信息 ; engine.showerror = true, 会在控制台打印 信息 ; engine.showwarn = true, 会在控制台打印警告信息 ;
2. 如果希望将信息不 打印到控制台, 而是保存 文件, 那么可以通 似如下的代, NewSimpleLogger(w io.writer) 接 收一个 io.writer 接口来将数据写入到 的 施中 f, err := os.create("sql.log") if err!= nil { println(err.error()) return } engine.logger = xorm.newsimplelogger(f) 3.engine 内部支持 接池接口和 的函数 如果需要 置 接池的空 数大小, 可以使用 engine.setmaxidleconns() 来 如果需要 置最大打开 接数, 可以使用 engine.setmaxopenconns() 来
2. 定 表 体 xorm 支持将一个 struct 映射 数据 中 的一 表 映射 如下 :
名称映射 名称映射 主要 体名称到表名和 体 field 到表字段的名称映射 由 xorm.imapper 接口的 者来管理,xorm 内 置了 种 IMapper : SnakeMapper 和 SameMapper SnakeMapper 支持 struct 峰式命名, 表 下划 命名之 的 ;SameMapper 支持 体名称和 的表名称以及 体 field 名称与 的表字段名称相同的命名 当前 SnakeMapper 默, 如果需要改, 在 engine 建完成后使用 engine.setmapper(samemapper{}) 同 需要注意的是 : 如果你使用了 的命名 映射方案, 也可以自己 一个 IMapper 表名称和字段名称的映射 默 是相同的, 当然也可以 置 不同, 如 : engine.settablemapper(samemapper{}) engine.setcolumnmapper(snakemapper{}) When a struct auto mapping to a database's table, the below table describes how they change to each other: go type's kind value method xorm type implemented Conversion Conversion.ToDB / Conversion.FromDB Text int, int8, int16, int32, uint, uint8, uint16, uint32 int64, uint64 float32 float64 Int BigInt Float Double complex64, complex128 json.marshal / json.unmarshal Varchar(64) []uint8 Blob array, slice, map except []uint8 json.marshal / json.unmarshal Text bool 1 or 0 Bool string time.time Varchar(255) DateTime cascade struct primary key field value BigInt struct json.marshal / json.unmarshal Text Others Text
前 映射, 后 映射和 存映射 通 engine.newprefixmapper(snakemapper{}, "prefix") 可以 建一个在 SnakeMapper 的基 上在命名中添加 一的前, 当然也可以把 SnakeMapper{} 成 SameMapper 或者你自定 的 Mapper 通 engine.newsufffixmapper(snakemapper{}, "suffix") 可以 建一个在 SnakeMapper 的基 上在命名中添加 一的后, 当然也可以把 SnakeMapper 成 SameMapper 或者你自定 的 Mapper 通 engine.newcachemapper(snakemapper{}) 可以 建一个 合了其它的映射, 起到在内存中 存曾 映射 的命 名映射 例如, 如果希望所有的表名都在 体自 命名的基 上加一个前 而字段名不加前, 可以在 engine 建完成后 行以 下 句 : tbmapper := engine.newprefixmapper(snakemapper{}, "prefix") engine.settablemapper(tbmapper) 行之后, 体 type User struct 默 的表名就 成了 prefix_user 了, 而默 是 user
使用 Table 和 Tag 改 名称映射 如果所有的命名都是按照 IMapper 的映射来操作的, 那当然是最理想的 但是如果碰到某个表名或者某个字段名跟映射 不匹配, 我 就需要 的机制来改 如果 体 有 TableName() string 的成 方法, 那么此方法的返回 即是 体 的数据 表名 通 engine.table() 方法可以改 struct 的数据 表的名称, 通 sturct 中 field 的 Tag 中使用 xorm:"'column_name'" 可以使 field 的 Column 名称 指定名称 里使用 个 引号将 Column 名称括起来是 了防止名称冲突, 因 我 在 Tag 中 可以 个 Column 行更多的定 如果名称不冲突的情况, 引号也可以不使用 到此名称映射的所有方法都 出了, 一共三种方式, 那么 三种是有 先 序的 表名的 先 序如下 : engine.table() 指定的 表名 先 最高 TableName() string 其次 Mapper 自 映射的表名 先 最后字段名的 先 序如下 : 体 tag 指定的字段名 先 高 Mapper 自 映射的表名 先 低
Column 属性定 我 在 field 的 Tag 中 Column 的一些属性 行定, 定 的方法基本和我 写 SQL 定 表 似, 比如 : type User struct { Id int64 Name string `xorm:"varchar(25) not null unique 'usr_name'"` } 于不同的数据 系, 数据 型其 是有些差异的 因此 xorm 中 数据 型有自己的定, 基本的原 是尽量兼容各种数 据 的字段 型, 具体的字段 关系可以 看字段 型 表 于使用者, 一般只要使用自己熟悉的数据 字段定 即 可 具体的 Tag 如下, Tag 中的关 字均不区分大小写, 但字段名根据不同的数据 是区分大小写 : name pk 当前支持 30 多种字段 型, 情参 字段 型 autoincr [not ]null 或 notnull unique 或 unique(uniquename) index 或 index(indexname) extends 当前 field 的字段的名称, 可, 如不写, 自 根据 field 名字和 命名, 如与其它关 字冲突, 使用 引号括起来 是否是 Primary Key, 如果在一个 struct 中有多个字段都使用了此, 多个字段 成了复合主, 主 当前支持 int32,int,int64,uint32,uint,uint64,string 7 种 Go 的数据 型, 复合主 支持 7 种 Go 的数据 型的 合 字段 型 是否是自增 是否可以 空 是否是唯一, 如不加括号 字段不允 重复 ; 如加上括号, 括号中 合唯一索引的名字, 此 如果有 外一个或多个字段和本 unique 的 uniquename 相同, 些 uniquename 相同的字段 成 合唯一索引 是否是索引, 如不加括号 字段自身 索引, 如加上括号, 括号中 合索引的名字, 此 如果有 外一个或多个字段和本 index 的 indexname 相同, 些 indexname 相同的字段 成 合索引 用于一个匿名 体之上, 表示此匿名 体的成 也映射到数据 中 - 个 Field 将不 行字段映射 -> 个 Field 将只写入到数据 而不从数据 取 <- 个 Field 将只从数据 取, 而不写入到数据 created updated 个 Field 将在 Insert 自 当前 个 Field 将在 Insert 或 Update 自 当前 version 个 Field 将会在 insert 默 1, 每次更新自 加 1 default 0 置默, 跟的内容如果是 Varchar 等需要加上 引号 外有如下几条自 映射的 : 1. 如果 field 名称 Id 而且 型 int64 并且没有定 tag, 会被 xorm 主, 并且 有自增属性 如果想用 Id 以外的 名字或非 int64 型做 主 名, 必 在 的 Tag 上加上 xorm:"pk" 来定 主, 加上 xorm:"autoincr" 作 自增 里需 要注意的是, 有些数据 并不允 非主 的自增属性 2.string 型默 映射 varchar(255), 如果需要不同的定, 可以在 tag 中自定 3. 支持 type MyString string 等自定 的 field, 支持 Slice, Map 等 field 成, 些成 默 存 Text 型, 并且默 将使 用 Json 格式来序列化和反序列化 也支持数据 字段 型 Blob 型, 如果是 Blob 型, 先使用 Json 格式序列化再 成 []byte 格式 当然 []byte 或者 []uint8 默 Blob 型并且都以二 制方式存 具体参 Go 与字段 型 表 4. 了 Conversion 接口的 型或者 体, 将根据接口的 方式在 型和数据 之 行相互, 个接口
的 先 是最高的 type Conversion interface { FromDB([]byte) error ToDB() ([]byte, error) } 5. 如果一个 体包含一个 Conversion 的接口 型, 那么在 取数据, 必 要 先 置一个 此接口的 struct 或者 struct 的指 此 可以在此 struct 中 BeforeSet(name string, cell xorm.cell) 方法来 行 先 Conversion 例子 参 testconversion xorm mysql sqlite3 postgres remark BIT BIT INTEGER BIT TINYINT TINYINT INTEGER SMALLINT SMALLINT SMALLINT INTEGER SMALLINT MEDIUMINT MEDIUMINT INTEGER INTEGER INT INT INTEGER INTEGER INTEGER INTEGER INTEGER INTEGER BIGINT BIGINT INTEGER BIGINT CHAR CHAR TEXT CHAR VARCHAR VARCHAR TEXT VARCHAR TINYTEXT TINYTEXT TEXT TEXT TEXT TEXT TEXT TEXT MEDIUMTEXT MEDIUMTEXT TEXT TEXT LONGTEXT LONGTEXT TEXT TEXT BINARY BINARY BLOB BYTEA VARBINARY VARBINARY BLOB BYTEA DATE DATE NUMERIC DATE DATETIME DATETIME NUMERIC TIMESTAMP TIME TIME NUMERIC TIME TIMESTAMP TIMESTAMP NUMERIC TIMESTAMP TIMESTAMPZ TEXT TEXT TIMESTAMP with zone timestamp with zone info REAL REAL REAL REAL FLOAT FLOAT REAL REAL DOUBLE DOUBLE REAL DOUBLE PRECISION DECIMAL DECIMAL NUMERIC DECIMAL NUMERIC NUMERIC NUMERIC NUMERIC TINYBLOB TINYBLOB BLOB BYTEA BLOB BLOB BLOB BYTEA MEDIUMBLOB MEDIUMBLOB BLOB BYTEA
LONGBLOB LONGBLOB BLOB BYTEA BYTEA BLOB BLOB BYTEA BOOL TINYINT INTEGER BOOLEAN SERIAL INT INTEGER SERIAL auto increment BIGSERIAL BIGINT INTEGER BIGSERIAL auto increment
Go 与字段 型 表 如果不使用 tag 来定 field 的数据 字段 型, 那么系 会自 出一个默 的字段 型, 表如下 : When a struct auto mapping to a database's table, the below table describes how they change to each other: go type's kind value method xorm type implemented Conversion Conversion.ToDB / Conversion.FromDB Text int, int8, int16, int32, uint, uint8, uint16, uint32 int64, uint64 float32 float64 Int BigInt Float Double complex64, complex128 json.marshal / json.unmarshal Varchar(64) []uint8 Blob array, slice, map except []uint8 json.marshal / json.unmarshal Text bool 1 or 0 Bool string time.time Varchar(255) DateTime cascade struct primary key field value BigInt struct json.marshal / json.unmarshal Text Others Text
表 操作 xorm 提供了一些 取和修改表 的方法, 通 些方法可以 同步数据, 出数据, 入数据 如果您只是需要一个工具, 可以直接使用 go install github.com/go-xorm/cmd/xorm 来安装 xorm 命令
取数据 信息 DBMetas() xorm 支持 取表 信息, 通 用 engine.dbmetas() 可以 取到数据 中所有的表, 字段, 索引的信息 TableInfo() 根据 入的 体指 及其 的 Tag, 提取出模型 的表 信息 里不是数据 当前的表 信息, 而是我 通 struct 建模 希望数据 的表的 信息
表操作 CreateTables() 建表使用 engine.createtables(), 参数 一个或多个空的 Struct 的指 同 可用的方法有 Charset() 和 StoreEngine(), 如果 的数据 支持, 个方法可以在 建表 指定表的字符 和使用的引擎 Charset() 和 StoreEngine() 当前 支持 Mysql 数据 IsTableEmpty() 判断表是否 空, 参数和 CreateTables 相同 IsTableExist() 判断表是否存在 DropTables() 除表使用 engine.droptables(), 参数 一个或多个空的 Struct 的指 或者表的名字 如果 string 入, 只 除 的表, 如果 入的 Struct, 除表的同 会 除 的索引
建索引和唯一索引 CreateIndexes 根据 struct 中的 tag 来 建索引 CreateUniques 根据 struct 中的 tag 来 建唯一索引
同步数据 同步能 部分智能的根据 体的 表 的, 并自 同步 目前有 个 : Sync 自 和 建表, 个 是根据表的名字 自 和新增表中的字段, 个 是根据字段名 自 和 建索引和唯一索引, 个 是根据索引的一个或多个字段名, 而不根据索引名称 用方法如下 : err := engine.sync(new(user)) Sync2 Sync 行了改, 目前推荐使用 Sync2 自 和 建表, 个 是根据表的名字自 和新增表中的字段, 个 是根据字段名, 同 表中多余的字段 出警告信息自, 建, 和 除索引和唯一索引, 个 是根据索引的一个或多个字段名, 而不根据索引名称自 varchar 字段 型到 text 字段 型, 自 警告其它 型不一致的情况 自 警告字段的默, 是否 空信息在模型和数据 之 不匹配的情况 以上 些警告信息需要将 engine.showwarn 置 true 用方法和 Sync 一 : err := engine.sync2(new(user))
Dump 数据 和数据 如果需要在程序中 Dump 数据 的 和数据可以 用 engine.dumpall(w io.writer) 和 engine.dumpallfile(fpath string) DumpAll 方法接收一个 io.writer 接口来保存 Dump 出的数据 和数据的 SQL 句, 个方法 出的 SQL 句并不能通用 只 当前 engine 所 的数据 支持的 SQL Import 行数据 SQL 脚本 如果你需要将保存在文件或者其它存 施中的 SQL 脚本 行, 那么可以 用 engine.import(w io.writer) 和 engine.importfile(fpath string)
插入数据 插入数据使用 Insert 方法,Insert 方法的参数可以是一个或多个 Struct 的指, 一个或多个 Struct 的 Slice 的指 如果 入的是 Slice 并且当数据 支持批量插入,Insert 会使用批量插入的方式 行插入 插入一条数据, 此 可以用 Insert 或者 InsertOne user := new(user) user.name = "myname" affected, err := engine.insert(user) // INSERT INTO user (name) values (?) 在插入 条数据成功后, 如果 体有自增字段, 自增字段会被自 数据 中的 id fmt.println(user.id) 插入同一个表的多条数据, 此 如果数据 支持批量插入, 那么会 行批量插入, 但是 每条 就无法被自 予 id 如果数据 不支持批量插入, 那么就会一条一条插入 users := make([]user, 0) users[0].name = "name0"... affected, err := engine.insert(&users) 使用指 Slice 插入多条, 同上 users := make([]*user, 0) users[0] = new(user) users[0].name = "name0"... affected, err := engine.insert(&users) 插入多条 并且不使用批量插入, 此 生成多条插入 句, 每条 均会自 予 Id users := make([]*user, 0) users[0] = new(user) users[0].name = "name0"... affected, err := engine.insert(users...) 插入不同表的一条 user := new(user) user.name = "myname" question := new(question) question.content = "whywhywhwy?" affected, err := engine.insert(user, question) 插入不同表的多条
users := make([]user, 0) users[0].name = "name0"... questions := make([]question, 0) questions[0].content = "whywhywhwy?" affected, err := engine.insert(&users, &questions) 插入不同表的一条或多条 user := new(user) user.name = "myname"... questions := make([]question, 0) questions[0].content = "whywhywhwy?" affected, err := engine.insert(user, &questions) 里需要注意以下几点 : 里 然支持同 插入, 但 些插入并没有事 关系 因此有可能在中 插入出 后, 后面的插入将不会 批量插入会自 生成 Insert into table values (),(),() 的 句, 因此各个数据 SQL 句有 度限制, 因此 的 句有一个最大的 数, 根据 算在 150 条左右 大于 150 条后, 生成的 sql 句将太 可能 致 行失 因此在插入大量数据, 目前需要自行分割成每 150 条插入一次
建 Created Created 可以 您在数据插入到数据 自 将 的字段 置 当前, 需要在 xorm 中使用 created, 如下所示 行, 的字段必 time.time 型 type User struct { Id int64 Name string CreatedAt time.time `xorm:"created"` } 在 Insert() 或 InsertOne() 方法被 用,created 的字段将会被自 更新 当前, 如下所示 : var user User engine.insert(&user) // INSERT user (created...) VALUES (?...)
和 数据 所有的 条件不区分 用 序, 但必 在 用 Get,Find,Count, Iterate, Rows 几个函数之前 用 同 需要注意的一 点是, 在 用的参数中, 如果采用默 的 SnakeMapper 所有的字符字段名均 映射后的数据 的字段名, 而不是 field 的名 字
条件方法 和 主要使用 Get, Find, Count, Rows, Iterate 几个方法 在 行 可以使用多个方法来形成 条件, 条件 函数如下 : Id(interface{}) 入一个 PK 字段的, 作 条件, 如 engine.id(1).get(&user) // SELECT * FROM user Where id = 1 如果是复合主, 可以 engine.id(core.pk{1, "name"}).get(&user) // SELECT * FROM user Where id =1 AND name= 'name' 入的 个参数按照 struct 中 pk 字段出 的 序 Where(string, interface{}) 和 SQL 中 Where 句中的条件基本相同, 作 条件 And(string, interface{}) 和 Where 函数中的条件基本相同, 作 条件 Or(string, interface{}) 和 Where 函数中的条件基本相同, 作 条件 Sql(string, interface{}) 行指定的 Sql 句, 并把 果映射到 体 Asc( string) 指定字段名正序排序 Desc( string) 指定字段名逆序排序 OrderBy(string) 按照指定的 序 行排序 In(string, interface{}) 某字段在一些 中, 里需要注意必 是 []interface{} 才可以展开, 由于 Go 言的限制,[]int64 等 不可以直接展开, 而是通 一个 slice 示例代 如下 : engine.in("cloumn", 1, 2, 3).Find() engine.in("column", []int{1, 2, 3}).Find() Cols( string) 只 或更新某些指定的字段, 默 是 所有映射的字段或者根据 Update 的第一个参数来判断更新的 字段 例如 : engine.cols("age", "name").find(&users) // SELECT age, name FROM user engine.cols("age", "name").update(&user) // UPDATE user SET age=? AND name=? AllCols() 或更新所有字段, 一般与 Update 配合使用, 因 默 Update 只更新非 0, 非 "", 非 bool 的字段 engine.allcols().id(1).update(&user) // UPDATE user SET name =?, age =?, gender =? WHERE id = 1 MustCols( string) 某些字段必 更新, 一般与 Update 配合使用 Omit(...string) 和 cols 相反, 此函数指定排除某些指定的字段 注意 : 此方法和 Cols 方法不可同 使用 ```Go engine.omit("age", "gender").update(&user) // UPDATE user SET name =? AND department =?
engine.omit("age, gender").insert(&user) // INSERT INTO user (name) values (?) // 的 age 和 gender 会 默 engine.omit("age", "gender").find(&users) // SELECT name FROM user // 只 select 除 age 和 gender 字段的其它字段 * Distinct( string) 按照参数中指定的字段 果 ```Go engine.distinct("age", "department").find(&users) // SELECT DISTINCT age, department FROM user 注意 : 当开 了 存, 此方法的 用将在当前 中禁用 存 因 存系 当前依 Id, 而此 无法 得 Id Table(nameOrStructPtr interface{}) 入表名称或者 体指, 如果 入的是 体指, 按照 IMapper 的 提取 出表名 Limit(int, int) 限制 取的数目, 第一个参数 条数, 第二个参数表示开始位置, 如果不 0 Top(int) 相当于 Limit(int, 0) Join(string,string,string) 第一个参数 接 型, 当前支持 INNER, LEFT OUTER, CROSS 中的一个, 第二个参数 表名, 第三个参数 接条件 type UserGroup struct { User `xorm:"extends"` Group `xorm:"extends"` } usergroup := make([]usergroup, 0) engine.table(&user{}).join("inner", "group", "group.id = user.group_id").find(&usergroup) GroupBy(string) Groupby 的参数字符串 Having(string) Having 的参数字符串
开关方法 NoAutoTime() 如果此方法 行, 此次生成的 句中 Created 和 Updated 字段将不自 当前 NoCache() 如果此方法 行, 此次生成的 句 在非 存模式下 行 UseBool(...string) 当从一个 struct 来生成 条件或更新字段,xorm 会判断 struct 的 field 是否 0,"",nil, 如果 以上 不当做 条件或者更新内容 因 bool 型只有 true 和 false 种, 因此默 所有 bool 型不会作 条件或者更新字段 如果可以使用此方法, 如果默 不 参数, 所有的 bool 字段都将会被使用, 如果参数不 空, 参数中指定的 字段名, 些字段 的 bool 将被使用 NoCascade() 是否自 关 field 中的数据, 如果 struct 的 field 也是一个 struct 并且映射 某个 Id, 可以在 自 用 Get 方法 出 的数据
Get 方法 条数据使用 Get 方法, 在 用 Get 方法 需要 入一个 体的指, 同 体中的非空 field 自 成 的条 件和前面的方法条件 合在一起 如 : 1) 根据 Id 来 得 条数据 : user := new(user) has, err := engine.id(id).get(user) // 复合主 的 取方法 // has, errr := engine.id(xorm.pk{1,2}).get(user) 2) 根据 Where 来 得 条数据 : user := new(user) has, err := engine.where("name=?", "xlw").get(user) 3) 根据 user 体中已有的非空数据来 得 条数据 : user := &User{Id:1} has, err := engine.get(user) 或者其它条件 user := &User{Name:"xlw"} has, err := engine.get(user) 返回的 果 个参数, 一个 has 条 是否存在, 第二个参数 err 是否有 不管 err 是否 nil,has 都有可能 true 或者 false
Find 方法 多条数据使用 Find 方法,Find 方法的第一个参数 slice 的指 或 Map 指, 即 后返回的 果, 第二个参数可, 的条件 struct 的指 1) 入 Slice 用于返回数据 everyone := make([]userinfo, 0) err := engine.find(&everyone) peveryone := make([]*userinfo, 0) err := engine.find(&peveryone) 2) 入 Map 用 返回数据,map 必 map[int64]userinfo 的形式,map 的 key id, 因此 于复合主 无法使用 种方式 users := make(map[int64]userinfo) err := engine.find(&users) pusers := make(map[int64]*userinfo) err := engine.find(&pusers) 3) 也可以加入各种条件 users := make([]userinfo, 0) err := engine.where("age >? or name =?", 30, "xlw").limit(20, 10).Find(&users)
Iterate 方法 Iterate 方法提供逐条 行 到的 的方法, 他所能使用的条件和 Find 方法完全相同 err := engine.where("age >? or name=?)", 30, "xlw").iterate(new(userinfo), func(i int, bean interface{})error{ user := bean.(*userinfo) //do somthing use i and user })
Count 方法 数据使用 Count 方法,Count 方法的参数 struct 的指 并且成 条件 user := new(user) total, err := engine.where("id >?", 1).Count(user)
Rows 方法 Rows 方法和 Iterate 方法 似, 提供逐条 行 到的 的方法, 不 Rows 更加灵活好用 user := new(user) rows, err := engine.where("id >?", 1).Rows(user) if err!= nil { } defer rows.close() for rows.next() { err = rows.scan(user) //... }
更新数据 更新数据使用 Update 方法,Update 方法的第一个参数 需要更新的内容, 可以 一个 体指 或者一个 Map[string]interface{} 型 当 入的 体指, 只有非空和 0 的 field 才会被作 更新的字段 当 入的 Map 型,key 数据 Column 的名字,value 要更新的内容 user := new(user) user.name = "myname" affected, err := engine.id(id).update(user) 里需要注意,Update 会自 从 user 体中提取非 0 和非 nil 得 作 需要更新的内容, 因此, 如果需要更新一个 0, 此种方法将无法, 因此有 种 : 1. 通 添加 Cols 函数指定需要更新 体中的 些, 未指定的将不更新, 指定了的即使 0 也会更新 affected, err := engine.id(id).cols("age").update(&user) 2. 通 入 map[string]interface{} 来 行更新, 但 需要 外指定更新到 个表, 因 通 map 是无法自 更新 个表的 affected, err := engine.table(new(user)).id(id).update(map[string]interface{}{"age":0})
Version 要使用, 需要使用 version type User struct { Id int64 Name string Version int xorm:"version" } 在 Insert,version 的字段将会被 置 1, 在 Update,Update 的内容必 包含 version 原来的 var user User engine.id(1).get(&user) // SELECT * FROM user WHERE id =? engine.id(1).update(&user) // UPDATE user SET..., version = version + 1 WHERE id =? AND version =?
更新 Updated Updated 可以 您在 插入或每次 更新 自 更新数据 中的 字段 当前, 需要在 xorm 中使用 updated, 如下所示 行, 的字段必 time.time 型 type User struct { Id int64 Name string UpdatedAt time.time `xorm:"updated"` } 在 Insert(), InsertOne(), Update() 方法被 用,updated 的字段将会被自 更新 当前, 如下所示 : var user User engine.id(1).get(&user) // SELECT * FROM user WHERE id =? engine.id(1).update(&user) // UPDATE user SET..., updaetd_at =? WHERE id =?
除数据 除数据 Delete 方法, 参数 struct 的指 并且成 条件 user := new(user) affected, err := engine.id(id).delete(user) Delete 的返回 第一个参数 除的 数, 第二个参数 注意 : 当 除, 如果 user 中包含有 bool,float64 或者 float32 型, 有可能会使 除失 具体 看 FAQ
除 Deleted Deleted 可以 您不真正的 除数据, 而是 一个 除 使用此特性需要在 xorm 中使用 deleted, 如下所示 行, 的字段必 time.time 型 type User struct { Id int64 Name string DeletedAt time.time `xorm:"deleted"` } 在 Delete(),deleted 的字段将会被自 更新 当前 而不是去 除 条, 如下所示 : var user User engine.id(1).get(&user) // SELECT * FROM user WHERE id =? engine.id(1).delete(&user) // UPDATE user SET..., deleted_at =? WHERE id =? engine.id(1).get(&user) // 再次 用 Get, 此 将返回 false, nil, 即 不存在 engine.id(1).delete(&user) // 再次 用 除会返回 0, nil, 即 不存在 那么如果 已 被 除后, 要真正的 得 条 或者真正的 除 条, 需要 用 Unscoped, 如下所示 : var user User engine.id(1).unscoped().get(&user) // 此 将可以 得 engine.id(1).unscoped().delete(&user) // 此 将可以真正的 除
行 SQL 也可以直接 行一个 SQL, 即 Select 命令 在 Postgres 中支持原始 SQL 句中使用 ` 和? 符号 sql := "select * from userinfo" results, err := engine.query(sql) 当 用 Query, 第一个返回 results []map[string][]byte 的形式
行 SQL 命令 也可以直接 行一个 SQL 命令, 即 行 Insert, Update, Delete 等操作 此 不管数据 是何种 型, 都可以使用 ` 和? 符 号 sql = "update `userinfo` set username=? where id=?" res, err := engine.exec(sql, "xiaolun", 1)
事 理 当使用事 理, 需要 建 Session 象 在 行事物 理, 可以混用 ORM 方法和 RAW 方法, 如下代 所示 : session := engine.newsession() defer session.close() // add Begin() before any action err := session.begin() user1 := Userinfo{Username: "xiaoxiao", Departname: "dev", Alias: "lunny", Created: time.now()} _, err = session.insert(&user1) if err!= nil { session.rollback() return } user2 := Userinfo{Username: "yyy"} _, err = session.where("id =?", 2).Update(&user2) if err!= nil { session.rollback() return } _, err = session.exec("delete from userinfo where username =?", user2.username) if err!= nil { session.rollback() return } // add Commit() after all actions err = session.commit() if err!= nil { return } 注意如果您使用的是 mysql, 数据 引擎 innodb 事 才有效,myisam 引擎是不支持事 的
存 xorm 内置了一致性 存支持, 不 默 并没有开 要开 存, 需要在 engine 建完后 行配置, 如 : 用一个全局的 内存 存 cacher := xorm.newlrucacher(xorm.newmemorystore(), 1000) engine.setdefaultcacher(cacher) 上述代 采用了 LRU 算法的一个 存, 存方式是存放到内存中, 存 struct 的 数 1000 条, 存 的范 是所有具 有主 的表, 没有主 的表中的数据将不会被 存 如果只想 部分表, : cacher := xorm.newlrucacher(xorm.newmemorystore(), 1000) engine.mapcacher(&user, cacher) 如果要禁用某个表的 存, : engine.mapcacher(&user, nil) 置完之后, 其它代 基本上就不需要改 了, 存系 已 在后台 行 当前 了内存存 的 CacheStore 接口 MemoryStore, 如果需要采用其它 存, 可以 CacheStore 接口 不 需要特 注意不适用 存或者需要手 的地方 : 1. 当使用了 Distinct, Having, GroupBy 方法将不会使用 存 2. 在 Get 或者 Find 使用了 Cols, Omit 方法, 在开 存后此方法无效, 系 仍旧会取出 个表中的所有字段 3. 在使用 Exec 方法 行了方法之后, 可能会 致 存与数据 不一致的地方 因此如果 用 存, 尽量避免使用 Exec 如 果必 使用, 需要在使用了 Exec 之后 用 ClearCache 手 做 存清除的工作 比如 : engine.exec("update user set name =? where id =?", "xlw", 1) engine.clearcache(new(user)) 存的 原理如下 所示 :
事件 xorm 支持 种方式的事件, 一种是在 Struct 中的特定方法来作 事件的方法, 一种是在 行 句的 程中 行事件 在 Struct 中作 成 方法的事件如下 : BeforeInsert() BeforeUpdate() BeforeDelete() func BeforeSet(name string, cell xorm.cell) 在 Get 或 Find 方法中, 当数据已 从数据 出来, 而在 置到 体之前 用 AfterInsert() AfterUpdate() AfterDelete() 在 句 行 程中的事件方法 : Before(beforeFunc interface{}) After(afterFunc interface{}) 其中 beforefunc 和 afterfunc 的原型 func(bean interface{}).
xorm 工具 xorm 是一 数据 操作命令行工具 二 制安装 如果你安装了 got, 你可以 入如下命令安装 : got go-xorm/cmd/xorm 或者你可以从 gobuild 下 后解 到可 行路径 源 安装 go get github.com/go-xorm/cmd/xorm 同 你需要安装如下依 : github.com/go-xorm/xorm Mysql: github.com/go-sql-driver/mysql MyMysql: github.com/ziutek/mymysql/godrv Postgres: github.com/lib/pq SQLite: github.com/mattn/go-sqlite3 ** 于 sqlite3 的支持, 你需要自己 行 go build -tags sqlite3 因 sqlite3 需要 cgo 的支持 命令列表 有如下可用的命令 : reverse 反 一个数据, 生成代 shell 通用的数据 操作客 端, 可 数据 和数据操作 dump Dump 数据 中所有 和数据到 准 出 source 从 注 入中 行 SQL 文件 driver 列出所有支持的数据 reverse Reverse command is a tool to convert your database struct to all kinds languages of structs or classes. After you installed the tool, you can type xorm help reverse to get help example: sqlite: xorm reverse sqite3 test.db templates/goxorm mysql: xorm reverse mysql root:@/xorm_test?charset=utf8 templates/goxorm
mymysql: xorm reverse mymysql xorm_test2/root/ templates/goxorm postgres: xorm reverse postgres "dbname=xorm_test sslmode=disable" templates/goxorm will generated go files in./model directory Template and Config Now, xorm tool supports go and c++ two languages and have go, goxorm, c++ three of default templates. In template directory, we can put a config file to control how to generating. lang=go genjson=1 lang must be go or c++ now. genjson can be 1 or 0, if 1 then the struct will have json tag. Shell Shell command provides a tool to operate database. For example, you can create table, alter table, insert data, delete data and etc. xorm shell sqlite3 test.db will connect to the sqlite3 database and you can type help to list all the shell commands. Dump Dump command provides a tool to dump all database structs and data as SQL to your standard output. xorm dump sqlite3 test.db could dump sqlite3 database test.db to standard output. If you want to save to file, just type xorm dump sqlite3 test.db > test.sql. Source xorm source sqlite3 test.db < test.sql will execute sql file on the test.db. Driver List all supported drivers since default build will not include sqlite3. LICENSE BSD License http://creativecommons.org/licenses/bsd/
常 怎么同 使用 xorm 的 tag 和 json 的 tag? 答 : 使用空格 type User struct { Name string `json:"name" xorm:"name"` } 我的 struct 里面包含 bool 型, 什么它不能作 条件也没法用 Update 更新? 答 : 默 bool 型因 无法判断是否 空, 所以不会自 作 条件也不会作 Update 的内容 可以使用 UseBool 函数, 也可 以使用 Cols 函数 engine.cols("bool_field").update(&struct{boolfield:true}) // UPDATE struct SET bool_field = true 我的 struct 里面包含 float64 和 float32 型, 什么用他 作 条件 是不正确? 答 : 默 float32 和 float64 映射到数据 中 float,real,double 几种 型, 几种数据 型数据 的 一般都是非精确 的 因此作 相等条件 有可能不会返回正确的 果 如果一定要作 条件, 将数据 中的 型定 Numeric 或 者 Decimal type account struct { money float64 `xorm:"numeric"` } 什么 Update Sqlite3 返回的 affected 和其它数据 不一? 答 :Sqlite3 默 Update 返回的是 update 的 条件的 数条数, 不管 是否真的有更新 而 Mysql 和 Postgres 默 情 况下都是只返回 中有字段改 的 数 xorm 有几种命名映射? 答 : 目前支持 SnakeMapper 和 SameMapper 种 SnakeMapper 支持 体和成 以 峰式命名而数据 表和字段以下划 接命名 ;SameMapper 支持 体和数据 的命名保持一致的映射 xorm 支持复合主? 答 : 支持 在定, 如果有多个字段 了 pk, 些字段自 成 复合主, 序 在 struct 中出 的 序 在使用 Id 方 法, 可以用 Id(xorm.PK{1, 2}) 的方式来用 xorm 如何使用 Join? 答 : 一般我 配合 Join() 和 extends 来 行, 比如我 要 个表 行 Join 操作, 我 可以 :
type Userinfo struct { Id int64 Name string DetailId int64 } type Userdetail struct { Id int64 Gender int } type User struct { Userinfo `xorm:"extends"` Userdetail `xorm:"extends"` } var users = make([]user, 0) err := engine.table(&userinfo{}).join("left", "userdetail", "userinfo.detail_id = userdetail.id").find(&users) 注意 里的 Userinfo 在 User 中的位置必 在 Userdetail 的前面, 因 他在 join 句中的 序在 userdetail 前面 如果 序不, 那么 于同名的列, 有可能会 出 当然, 如果 Join 句比 复, 我 也可以直接用 Sql 函数 err := engine.sql("select * from userinfo, userdetail where userinfo.detail_id = userdetail.id").find(&users)
案例 Gogs - github.com/gogits/gogs Gowalker - github.com/unknwon/gowalker Gobuild.io - github.com/shxsun/gobuild Sudo China - github.com/insionng/toropress Godaily - github.com/govc/godaily GoCMS - github.com/zzboy/gocms GoBBS - gobbs.domolo.com go-blog - github.com/easykoo/go-blog
更新日志 v0.4.0 RC1 新特性 : 移 xorm cmd github.com/go-xorm/cmd 在重 一般 DB 操作核心 github.com/go-xorm/core 移 github.com/xorm/tests github.com/go-xorm/tests 改 : Prepared statement 存添加 Incr API 指定 区位置 v0.3.2 改 : Add AllCols & MustCols function Add TableName for custom table name Bug 修复 : 46 51 53 89 86 92 v0.3.1 新特性 : 支持 MSSQL DB 通 ODBC (github.com/lunny/godbc); 通 多个 pk 支持 合主 ; 新增 Rows() API 用来遍 果, 函数提供了 似 sql.rows 的相似用法, 可作 Iterate() API 的可 替代 ; ORM 体 在允 内建 型的指 作 成, 使得数据 null 成 可能 ; Before 和 After 支持 改 : 允 int/int32/int64/uint/uint32/uint64/string 作 主 型 函数 Get()/Find()/Iterate() 在性能上的改 v0.2.3 : 改善了文档 ; 提供了 支持 ; 添加了 区 字段支持 ;Mapper 在分成表名 Mapper 和字段名 Mapper, 同 了表或字段的自定 前 后 ;Insert 方法的返回 含 从 id, err 更改 affected, err, 大家注意 ; 添加了 UseBool 和 Distinct 函数
v0.2.2 : Postgres 新增了 lib/pq 的支持 ; 新增了逐条遍 方法 Iterate; 新增了 SetMaxConns(go1.2+) 支持, 修复了 bug 若干 ; v0.2.1 : 新增数据 反 工具, 当前支持 go 和 c++ 代 的生成, Xorm Tool README; 修复了一些 bug. v0.2.0 : 新增 存支持, 速度提升 3-5 倍 ; 新增数据 表和 Struct 同名的映射方式 ; 新增 Sync 同步表 ; v0.1.9 : 新增 postgres 和 mymysql 支持 ; 在 Postgres 中支持原始 SQL 句中使用 ` 和? 符号 ; 新增 Cols, StoreEngine, Charset 函数 ;SQL 句打印支持 io.writer 接口, 默 打印到控制台 ; 新增更多的字段 型支持, 映射 ; 除 弃的 MakeSession 和 Create 函数 v0.1.8 : 新增 合 index, 合 unique 支持, 看映射 v0.1.7 : 新增 IConnectPool 接口以及 NoneConnectPool, SysConnectPool, SimpleConnectPool 三种, 可以 不使用 接池, 使用系 接池和使用自 接池三种, 默 SysConnectPool, 即系 自 的 接池 同 支持自定 接池 Engine 新增 Close 方法, 在系 退出 用此方法 v0.1.6 : 新增 Conversion, 支持自定 型到数据 型的 ; 新增 体自 匿名成 支持 ; 新增 向映射支持 ; v0.1.5 : 新增 多 程的支持 ; 新增 Sql() 函数 ; 支持任意 sql 句的 struct ;Get 函数返回 ;MakeSession 和 Create 函数被 NewSession 和 NewEngine 函数替代 ; v0.1.4 : Get 函数和 Find 函数新增 的 入功能 ; 更多的数据 型支持 v0.1.3 : Find 函数 在支持 入 Slice 或者 Map, 当 入 Map,key id; 新增 Table 函数以 多表和 表 行支持 v0.1.2 : Insert 函数支持混合 struct 和 slice 指 入, 并根据数据 型自 批量插入, 同 自 添加事 v0.1.1 : 添加 Id, In 函数, 改善 README 文档 v0.1.0 : 初始化工程 s