Merge pull request #12 from ronenlu/migrations

docs/en-US: add migration section under ORM

docs/en-US/v2.0.x/orm/migrations.md

@@ -0,0 +1,97 @@
+---
+title: Migrations
+lang: en-US
+---
+
+# Migrations
+
+Models migrations can be generated by using the `bee` command line tool.
+
+```shell
+bee generate migration create_user_table -driver mysql
+```
+
+Then new migration file will be generated in `database/migrations` folder.
+
+```go
+package main
+
+import (
+	"github.com/beego/beego/v2/client/orm/migration"
+)
+
+// DO NOT MODIFY
+type CreateUserTable_20230928_103629 struct {
+	migration.Migration
+}
+
+// DO NOT MODIFY
+func init() {
+	m := &CreateUserTable_20230928_103629{}
+	m.Created = "20230928_103629"
+
+	migration.Register("CreateUserTable_20230928_103629", m)
+}
+
+// Run the migrations
+func (m *CreateUserTable_20230928_103629) Up() {
+	// use m.SQL("CREATE TABLE ...") to make schema update
+
+}
+
+// Reverse the migrations
+func (m *CreateUserTable_20230928_103629) Down() {
+	// use m.SQL("DROP TABLE ...") to reverse schema update
+
+}
+```
+
+Feel `Up()` and `Down()` functions with the next SQL statements.
+
+```diff
+// Run the migrations
+func (m *CreateUserTable_20230928_103629) Up() {
++	m.SQL("CREATE TABLE users(id int NOT NULL, name varchar(100) NULL, PRIMARY KEY(id));");
+}
+
+// Reverse the migrations
+func (m *CreateUserTable_20230928_103629) Down() {
++	m.SQL("DROP TABLE users")
+}
+````
+
+Then run the migration, using the `bee` command line tool.
+
+```shell
+bee migrate -driver=mysql -conn="root:pass@tcp(127.0.0.1:3306)/test" -dir="database/migrations"
+```
+`users` table will be created in `test` database.
+
+```shell
+describe users;
+
++-------+--------------+------+-----+---------+-------+
+| Field | Type         | Null | Key | Default | Extra |
++-------+--------------+------+-----+---------+-------+
+| id    | int          | NO   | PRI | <null>  |       |
+| name  | varchar(100) | YES  |     | <null>  |       |
++-------+--------------+------+-----+---------+-------+
+```
+
+
+## Atlas Integration
+[Atlas](https://atlasgo.io/) is an open-source database migration tool that has an official integration with Beego.
+
+While Beego’s [migrations](#migrations) feature works in most cases,
+the problem with creating migrations is that the `Up()` and `Down()` functions need to be filled with raw SQL statements,
+written by hand, which is error-prone and time consuming.
+
+Atlas can automatically plan database schema migrations for developers using the official [Beego Provider](https://github.com/ariga/atlas-provider-beego).
+
+After configuring the provider you can automatically plan migrations by running:
+
+```shell    
+atlas migrate diff --env beego
+```
+
+To learn how to use Atlas with Beego, check out the [official documentation](https://atlasgo.io/guides/orms/beego).

docs/en-US/v2.1.0/orm/migrations.md

@@ -0,0 +1,97 @@
+---
+title: Migrations
+lang: en-US
+---
+
+# Migrations
+
+Models migrations can be generated by using the `bee` command line tool.
+
+```shell
+bee generate migration create_user_table -driver mysql
+```
+
+Then new migration file will be generated in `database/migrations` folder.
+
+```go
+package main
+
+import (
+	"github.com/beego/beego/v2/client/orm/migration"
+)
+
+// DO NOT MODIFY
+type CreateUserTable_20230928_103629 struct {
+	migration.Migration
+}
+
+// DO NOT MODIFY
+func init() {
+	m := &CreateUserTable_20230928_103629{}
+	m.Created = "20230928_103629"
+
+	migration.Register("CreateUserTable_20230928_103629", m)
+}
+
+// Run the migrations
+func (m *CreateUserTable_20230928_103629) Up() {
+	// use m.SQL("CREATE TABLE ...") to make schema update
+
+}
+
+// Reverse the migrations
+func (m *CreateUserTable_20230928_103629) Down() {
+	// use m.SQL("DROP TABLE ...") to reverse schema update
+
+}
+```
+
+Feel `Up()` and `Down()` functions with the next SQL statements.
+
+```diff
+// Run the migrations
+func (m *CreateUserTable_20230928_103629) Up() {
++	m.SQL("CREATE TABLE users(id int NOT NULL, name varchar(100) NULL, PRIMARY KEY(id));");
+}
+
+// Reverse the migrations
+func (m *CreateUserTable_20230928_103629) Down() {
++	m.SQL("DROP TABLE users")
+}
+````
+
+Then run the migration, using the `bee` command line tool.
+
+```shell
+bee migrate -driver=mysql -conn="root:pass@tcp(127.0.0.1:3306)/test" -dir="database/migrations"
+```
+`users` table will be created in `test` database.
+
+```shell
+describe users;
+
++-------+--------------+------+-----+---------+-------+
+| Field | Type         | Null | Key | Default | Extra |
++-------+--------------+------+-----+---------+-------+
+| id    | int          | NO   | PRI | <null>  |       |
+| name  | varchar(100) | YES  |     | <null>  |       |
++-------+--------------+------+-----+---------+-------+
+```
+
+
+## Atlas Integration
+[Atlas](https://atlasgo.io/) is an open-source database migration tool that has an official integration with Beego.
+
+While Beego’s [migrations](#migrations) feature works in most cases,
+the problem with creating migrations is that the `Up()` and `Down()` functions need to be filled with raw SQL statements,
+written by hand, which is error-prone and time consuming.
+
+Atlas can automatically plan database schema migrations for developers using the official [Beego Provider](https://github.com/ariga/atlas-provider-beego).
+
+After configuring the provider you can automatically plan migrations by running:
+
+```shell    
+atlas migrate diff --env beego
+```
+
+To learn how to use Atlas with Beego, check out the [official documentation](https://atlasgo.io/guides/orms/beego).