From b114f258d61e7c917dc23090ee93a6f346c30389 Mon Sep 17 00:00:00 2001 From: slene Date: Mon, 19 Aug 2013 22:37:53 +0800 Subject: [PATCH] orm update docs --- orm/README.md | 1 + orm/docs/zh/Cmd.md | 43 +++++++++++++++++++++++++++++++ orm/docs/zh/Models.md | 59 +++++++++++++++++++++++++++++++++---------- orm/docs/zh/Object.md | 2 +- orm/docs/zh/Orm.md | 28 ++++++++++++++------ orm/docs/zh/Query.md | 2 +- orm/docs/zh/README.md | 11 +++++--- orm/docs/zh/Test.md | 34 +++++++++++++++++++++++++ 8 files changed, 153 insertions(+), 27 deletions(-) create mode 100644 orm/docs/zh/Cmd.md create mode 100644 orm/docs/zh/Test.md diff --git a/orm/README.md b/orm/README.md index e27d2a97..f2f86fd5 100644 --- a/orm/README.md +++ b/orm/README.md @@ -33,6 +33,7 @@ more features please read the docs ## Changelog +* 2013-08-19: support table auto create * 2013-08-13: update test for database types * 2013-08-13: go type support, such as int8, uint8, byte, rune * 2013-08-13: date / datetime timezone support very well diff --git a/orm/docs/zh/Cmd.md b/orm/docs/zh/Cmd.md new file mode 100644 index 00000000..932cb1c6 --- /dev/null +++ b/orm/docs/zh/Cmd.md @@ -0,0 +1,43 @@ +## 命令模式 + +注册模型与数据库以后，调用 RunCommand 执行 orm 命令 + +```go +func main() { + // orm.RegisterModel... + // orm.RegisterDataBase... + ... + orm.RunCommand() +} +``` + +```bash +go build main.go +./main orm +# 直接执行可以显示帮助 +# 如果你的程序可以支持的话，直接运行 go run main.go orm 也是一样的效果 +``` + +## 自动建表 + +```bash +./main orm syncdb -h +Usage of orm command: syncdb: + -db="default": DataBase alias name + -force=false: drop tables before create + -v=false: verbose info +``` + +使用 `-force=1` 可以 drop table 后再建表 + +使用 `-v` 可以查看执行的 sql 语句 + +## 打印建表SQL + +```bash +./main orm sqlall -h +Usage of orm command: syncdb: + -db="default": DataBase alias name +``` + +默认使用别名为 default 的数据库 diff --git a/orm/docs/zh/Models.md b/orm/docs/zh/Models.md index fcd5e458..c8263822 100644 --- a/orm/docs/zh/Models.md +++ b/orm/docs/zh/Models.md @@ -1,13 +1,28 @@ ## 模型定义 -复杂的模型定义不是必须的，此功能用作数据库数据转换和自动建表 +复杂的模型定义不是必须的，此功能用作数据库数据转换和[自动建表](Cmd.md#自动建表) + +默认的表名使用驼峰转蛇形，比如 AuthUser -> auth_user + +**自定义表名** + +```go +type User struct { + Id int + Name string +} + +func (u *User) TableName() string { + return "auth_user" +} +``` + +如果[前缀设置](Orm.md#registermodelwithprefix)为`prefix_`那么表名为：prefix_auth_user ## Struct Tag 设置参数 ```go orm:"null;rel(fk)" ``` - -通常每个 Field 的 StructTag 里包含两种类型的设置，类似 null 的 bool 型设置，还有 类似 rel(fk) 的指定值设置，bool 型默认为 false，指定以后即表示为 true 多个设置间使用 `;` 分隔，设置的值如果是多个，使用 `,` 分隔。 @@ -24,11 +39,13 @@ type User struct { #### auto -设置为 Autoincrement Primary Key +当 Field 类型为 int, int32, int64 时，可以设置字段为自增健 + +当模型定义里没有主键时，符合上述类型且名称为 `Id` 的 Field 将被视为自增健。 #### pk -设置为 Primary Key +设置为主键，适用于自定义其他类型为主键 #### null @@ -60,9 +77,12 @@ type User struct { ... Status int `orm:"default(1)"` ``` -#### size (string) +#### size + +string 类型字段默认为 varchar(255) + +设置 size 以后，db type 将使用 varchar(size) -string 类型字段设置 size 以后，db type 将使用 varchar ```go Title string `orm:"size(60)"` ``` @@ -86,10 +106,18 @@ Updated time.Time `auto_now` #### type -设置为 date, time.Time 字段的对应 db 类型使用 date +设置为 date 时，time.Time 字段的对应 db 类型使用 date + ```go Created time.Time `orm:"auto_now_add;type(date)"` ``` + +设置为 text 时，string 字段对应的 db 类型使用 text + +```go +Content string `orm:"type(text)"` +``` + ## 表关系设置 #### rel / reverse @@ -174,9 +202,10 @@ type Profile struct { | go |mysql | :--- | :--- +| int, int32, int64 - 设置 auto 或者名称为 `Id` 时 | integer AUTO_INCREMENT | bool | bool -| string - 设置 size 时 | varchar(size) -| string | longtext +| string - 默认为 size 255 | varchar(size) +| string - 设置 type(text) 时 | longtext | time.Time - 设置 type 为 date 时 | date | time.TIme | datetime | byte | tinyint unsigned @@ -199,9 +228,10 @@ type Profile struct { | go | sqlite3 | :--- | :--- +| int, int32, int64 - 设置 auto 或者名称为 `Id` 时 | integer AUTOINCREMENT | bool | bool -| string - 设置 size 时 | varchar(size) -| string | text +| string - 默认为 size 255 | varchar(size) +| string - 设置 type(text) 时 | text | time.Time - 设置 type 为 date 时 | date | time.TIme | datetime | byte | tinyint unsigned @@ -224,9 +254,10 @@ type Profile struct { | go | postgres | :--- | :--- +| int, int32, int64 - 设置 auto 或者名称为 `Id` 时 | serial | bool | bool -| string - 设置 size 时 | varchar(size) -| string | text +| string - 默认为 size 255 | varchar(size) +| string - 设置 type(text) 时 | text | time.Time - 设置 type 为 date 时 | date | time.TIme | timestamp with time zone | byte | smallint CHECK("column" >= 0 AND "column" <= 255) diff --git a/orm/docs/zh/Object.md b/orm/docs/zh/Object.md index 0d17c71b..f1a2e0e1 100644 --- a/orm/docs/zh/Object.md +++ b/orm/docs/zh/Object.md @@ -3,7 +3,7 @@ 对 object 操作简单的三个方法 Read / Insert / Update / Delete ```go o := orm.NewOrm() -user := NewUser() +user := new(User) user.Name = "slene" fmt.Println(o.Insert(user)) diff --git a/orm/docs/zh/Orm.md b/orm/docs/zh/Orm.md index 85eb8c69..a5cdf8a5 100644 --- a/orm/docs/zh/Orm.md +++ b/orm/docs/zh/Orm.md @@ -14,13 +14,13 @@ import ( ) type User struct { - Id int `orm:"auto"` // 设置为auto主键 + Id int Name string Profile *Profile `orm:"rel(one)"` // OneToOne relation } type Profile struct { - Id int `orm:"auto"` + Id int Age int16 User *User `orm:"reverse(one)"` // 设置反向关系(可选) } @@ -52,10 +52,10 @@ func main() { o := orm.NewOrm() o.Using("default") // 默认使用 default，你可以指定为其他数据库 - profile := NewProfile() + profile := new(Profile) profile.Age = 30 - user := NewUser() + user := new(User) user.Profile = profile user.Name = "slene" @@ -98,10 +98,10 @@ orm.RegisterDriver("mymysql", orm.DR_MySQL) #### RegisterDataBase -orm 必须注册一个名称为 `default` 的数据库，用以作为默认使用。 +orm 必须注册一个别名为 `default` 的数据库，作为默认使用。 ```go -// 参数1 自定义数据库名称，用来在orm中切换数据库使用 +// 参数1 数据库的别名，用来在orm中切换数据库使用 // 参数2 driverName // 参数3 对应的链接字符串 // 参数4 设置最大的空闲连接数，使用 golang 自己的连接池 @@ -126,12 +126,14 @@ orm 在进行 RegisterDataBase 的同时，会获取数据库使用的时区， **注意:** 鉴于 Sqlite3 的设计，存取默认都为 UTC 时间 -## RegisterModel +## 注册模型 如果使用 orm.QuerySeter 进行高级查询的话，这个是必须的。 反之，如果只使用 Raw 查询和 map struct，是无需这一步的。您可以去查看 [Raw SQL 查询](Raw.md) +#### RegisterModel + 将你定义的 Model 进行注册，最佳设计是有单独的 models.go 文件，在他的 init 函数中进行注册。 @@ -142,7 +144,7 @@ package main import "github.com/astaxie/beego/orm" type User struct { - Id int `orm:"auto"` + Id int name string } @@ -159,6 +161,16 @@ orm.RegisterModel(new(User), new(Profile), new(Post)) 详细的 struct 定义请查看文档 [模型定义](Models.md) +#### RegisterModelWithPrefix + +使用表名前缀 + +```go +orm.RegisterModelWithPrefix("prefix_", new(User)) +``` + +创建后的表名为 prefix_user + ## ORM 接口使用 使用 orm 必然接触的 Ormer 接口，我们来熟悉一下 diff --git a/orm/docs/zh/Query.md b/orm/docs/zh/Query.md index e305a7ef..cfc4073c 100644 --- a/orm/docs/zh/Query.md +++ b/orm/docs/zh/Query.md @@ -10,7 +10,7 @@ o := orm.NewOrm() qs := o.QueryTable("user") // 也可以直接使用对象作为表名 -user := NewUser() +user := new(User) qs = o.QueryTable(user) // 返回 QuerySeter ``` ## expr diff --git a/orm/docs/zh/README.md b/orm/docs/zh/README.md index c5ec73ef..61f67ce9 100644 --- a/orm/docs/zh/README.md +++ b/orm/docs/zh/README.md @@ -5,7 +5,7 @@ * [驱动类型设置](Orm.md#registerdriver) * [参数设置](Orm.md#registerdataBase) * [时区设置](Orm.md#时区设置) - - [注册 ORM 使用的模型](Orm.md#registermodel) + - [注册模型](Orm.md#注册模型) - [ORM 接口使用](Orm.md#orm-接口使用) - [调试模式打印查询语句](Orm.md#调试模式打印查询语句) 2. [对象的CRUD操作](Object.md) @@ -19,11 +19,16 @@ - [Struct Tag 设置参数](Models.md#struct-tag-设置参数) - [表关系设置](Models.md#表关系设置) - [模型字段与数据库类型的对应](Models.md#模型字段与数据库类型的对应) -7. Custom Fields -8. Faq +7. [命令模式](Cmd.md) + - [自动建表](Cmd.md#自动建表) + - [打印建表SQL](Cmd.md#打印建表sql) +8. [Test ORM](Test.md) +9. Custom Fields +10. Faq ### 文档更新记录 +* 2013-08-19: 增加[自动建表](Cmd.md#自动建表)功能 * 2013-08-13: ORM 的 [时区设置](Orm.md#时区设置) * 2013-08-13: [模型字段与数据库类型的对应](Models.md#模型字段与数据库类型的对应) 推荐的数据库对应使用的类型 diff --git a/orm/docs/zh/Test.md b/orm/docs/zh/Test.md new file mode 100644 index 00000000..c2146336 --- /dev/null +++ b/orm/docs/zh/Test.md @@ -0,0 +1,34 @@ +## Test ORM + +测试代码参见 + +```bash +models_test.go // 表定义 +orm_test.go // 测试用例 +``` + +#### MySQL +```bash +mysql -u root -e 'create database orm_test;' +export ORM_DRIVER=mysql +export ORM_SOURCE="root:@/orm_test?charset=utf8" +go test -v github.com/astaxie/beego/orm +``` + + +#### Sqlite3 +```bash +touch /path/to/orm_test.db +export ORM_DRIVER=sqlite3 +export ORM_SOURCE=/path/to/orm_test.db +go test -v github.com/astaxie/beego/orm +``` + + +#### PostgreSQL +```bash +psql -c 'create database orm_test;' -U postgres +export ORM_DRIVER=postgres +export ORM_SOURCE="user=postgres dbname=orm_test sslmode=disable" +go test -v github.com/astaxie/beego/orm +``` \ No newline at end of file