From c6a436ed5d80255003fc9f57dec4ed0796d4d92e Mon Sep 17 00:00:00 2001 From: slene Date: Tue, 13 Aug 2013 18:06:01 +0800 Subject: [PATCH] orm docs update --- orm/README.md | 23 ++++++++-- orm/docs/zh/Models.md | 100 ++++++++++++++++++++++++++++++++++-------- orm/docs/zh/Orm.md | 54 ++++++++++++++++++++++- orm/docs/zh/Query.md | 2 +- orm/docs/zh/README.md | 13 +++++- 5 files changed, 165 insertions(+), 27 deletions(-) diff --git a/orm/README.md b/orm/README.md index b9da3ba1..e27d2a97 100644 --- a/orm/README.md +++ b/orm/README.md @@ -1,6 +1,10 @@ # 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 - -## diff --git a/orm/docs/zh/Models.md b/orm/docs/zh/Models.md index 5f82e8eb..fcd5e458 100644 --- a/orm/docs/zh/Models.md +++ b/orm/docs/zh/Models.md @@ -164,27 +164,91 @@ type Profile struct { ``` -## Struct Field 类型与数据库的对应 +## 模型字段与数据库类型的对应 -现在 orm 支持下面的字段形式 +在此列出 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) +默认所有的字段都是 **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 diff --git a/orm/docs/zh/Orm.md b/orm/docs/zh/Orm.md index a43f0b81..a8be1d1c 100644 --- a/orm/docs/zh/Orm.md +++ b/orm/docs/zh/Orm.md @@ -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 接口，我们来熟悉一下 diff --git a/orm/docs/zh/Query.md b/orm/docs/zh/Query.md index 0ec31fcc..e305a7ef 100644 --- a/orm/docs/zh/Query.md +++ b/orm/docs/zh/Query.md @@ -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 的条件查询。 diff --git a/orm/docs/zh/README.md b/orm/docs/zh/README.md index 305e19a8..c5ec73ef 100644 --- a/orm/docs/zh/README.md +++ b/orm/docs/zh/README.md @@ -1,8 +1,11 @@ ## 文档目录 - 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#模型字段与数据库类型的对应) 推荐的数据库对应使用的类型