orm update docs

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

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 的数据库

orm/docs/zh/Models.md

@@ -1,14 +1,29 @@
 ## 模型定义
 
-复杂的模型定义不是必须的，此功能用作数据库数据转换和自动建表
+复杂的模型定义不是必须的，此功能用作数据库数据转换和[自动建表](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 - 默认为 size 255 | varchar(size)
-| string | longtext
+| 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 - 默认为 size 255 | varchar(size)
-| string | text
+| 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 - 默认为 size 255 | varchar(size)
-| string | text
+| string - 设置 type(text) 时 | text
 | time.Time - 设置 type 为 date 时 | date
 | time.TIme | timestamp with time zone
 | byte | smallint CHECK("column" >= 0 AND "column" <= 255)

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))

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 接口，我们来熟悉一下

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

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
+7. [命令模式](Cmd.md)
-8. Faq
+	- [自动建表](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#模型字段与数据库类型的对应) 推荐的数据库对应使用的类型

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
+```