From 9a79822ff2156d96657288e64eba23c93015ecf0 Mon Sep 17 00:00:00 2001 From: Jinzhu Date: Sun, 21 Feb 2016 23:09:24 +0800 Subject: [PATCH] Update Document --- doc/SUMMARY.md | 36 ++---------------- doc/associations/associations.md | 0 doc/associations/belongs-to.md | 0 doc/book.json | 50 +++++++++++++++++++++++- doc/database/connect-database.md | 65 ++++++++++++++++++++++++-------- doc/database/database.md | 19 +--------- doc/database/migration.md | 30 +++++++++++++++ doc/models/defination.md | 0 doc/models/models.md | 8 ++++ doc/models/naming-conventions.md | 0 10 files changed, 140 insertions(+), 68 deletions(-) create mode 100644 doc/associations/associations.md create mode 100644 doc/associations/belongs-to.md create mode 100644 doc/models/defination.md create mode 100644 doc/models/models.md create mode 100644 doc/models/naming-conventions.md diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md index 28c2ffdb..7195a268 100644 --- a/doc/SUMMARY.md +++ b/doc/SUMMARY.md @@ -1,40 +1,12 @@ # Summary * [GORM GITHUB](http://github.com/jinzhu/gorm) -* [Getting Start](README.md) +* [Getting Started with GORM](README.md) {% for path, chapter in book.chapters %} * [{{ chapter.name }}]({{ path }}) {% for section in chapter.sections %} * [{{ section.name }}]({{ section.path }}) - {% endfor %} + {% if section["sections"] %}{% for subsection in section.sections %} + * [{{ subsection.name }}]({{ subsection.path }}) + {% endfor %}{% endif %}{% endfor %} {% endfor %} - -* [Database](database/database.md) - * [Connecting to a Database](database/connect-database.md) - * [Migration](database/migration.md) - * [Schema]() -* [Models]() - * [Model Defination]() - * [Naming Conventions & Overriding]() - * [Associations]() - * [Belongs To]() - * [Has One]() - * [Has Many]() - * [Many To Many]() - * [Polymorphism]() - * [Association Mode]() -* [CRUD: Reading and Writing Data]() - * [Create]() - * [Query]() - * [Preloading (Eager Loading)]() - * [Update]() - * [Delete / Soft Delete]() - * [Callbacks]() -* [Advanced Usage]() - * [Error Handling]() - * [Transactions]() - * [Raw SQL & SQL Builder]() - * [Composite Primary Key]() - * [Overriding Logger]() -* [Development]() - * [Write Plugins]() diff --git a/doc/associations/associations.md b/doc/associations/associations.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/associations/belongs-to.md b/doc/associations/belongs-to.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/book.json b/doc/book.json index 65889b54..9e347864 100644 --- a/doc/book.json +++ b/doc/book.json @@ -13,7 +13,7 @@ "url": "https://github.com/jinzhu/gorm" }, "edit-link": { - "base": "https://github.com/jinzhu/gorm/edit/gh-pages", + "base": "https://github.com/jinzhu/gorm/edit/master", "label": "Edit This Page" } }, @@ -28,9 +28,55 @@ "database/database.md": { "name": "Databae", "sections": [ - {"name": "Connection to a Database", "path": "database/connect-database.md"}, + {"name": "Database Connection", "path": "database/connect-database.md"}, {"name": "Migration", "path": "database/migration.md"} ] + }, + "models/models.md": { + "name": "Models", + "sections": [ + {"name": "Model Defination", "path": "models/defination.md"}, + {"name": "Naming Conventions & Overriding", "path": "models/naming-conventions.md"}, + {"name": "Associations", "path": "associations/associations.md", "sections": + [ + {"name": "Belongs To", "path": "associations/belongs-to.md"}, + {"name": "Has One", "path": "associations/has-one.md"}, + {"name": "Has Many", "path": "associations/has-many.md"}, + {"name": "Many To Many", "path": "associations/many-to-many.md"}, + {"name": "Polymorphism", "path": "associations/polymorphism.md"}, + {"name": "Association Mode", "path": "associations/association-mode.md"} + ] + } + ] + }, + "curd/curd.md": { + "name": "CRUD: Reading and Writing Data", + "sections": [ + {"name": "Create", "path": "curd/create.md"}, + {"name": "Query", "path": "curd/query.md"}, + {"name": "Preloading (Eager Loading)", "path": "curd/preloading.md"}, + {"name": "Update", "path": "curd/update.md"}, + {"name": "Delete / Soft Delete", "path": "curd/delete.md"} + ] + }, + "callbacks/callbacks.md": { + "name": "Callbacks" + }, + "advanced/advanced.md": { + "name": "Advanced Usage", + "sections": [ + {"name": "Error Handling", "path": "advanced/error-handling.md"}, + {"name": "Transactions", "path": "advanced/transactions.md"}, + {"name": "Raw SQL & SQL Builder", "path": "advanced/sql-builder.md"}, + {"name": "Composite Primary Key", "path": "advanced/compose-primary-key.md"}, + {"name": "Overriding Logger", "path": "advanced/logger.md"} + ] + }, + "development/development.md": { + "name": "Development", + "sections": [ + {"name": "Write Plugins", "path": "development/plugins.md"} + ] } } } diff --git a/doc/database/connect-database.md b/doc/database/connect-database.md index 29432a16..66f04509 100644 --- a/doc/database/connect-database.md +++ b/doc/database/connect-database.md @@ -1,33 +1,66 @@ -### Connecting To A Database +# Database Connection + + + +## Connecting to a database + +#### MySQL + +**NOTE** don't forgot params `parseTime` to handle data type `time.Time`, [more support parameters](https://github.com/go-sql-driver/mysql#parameters) + +```go +import ( + "github.com/jinzhu/gorm" + _ "github.com/go-sql-driver/mysql" +) +func main() { + db, err := gorm.Open("mysql", "user:password@/dbname?charset=utf8&parseTime=True&loc=Local") +} +``` + +#### PostgreSQL ```go import ( "github.com/jinzhu/gorm" _ "github.com/lib/pq" - _ "github.com/go-sql-driver/mysql" - _ "github.com/mattn/go-sqlite3" ) - -func init() { +func main() { db, err := gorm.Open("postgres", "user=gorm dbname=gorm sslmode=disable") - // db, err := gorm.Open("mysql", "user:password@/dbname?charset=utf8&parseTime=True&loc=Local") - // db, err := gorm.Open("sqlite3", "/tmp/gorm.db") - - // Use existing database connection - dbSql, err := sql.Open("postgres", "user=gorm dbname=gorm sslmode=disable") - db, err := gorm.Open("postgres", dbSql) } ``` +#### Sqlite3 + ```go -// Get database connection handle [*sql.DB](http://golang.org/pkg/database/sql/#DB) +import ( + "github.com/jinzhu/gorm" + _ "github.com/mattn/go-sqlite3" +) +func main() { + db, err := gorm.Open("sqlite3", "/tmp/gorm.db") +} +``` + +#### Write Dialect for unsupported databases + +GORM officially support above databases, for unsupported databaes, you could write a dialect for that. + +Refer: https://github.com/jinzhu/gorm/blob/master/dialect.go + + +## Generic database object *sql.DB + +[*sql.DB](http://golang.org/pkg/database/sql/#DB) + +```go +// Get generic database object *sql.DB to use its functions db.DB() -// Then you could invoke `*sql.DB`'s functions with it -db.DB().Ping() +// Connection Pool db.DB().SetMaxIdleConns(10) db.DB().SetMaxOpenConns(100) -// Disable table name's pluralization -db.SingularTable(true) + // Ping +db.DB().Ping() ``` diff --git a/doc/database/database.md b/doc/database/database.md index 913a283f..0733f61b 100644 --- a/doc/database/database.md +++ b/doc/database/database.md @@ -1,22 +1,5 @@ -## Database +# Database {% for section in book.chapters["database/database.md"].sections %} * [**{{section.name}}**](../{{section.path}}) {% endfor %} -{{book.chapters}} - - diff --git a/doc/database/migration.md b/doc/database/migration.md index 6ff8f080..0ca27a13 100644 --- a/doc/database/migration.md +++ b/doc/database/migration.md @@ -57,3 +57,33 @@ db.Model(&User{}).ModifyColumn("description", "text") ```go db.Model(&User{}).DropColumn("description") ``` + +### Add Foreign Key + +```go +// Add foreign key +// 1st param : foreignkey field +// 2nd param : destination table(id) +// 3rd param : ONDELETE +// 4th param : ONUPDATE +db.Model(&User{}).AddForeignKey("city_id", "cities(id)", "RESTRICT", "RESTRICT") +``` + +### Indexes + +```go +// Add index +db.Model(&User{}).AddIndex("idx_user_name", "name") + +// Multiple column index +db.Model(&User{}).AddIndex("idx_user_name_age", "name", "age") + +// Add unique index +db.Model(&User{}).AddUniqueIndex("idx_user_name", "name") + +// Multiple column unique index +db.Model(&User{}).AddUniqueIndex("idx_user_name_age", "name", "age") + +// Remove index +db.Model(&User{}).RemoveIndex("idx_user_name") +``` diff --git a/doc/models/defination.md b/doc/models/defination.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/models/models.md b/doc/models/models.md new file mode 100644 index 00000000..46abf2da --- /dev/null +++ b/doc/models/models.md @@ -0,0 +1,8 @@ +# Models + +{% for section in book.chapters["models/models.md"].sections %} +* [**{{section.name}}**](../{{section.path}}) +{% if section["sections"] %}{% for subsection in section.sections %} + * [**{{ subsection.name }}**]({{ subsection.path }}) +{% endfor %}{% endif %} +{% endfor %} diff --git a/doc/models/naming-conventions.md b/doc/models/naming-conventions.md new file mode 100644 index 00000000..e69de29b