doc: add short intro to the migrate apply page (#2088)

* doc: add short intro to the migrate apply page * Update doc/md/versioned/apply.mdx Co-authored-by: Jannik Clausen <12862103+masseelch@users.noreply.github.com> * Update doc/md/versioned/apply.mdx Co-authored-by: Jannik Clausen <12862103+masseelch@users.noreply.github.com> --------- Co-authored-by: Jannik Clausen <12862103+masseelch@users.noreply.github.com>
ariga · Sep 15, 2023 · 99a1ee5 · 99a1ee5
1 parent 8dcd201
commit 99a1ee5
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 11 deletions.
diff --git a/doc/md/versioned/apply.mdx b/doc/md/versioned/apply.mdx
@@ -7,19 +7,114 @@ title: Applying Migrations
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Atlas has its own migration execution engine, that works with the Atlas migration file format, e.g. migration files
-generated by [`atlas migrate diff`](/versioned/diff).
+With the `atlas migrate apply` command, users can apply pending migrations to database(s). The typical flow for introducing
+schema changes to databases is as follows: **Develop** ⇨ **Check (CI)** ⇨ **Push (CD)** ⇨ **Deploy**.
 
-### Arguments
-`atlas migrate apply` accepts one positional integer argument to specify how many pending migration files to run.
-* `atlas migrate apply` run all pending migrations
-* `atlas migrate apply 2` run at most 2 pending migrations
+1. **Develop** - Generate a migration file with the desired database changes using the [`atlas migrate diff`](/versioned/diff) command.
+2. **Check (CI)** - Use [`atlas migrate lint`](versioned/lint) to validate migrations, ensuring they don't conflict with other team members' changes
+   and align with best practices. Add Atlas to your CI pipeline in [GitHub Actions](/cloud/setup-ci) or [GitLab](/guides/ci-platforms/gitlab)
+   to review migrations files before they get merged into the main branch.
+3. **Push (Delivery)** - Use `atlas migrate push`, or set up a CI pipeline to push the latest migrations state to [Atlas Cloud](https://auth.atlasgo.cloud/signup).
+   Alternatively, you can package the migrations directory into a custom Docker image and push it to an artifactory.
+4. **Deploy** - Use `atlas migrate apply` to apply the pending migrations to your database(s).
+
+### Flags and Arguments
+
+By default, `atlas migrate apply` executes all pending migrations. However, you can pass an optional argument to limit the
+number of migrations applied. For instance, `atlas migrate apply 2` will apply up to 2 pending migrations.
+
+The following flags are required:
 
-### Flags
-When using `migrate apply` to apply migrations, users must supply multiple parameters:
 * `--url` the [URL](/concepts/url) to the database to apply migrations on.
-* `--dir` the URL of the migration directory, by default it is `file://migrations`, e.g a
- directory named `migrations` in the current working directory.
+* `--dir` the URL to the migration directory. It defaults to `file://migrations`.
+
+:::info Reading remote directories
+Users who have connected or pushed their migration directories to Atlas Cloud can read the migrations state directly from
+there without needing to have them locally. For example, `atlas migrate apply --dir "atlas://app"` will apply the pending
+migrations of the `app` project based on the most recent pushed state. To see it in action, run the following:
+
+**Login** or signup:
+```shell
+atlas login
+```
+
+**Push** a local migration directory and name it `app`:
+<Tabs>
+<TabItem value="postgres" label="PostgreSQL">
+
+```bash
+atlas migrate push app \
+  --dev-url "docker://postgres/15/dev?search_path=public"
+```
+
+</TabItem>
+<TabItem value="mysql" label="MySQL">
+
+```bash
+atlas migrate push app \
+  --dev-url "docker://mysql/8/dev"
+```
+
+</TabItem>
+<TabItem value="maria" label="Maria">
+
+```bash
+atlas migrate push app \
+  --dev-url "docker://mariadb/latest/dev"
+```
+
+</TabItem>
+<TabItem value="sqlite" label="SQLite">
+
+```bash
+atlas migrate push app \
+  --dev-url "sqlite://dev?mode=memory"
+```
+
+</TabItem>
+</Tabs>
+
+
+**Deploy** to a local database the remote migration directory named `app`:
+<Tabs>
+<TabItem value="postgres" label="PostgreSQL">
+
+```bash
+atlas migrate apply \
+  --dir "atlas://app" \
+  --url "postgres://postgres:pass@:5432/example?search_path=public&sslmode=disable"
+```
+
+</TabItem>
+<TabItem value="mysql" label="MySQL">
+
+```bash
+atlas migrate apply \
+  --dir "atlas://app" \
+  --url "mysql://root:pass@:3306/example"
+```
+
+</TabItem>
+<TabItem value="maria" label="Maria">
+
+```bash
+atlas migrate apply \
+  --dir "atlas://app" \
+  --url "maria://root:pass@:3306/example"
+```
+
+</TabItem>
+<TabItem value="sqlite" label="SQLite">
+
+```bash
+atlas migrate apply \
+  --dir "atlas://app" \
+  --url "sqlite://example.db"
+```
+
+</TabItem>
+</Tabs>
+:::
 
 ### Schema Revision Information
 

diff --git a/doc/md/versioned/intro.mdx b/doc/md/versioned/intro.mdx
@@ -141,7 +141,7 @@ h1:kGsXTVLtL0vs9Un8aaGKwMHZ2iMibgTQxwyAt7+Elcw=
 
 Now that we have our first migration, we can apply it to a database. There are multiple ways to accomplish this, with
 most methods covered in the [guides](/guides) section. In this example, we'll demonstrate how to push migrations to
-Atlas Cloud, much like how Docker images are pushed to Docker Hub.
+[Atlas Cloud](https://auth.atlasgo.cloud/signup), much like how Docker images are pushed to Docker Hub.
 
 <div style={{textAlign: 'center'}}>
     <img src="https://atlasgo.io/uploads/versioned/migrate-push1.jpg" alt="atlas migrate push" width="100%"/>