snapshot of https://github.com/ent/ent.git (master, 2026-09-15; blobs > 131072B omitted)

doc/md/versioned/04-new-migration.mdx

@@ -0,0 +1,129 @@
+---
+title: Planning a Migration
+id: new-migration
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::info Supporting repository
+
+The change described in this section can be found in
+[PR #6](https://github.com/rotemtam/ent-versioned-migrations-demo/pull/6/files)
+in the supporting repository.
+
+:::
+
+
+## Planning a migration
+
+In this section, we will discuss how to plan a new schema migration when we
+make a change to our project's Ent schema. Consider we want to add a new field
+to our `User` entity, adding a new optional field named `title`:
+
+```go title=ent/schema/user.go
+// Fields of the User.
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		field.String("name"),
+		field.String("email"). // <-- Our new field
+            Unique(),
+        // highlight-start
+		field.String("title").
+            Optional(),
+        // highlight-end
+	}
+}
+```
+
+After adding the new field, we need to rerun code-gen for our project:
+
+```shell
+go generate ./...
+```
+
+Next, we need to create a new migration file for our change using the Atlas CLI:
+
+
+<Tabs
+defaultValue="mysql"
+values={[
+{label: 'MySQL', value: 'mysql'},
+{label: 'MariaDB', value: 'maria'},
+{label: 'PostgreSQL', value: 'postgres'},
+{label: 'SQLite', value: 'sqlite'},
+]}>
+<TabItem value="mysql">
+
+```shell
+atlas migrate diff add_user_title \
+  --dir "file://ent/migrate/migrations" \
+  --to "ent://ent/schema" \
+  --dev-url "docker://mysql/8/ent"
+```
+
+</TabItem>
+<TabItem value="maria">
+
+```shell
+atlas migrate diff add_user_title \
+  --dir "file://ent/migrate/migrations" \
+  --to "ent://ent/schema" \
+  --dev-url "docker://mariadb/latest/test"
+```
+
+</TabItem>
+<TabItem value="postgres">
+
+```shell
+atlas migrate diff add_user_title \
+  --dir "file://ent/migrate/migrations" \
+  --to "ent://ent/schema" \
+  --dev-url "docker://postgres/15/test?search_path=public"
+```
+
+</TabItem>
+<TabItem value="sqlite">
+
+```shell
+atlas migrate diff add_user_title \
+  --dir "file://ent/migrate/migrations" \
+  --to "ent://ent/schema" \
+  --dev-url "sqlite://file?mode=memory&_fk=1"
+```
+
+</TabItem>
+</Tabs>
+
+Observe a new file named `20221115101649_add_user_title.sql` was created under
+the `ent/migrate/migrations/` directory. This file contains the SQL statements
+to create the newly added `title` field in the `users` table:
+
+```sql title=ent/migrate/migrations/20221115101649_add_user_title.sql
+-- modify "users" table
+ALTER TABLE `users` ADD COLUMN `title` varchar(255) NULL;
+```
+
+Great! We've successfully used the Atlas CLI to automatically
+generate a new migration file for our change.
+
+To apply the migration, we can run the following command:
+
+```shell
+atlas migrate apply --dir file://ent/migrate/migrations --url mysql://root:pass@localhost:3306/db
+```
+Atlas reports:
+```shell
+Migrating to version 20221115101649 from 20221114165732 (1 migrations in total):
+
+  -- migrating version 20221115101649
+    -> ALTER TABLE `users` ADD COLUMN `title` varchar(255) NULL;
+  -- ok (36.152277ms)
+
+  -------------------------
+  -- 44.1116ms
+  -- 1 migrations
+  -- 1 sql statements
+```
+
+In the next section, we will discuss how to plan custom schema migrations for our project.