docs: revise main docs outline (#10502)

2024-12-09 13:54:42 +02:00
parent c8cb9b5c1a
commit 0ae98c51eb
141 changed files with 814 additions and 1181 deletions
@@ -0,0 +1,88 @@
+export const metadata = {
+  title: `${pageNumber} Write Migration`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to create a migration and write it manually.
+
+## What is a Migration?
+
+A migration is a class created in a TypeScript or JavaScript file under a module's `migrations` directory. It has two methods:
+
+- The `up` method reflects changes on the database.
+- The `down` method reverts the changes made in the `up` method.
+
+---
+
+## How to Write a Migration?
+
+The Medusa CLI tool provides a [db:generate](!resources!/medusa-cli/commands/db#dbgenerate) command to generate a migration for the specified modules' data models.
+
+Alternatively, you can manually create a migration file under the `migrations` directory of your module.
+
+For example:
+
+```ts title="src/modules/hello/migrations/Migration20240429.ts"
+import { Migration } from "@mikro-orm/migrations"
+
+export class Migration20240702105919 extends Migration {
+
+  async up(): Promise<void> {
+    this.addSql("create table if not exists \"my_custom\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"my_custom_pkey\" primary key (\"id\"));")
+  }
+
+  async down(): Promise<void> {
+    this.addSql("drop table if exists \"my_custom\" cascade;")
+  }
+
+}
+```
+
+The migration's file name should be of the format `Migration{YEAR}{MONTH}{DAY}.ts`. The migration class in the file extends the `Migration` class imported from `@mikro-orm/migrations`.
+
+In the `up` and `down` method of the migration class, you use the `addSql` method provided by MikroORM's `Migration` class to run PostgreSQL syntax.
+
+In the example above, the `up` method creates the table `my_custom`, and the `down` method drops the table if the migration is reverted.
+
+<Note title="Tip">
+
+Refer to [MikroORM's documentation](https://mikro-orm.io/docs/migrations#migration-class) for more details on writing migrations.
+
+</Note>
+
+---
+
+## Run the Migration
+
+To run your migration, run the following command:
+
+<Note>
+
+This command also syncs module links. If you don't want that, use the `--skip-links` option.
+
+</Note>
+
+```bash
+npx medusa db:migrate
+```
+
+This reflects the changes in the database as implemented in the migration's `up` method.
+
+---
+
+## Rollback the Migration
+
+To rollback or revert the last migration you ran for a module, run the following command:
+
+```bash
+npx medusa db:rollback helloModuleService
+```
+
+This rolls back the last ran migration on the Hello Module.
+
+---
+
+## More Database Commands
+
+To learn more about the Medusa CLI's database commands, refer to [this CLI reference](!resources!/medusa-cli/commands/db).