orm docs update

slene
Showing 5 changed files with 168 additions and 30 deletions
orm/README.md
orm/docs/zh/Models.md
orm/docs/zh/Orm.md
orm/docs/zh/Query.md
orm/docs/zh/README.md
--- a/orm/README.md
View file @c6a436e
+++ b/orm/README.md
View file @c6a436e
 # beego orm

-a powerful orm framework
+[![Build Status](https://drone.io/github.com/astaxie/beego/status.png)](https://drone.io/github.com/astaxie/beego/latest)
+
+A powerful orm framework for go.
+
+It is heavily influenced by Django ORM, SQLAlchemy.

 now, beta, unstable, may be changing some api make your app build failed.

@@ -14,12 +18,25 @@ Passed all test, but need more feedback.

 **Features:**

-...
+* full go type support
+* easy for usage, simple CRUD operation
+* auto join with relation table
+* cross DataBase compatible query
+* Raw SQL query / mapper without orm model
+* full test keep stable and strong
+
+more features please read the docs

 **Install:**

 	go get github.com/astaxie/beego/orm

+## Changelog
+
+* 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
+
 ## Quick Start

 #### Simple Usage
@@ -143,5 +160,3 @@ more details and examples in docs and test
 - some unrealized api
 - examples
 - docs
-
-## 
--- a/orm/docs/zh/Models.md
View file @c6a436e
+++ b/orm/docs/zh/Models.md
View file @c6a436e
@@ -164,27 +164,91 @@ type Profile struct {
 ```


-## Struct Field 类型与数据库的对应
-
-现在 orm 支持下面的字段形式
-
-| go type		   | field type  | mysql type
-| :---   	   | :---        | :---
-| bool | TypeBooleanField | tinyint
-| string | TypeCharField | varchar
-| string | TypeTextField | longtext
-| time.Time | TypeDateField | date
-| time.TIme | TypeDateTimeField | datetime
-|  int16 |TypeSmallIntegerField | int(4)
-|  int, int32 |TypeIntegerField | int(11)
-|  int64 |TypeBigIntegerField | bigint(20)
-|  uint, uint16 |TypePositiveSmallIntegerField | int(4) unsigned
-|  uint32 |TypePositiveIntegerField | int(11) unsigned
-|  uint64 |TypePositiveBigIntegerField | bigint(20) unsigned
-| float32, float64 | TypeFloatField | double
-| float32, float64 | TypeDecimalField | double(digits, decimals)
-
-关系型的字段，其字段类型取决于对应的主键。
+## 模型字段与数据库类型的对应
+
+在此列出 orm 推荐的对应数据库类型，自动建表功能也会以此为标准。
+
+默认所有的字段都是 **NOT NULL**
+
+#### MySQL
+
+| go		   |mysql
+| :---   	   | :---
+| bool | bool
+| string - 设置 size 时 | varchar(size)
+| string | longtext
+| time.Time - 设置 type 为 date 时 | date
+| time.TIme | datetime
+| byte | tinyint unsigned
+| rune | integer
+| int | integer
+| int8 | tinyint
+| int16 | smallint
+| int32 | integer
+| int64 | bigint
+| uint | integer unsigned
+| uint8 | tinyint unsigned
+| uint16 | smallint unsigned
+| uint32 | integer unsigned
+| uint64 | bigint unsigned
+| float32 | double precision
+| float64 | double precision
+| float64 - 设置 digits, decimals 时  | numeric(digits, decimals)
+
+#### Sqlite3
+
+| go		   | sqlite3
+| :---   	   | :---
+| bool | bool
+| string - 设置 size 时 | varchar(size)
+| string | text
+| time.Time - 设置 type 为 date 时 | date
+| time.TIme | datetime
+| byte | tinyint unsigned
+| rune | integer
+| int | integer
+| int8 | tinyint
+| int16 | smallint
+| int32 | integer
+| int64 | bigint
+| uint | integer unsigned
+| uint8 | tinyint unsigned
+| uint16 | smallint unsigned
+| uint32 | integer unsigned
+| uint64 | bigint unsigned
+| float32 | real
+| float64 | real
+| float64 - 设置 digits, decimals 时  | decimal
+
+#### PostgreSQL
+
+| go		   | postgres
+| :---   	   | :---
+| bool | bool
+| string - 设置 size 时 | varchar(size)
+| string | text
+| time.Time - 设置 type 为 date 时 | date
+| time.TIme | timestamp with time zone
+| byte | smallint CHECK("column" >= 0 AND "column" <= 255)
+| rune | integer
+| int | integer
+| int8 | smallint CHECK("column" >= -127 AND "column" <= 128)
+| int16 | smallint
+| int32 | integer
+| int64 | bigint
+| uint | bigint CHECK("column" >= 0)
+| uint8 | smallint CHECK("column" >= 0 AND "column" <= 255)
+| uint16 | integer CHECK("column" >= 0)
+| uint32 | bigint CHECK("column" >= 0)
+| uint64 | bigint CHECK("column" >= 0)
+| float32 | double precision
+| float64 | double precision
+| float64 - 设置 digits, decimals 时  | numeric(digits, decimals)
+
+
+## 关系型字段
+
+其字段类型取决于对应的主键。

 * RelForeignKey
 * RelOneToOne
--- a/orm/docs/zh/Orm.md
View file @c6a436e
+++ b/orm/docs/zh/Orm.md
View file @c6a436e
@@ -80,7 +80,7 @@ import (

 #### RegisterDriver

-三种数据库类型
+三种默认数据库类型

 ```go
 orm.DR_MySQL
@@ -93,7 +93,7 @@ orm.DR_Postgres
 // 参数2   数据库类型
 // 这个用来设置 driverName 对应的数据库类型
 // mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置
-orm.RegisterDriver("mysql", orm.DR_MySQL)
+orm.RegisterDriver("mymysql", orm.DR_MySQL)
 ```

 #### RegisterDataBase
@@ -108,6 +108,56 @@ orm 必须注册一个名称为 `default` 的数据库，用以作为默认使
 orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30)
 ```

+#### 时区设置
+
+orm 默认使用 time.Local 本地时区
+
+* 作用于 orm 自动创建的时间
+* 从数据库中取回的时间转换成 orm 本地时间
+
+如果需要的话，你也可以进行更改
+
+```go
+// 设置为 UTC 时间
+orm.DefaultTimeLoc = time.UTC
+```
+
+orm 在进行 RegisterDataBase 的同时，会获取数据库使用的时区，然后在 time.Time 类型存取的时做相应转换，以匹配时间系统，从而保证时间不会出错。
+
+**注意:** 鉴于 Sqlite3 的设计，存取默认都为 UTC 时间
+
+## RegisterModel
+
+如果使用 orm.QuerySeter 进行高级查询的话，这个是必须的。
+
+反之，如果只使用 Raw 查询和 map struct，是无需这一步的。您可以去查看 [Raw SQL 查询](Raw.md)
+
+将你定义的 Model 进行注册，最佳设计是有单独的 models.go 文件，在他的 init 函数中进行注册。
+
+
+迷你版 models.go
+```go
+package main
+
+import "github.com/astaxie/beego/orm"
+
+type User struct {
+	Id   int    `orm:"auto"`
+	name string
+}
+
+func init(){
+	orm.RegisterModel(new(User))
+}
+```
+
+RegisterModel 也可以同时注册多个 model
+
+```go
+orm.RegisterModel(new(User), new(Profile), new(Post))
+```
+
+
 ## ORM 接口使用

 使用 orm 必然接触的 Ormer 接口，我们来熟悉一下
--- a/orm/docs/zh/Query.md
View file @c6a436e
+++ b/orm/docs/zh/Query.md
View file @c6a436e
@@ -15,7 +15,7 @@ qs = o.QueryTable(user) // 返回 QuerySeter
 ```
 ## expr

-QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方法
+QuerySeter 中用于描述字段和 sql 操作符，使用简单的 expr 查询方法

 字段组合的前后顺序依照表的关系，比如 User 表拥有 Profile 的外键，那么对 User 表查询对应的 Profile.Age 为条件，则使用 `Profile__Age` 注意，字段的分隔符号使用双下划线 `__`，除了描述字段， expr 的尾部可以增加操作符以执行对应的 sql 操作。比如 `Profile__Age__gt` 代表 Profile.Age > 18 的条件查询。

--- a/orm/docs/zh/README.md
View file @c6a436e
+++ b/orm/docs/zh/README.md
View file @c6a436e
 ## 文档目录

-
 1. [Orm 使用方法](Orm.md)
 	- [数据库的设置](Orm.md#数据库的设置)
+		* [驱动类型设置](Orm.md#registerdriver)
+		* [参数设置](Orm.md#registerdataBase)
+		* [时区设置](Orm.md#时区设置)
+	- [注册 ORM 使用的模型](Orm.md#registermodel)
 	- [ORM 接口使用](Orm.md#orm-接口使用)
 	- [调试模式打印查询语句](Orm.md#调试模式打印查询语句)
 2. [对象的CRUD操作](Object.md)
@@ -15,6 +18,12 @@
 6. [模型定义](Models.md)
 	- [Struct Tag 设置参数](Models.md#struct-tag-设置参数)
 	- [表关系设置](Models.md#表关系设置)
-	- [Struct Field 类型与数据库的对应](Models.md#struct-field-类型与数据库的对应)
+	- [模型字段与数据库类型的对应](Models.md#模型字段与数据库类型的对应)
 7. Custom Fields
 8. Faq
+
+
+### 文档更新记录
+
+* 2013-08-13: ORM 的 [时区设置](Orm.md#时区设置)
+* 2013-08-13: [模型字段与数据库类型的对应](Models.md#模型字段与数据库类型的对应) 推荐的数据库对应使用的类型