diff --git a/doc/md/components/_atlas_migrate_apply.mdx b/doc/md/components/_atlas_migrate_apply.mdx
new file mode 100644
index 000000000..af30b44cf
--- /dev/null
+++ b/doc/md/components/_atlas_migrate_apply.mdx
@@ -0,0 +1,48 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "mysql://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "maria://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "sqlite://file.db?_fk=1"
+```
+
+
+
diff --git a/doc/md/components/_atlas_migrate_diff.mdx b/doc/md/components/_atlas_migrate_diff.mdx
new file mode 100644
index 000000000..2d00b304d
--- /dev/null
+++ b/doc/md/components/_atlas_migrate_diff.mdx
@@ -0,0 +1,52 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+
+```shell
+atlas migrate diff migration_name \
+ --dir "file://ent/migrate/migrations" \
+ --to "ent://ent/schema" \
+ --dev-url "docker://mysql/8/ent"
+```
+
+
+
+
+```shell
+atlas migrate diff migration_name \
+ --dir "file://ent/migrate/migrations" \
+ --to "ent://ent/schema" \
+ --dev-url "docker://mariadb/latest/test"
+```
+
+
+
+
+```shell
+atlas migrate diff migration_name \
+ --dir "file://ent/migrate/migrations" \
+ --to "ent://ent/schema" \
+ --dev-url "docker://postgres/15/test?search_path=public"
+```
+
+
+
+
+```shell
+atlas migrate diff migration_name \
+ --dir "file://ent/migrate/migrations" \
+ --to "ent://ent/schema" \
+ --dev-url "sqlite://file?mode=memory&_fk=1"
+```
+
+
+
\ No newline at end of file
diff --git a/doc/md/components/_installation_instructions.mdx b/doc/md/components/_installation_instructions.mdx
new file mode 100644
index 000000000..e2f970e05
--- /dev/null
+++ b/doc/md/components/_installation_instructions.mdx
@@ -0,0 +1,61 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+To install the latest release of Atlas, simply run one of the following commands in your terminal, or check out the
+[Atlas website](https://atlasgo.io/getting-started#installation):
+
+
+
+
+```shell
+curl -sSf https://atlasgo.sh | sh
+```
+
+
+
+
+```shell
+brew install ariga/tap/atlas
+```
+
+
+
+
+```shell
+go install ariga.io/atlas/cmd/atlas@master
+```
+
+
+
+
+```shell
+docker pull arigaio/atlas
+docker run --rm arigaio/atlas --help
+```
+
+If the container needs access to the host network or a local directory, use the `--net=host` flag and mount the desired
+directory:
+
+```shell
+docker run --rm --net=host \
+ -v $(pwd)/migrations:/migrations \
+ arigaio/atlas migrate apply
+ --url "mysql://root:pass@:3306/test"
+```
+
+
+
+
+Download the [latest release](https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe) and
+move the atlas binary to a file location on your system PATH.
+
+
+
\ No newline at end of file
diff --git a/doc/md/getting-started.mdx b/doc/md/getting-started.mdx
index e9a987f56..7d67f4fea 100644
--- a/doc/md/getting-started.mdx
+++ b/doc/md/getting-started.mdx
@@ -6,6 +6,8 @@ sidebar_label: Quick Introduction
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
+import AtlasMigrateDiff from './components/_atlas_migrate_diff.mdx';
+import AtlasMigrateApply from './components/_atlas_migrate_apply.mdx';
**ent** is a simple, yet powerful entity framework for Go, that makes it easy to build
and maintain applications with large data-models and sticks with the following principles:
@@ -649,6 +651,44 @@ Now when we have a graph with data, we can run a few queries on it:
}
```
+## Schema Migration
+
+Ent provides two approaches for running schema migrations: [Automatic Migrations](/docs/migrate) and
+[Versioned migrations](/docs/versioned-migrations). Here is a brief overview of each approach:
+
+### Automatic Migrations
+
+With Automatic Migrations, users can use the following API to keep the database schema aligned with the schema objects
+defined in the generated SQL schema `ent/migrate/schema.go`:
+```go
+if err := client.Schema.Create(ctx); err != nil {
+ log.Fatalf("failed creating schema resources: %v", err)
+}
+```
+
+This approach is mostly useful for prototyping, development, or testing. Therefore, it is recommended to use the
+_Versioned Migration_ approach for mission-critical production environments. By using versioned migrations, users know
+beforehand what changes are being applied to their database, and can easily tune them depending on their needs.
+
+Read more about this approach in the [Automatic Migration](/docs/migrate) documentation.
+
+### Versioned Migrations
+
+Unlike _Automatic Migrations_, the _Version Migrations_ approach uses Atlas to automatically generate a set of migration
+files containing the necessary SQL statements to migrate the database. These files can be edited to meet specific needs
+and applied using existing migration tools like Atlas, golang-migrate, Flyway, and Liquibase. The API for this approach
+involves two primary steps.
+
+#### Generating migrations
+
+
+
+#### Applying migrations
+
+
+
+Read more about this approach in the [Versioned Migrations](/docs/versioned-migrations) documentation.
+
## Full Example
The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/start).
diff --git a/doc/md/versioned-migrations.mdx b/doc/md/versioned-migrations.mdx
index f65b3a4cb..26a3bfbd2 100644
--- a/doc/md/versioned-migrations.mdx
+++ b/doc/md/versioned-migrations.mdx
@@ -5,13 +5,141 @@ title: Versioned Migrations
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
+import InstallationInstructions from './components/_installation_instructions.mdx';
+import AtlasMigrateDiff from './components/_atlas_migrate_diff.mdx';
+import AtlasMigrateApply from './components/_atlas_migrate_apply.mdx';
+
+## Quick Guide
+
+Here are a few quick steps that explain how to auto-generate and execute migration files against a database. For
+a more in-depth explanation, continue reading the [next section](#in-depth-guide).
+
+### Generating migrations
+
+
+
+Then, run the following command to automatically generate migration files for your Ent schema:
+
+
+
+:::info The role of the [dev database](https://atlasgo.io/concepts/dev-database)
+Atlas loads the **current state** by executing the SQL files stored in the migration directory onto the provided
+[dev database](https://atlasgo.io/concepts/dev-database). It then compares this state against the **desired state**
+defined by the `ent/schema` package and writes a migration plan for moving from the current state to the desired state.
+:::
+
+### Applying migrations
+
+
+
+To apply the pending migration files onto the database, run the following command:
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "mysql://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "maria://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
+```
+
+
+
+
+```shell
+atlas migrate apply \
+ --dir "file://ent/migrate/migrations" \
+ --url "sqlite://file.db?_fk=1"
+```
+
+
+
+
+For more information head over to the [Atlas documentation](https://atlasgo.io/versioned/apply).
+
+### Migration status
+
+Use the following command to get detailed information about the migration status of the connected database:
+
+
+
+
+```shell
+atlas migrate status \
+ --dir "file://ent/migrate/migrations" \
+ --url "mysql://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate status \
+ --dir "file://ent/migrate/migrations" \
+ --url "maria://root:pass@localhost:3306/example"
+```
+
+
+
+
+```shell
+atlas migrate status \
+ --dir "file://ent/migrate/migrations" \
+ --url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
+```
+
+
+
+
+```shell
+atlas migrate status \
+ --dir "file://ent/migrate/migrations" \
+ --url "sqlite://file.db?_fk=1"
+```
+
+
+
+
+## In Depth Guide
If you are using the [Atlas](https://github.com/ariga/atlas) migration engine, you are able to use the versioned
migration workflow. Instead of applying the computed changes directly to the database, Atlas generates a set
of migration files containing the necessary SQL statements to migrate the database. These files can then be edited to
your needs and be applied by many existing migration tools, such as golang-migrate, Flyway, and Liquibase.
-## Generating Versioned Migration Files
+### Generating Versioned Migration Files
As mentioned above, versioned migrations only work if the new [Atlas](https://atlasgo.io) based migration engine is
used. Migration files are generated by computing the difference between two **states**. We call the state reflected by
@@ -468,68 +596,10 @@ Let's run `atlas migrate lint` with the necessary parameters to run migration li
#### Install Atlas:
-To install the latest release of Atlas, simply run one of the following in your terminal, or check out the
-[Atlas website](https://atlasgo.io/getting-started#installation):
-
-
-
-
-```shell
-curl -sSf https://atlasgo.sh | sh
-```
-
-
-
-
-```shell
-brew install ariga/tap/atlas
-```
-
-
-
-
-```shell
-go install ariga.io/atlas/cmd/atlas@master
-```
-
-
-
-
-```shell
-docker pull arigaio/atlas
-docker run --rm arigaio/atlas --help
-```
-
-If the container needs access to the host network or a local directory, use the `--net=host` flag and mount the desired
-directory:
-
-```shell
-docker run --rm --net=host \
- -v $(pwd)/migrations:/migrations \
- arigaio/atlas migrate apply
- --url "mysql://root:pass@:3306/test"
-```
-
-
-
-
-Download the [latest release](https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe) and
-move the atlas binary to a file location on your system PATH.
-
-
-
+
#### Run the `atlas migrate lint` command:
-