diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..9f743a65 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +/_book +/node_modules diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..4409686b --- /dev/null +++ b/doc/README.md @@ -0,0 +1,3 @@ +# GORM + +This is GORM diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md new file mode 100644 index 00000000..dea1d177 --- /dev/null +++ b/doc/SUMMARY.md @@ -0,0 +1,32 @@ +# Summary + +* [GORM](README.md) +* [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/book.json b/doc/book.json new file mode 100644 index 00000000..bcf750b9 --- /dev/null +++ b/doc/book.json @@ -0,0 +1,20 @@ +{ + "title": "GORM Guide", + "plugins": [ + "prism", "-highlight", "collapsible-menu", "toc", + "github", "anchors", "edit-link" + ], + "pluginsConfig": { + "toc": { + "addClass": true, + "className": "toc" + }, + "github": { + "url": "https://github.com/jinzhu/gorm" + }, + "edit-link": { + "base": "https://github.com/jinzhu/gorm/edit/gh-pages", + "label": "Edit This Page" + } + } +} diff --git a/doc/database/connect-database.md b/doc/database/connect-database.md new file mode 100644 index 00000000..29432a16 --- /dev/null +++ b/doc/database/connect-database.md @@ -0,0 +1,33 @@ +### Connecting To A Database + +```go +import ( + "github.com/jinzhu/gorm" + _ "github.com/lib/pq" + _ "github.com/go-sql-driver/mysql" + _ "github.com/mattn/go-sqlite3" +) + +func init() { + 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) +} +``` + +```go +// Get database connection handle [*sql.DB](http://golang.org/pkg/database/sql/#DB) +db.DB() + +// Then you could invoke `*sql.DB`'s functions with it +db.DB().Ping() +db.DB().SetMaxIdleConns(10) +db.DB().SetMaxOpenConns(100) + +// Disable table name's pluralization +db.SingularTable(true) +``` diff --git a/doc/database/database.md b/doc/database/database.md new file mode 100644 index 00000000..ccd8d176 --- /dev/null +++ b/doc/database/database.md @@ -0,0 +1,4 @@ +## Database + + + diff --git a/doc/database/migration.md b/doc/database/migration.md new file mode 100644 index 00000000..6ff8f080 --- /dev/null +++ b/doc/database/migration.md @@ -0,0 +1,59 @@ +## Migration + + + +### Auto Migration + +Automatically migrate your schema, to keep your schema update to date + +**WARNING** AutoMigrate will ONLY create tables, columns and indexes if doesn't exist, +WON'T change existing column's type or delete unused columns to protect your data + +```go +db.AutoMigrate(&User{}) + +db.AutoMigrate(&User{}, &Product{}, &Order{}) + +// Add table suffix when create tables +db.Set("gorm:table_options", "ENGINE=InnoDB").AutoMigrate(&User{}) +``` + +### Has Table + +```go +// Check if model `User`'s table has been created or not +db.HasTable(&User{}) + +// Check table `users` exists or not +db.HasTable("users") +``` + +### Create Table + +```go +db.CreateTable(&User{}) + +db.Set("gorm:table_options", "ENGINE=InnoDB").CreateTable(&User{}) +// will append "ENGINE=InnoDB" to the SQL statement when creating table `users` +``` + +### Drop table + +```go +db.DropTable(&User{}) +``` + +### ModifyColumn + +Change column's type + +```go +// change column description's data type to `text` for model `User`'s table +db.Model(&User{}).ModifyColumn("description", "text") +``` + +### DropColumn + +```go +db.Model(&User{}).DropColumn("description") +```