docs: add data migration scripts section (#12975)

* docs: add data migration scripts section

* rewording

Co-authored-by: Shahed Nasser <[email protected]>

* reordering

---------

Co-authored-by: SteelRazor47 <[email protected]>
Co-authored-by: Shahed Nasser <[email protected]>

Author: SteelRazor47

www/apps/book/app/learn/fundamentals/data-models/write-migration/page.mdx

@@ -106,3 +106,67 @@ So, always rollback the migration before deleting it.
 ## More Database Commands
 
 To learn more about the Medusa CLI's database commands, refer to [this CLI reference](!resources!/medusa-cli/commands/db).
+
+---
+
+## Data Migration Scripts
+
+In some use cases, you may need to perform data migration after updates to the database. For example, after you added a `Site` data model to the Blog Module, you want to assign all existing posts and authors to a default site. Another example is updating data stored in a third-party system.
+
+In those scenarios, you can instead create a data migration script. They are asynchronous function that the Medusa application executes once when you run the `npx medusa db:migrate command`.
+
+### How to Create a Data Migration Script
+
+You can create data migration scripts in a TypeScript or JavaScript file under the `src/migration-scripts` directory. The file must export an asynchronous function that will be executed when the `db:migrate` command is executed.
+
+For example, to create a data migration script for the Blog Module example, create the file `src/migration-scripts/migrate-blog-data.ts` with the following content:
+
+export const dataMigrationHighlights = [
+  ["6", "migrateBlogData", "Function to execute when migrations are run"],
+  ["8", "isInstalled", "Confirm that the Blog Module is installed before running the workflow."],
+  ["12", "migrateBlogDataWorkflow", "Perform the data migration action."],
+]
+
+```ts title="src/migration-scripts/migrate-blog-data.ts" highlights={dataMigrationHighlights}
+import { MedusaModule } from "@medusajs/framework/modules-sdk";
+import { ExecArgs } from "@medusajs/framework/types";
+import { BLOG_MODULE } from "../modules/blog";
+import { createWorkflow } from "@medusajs/framework/workflows-sdk";
+
+export default async function migrateBlogData({ container }: ExecArgs) {
+  // Check that the blog module exists
+  if (!MedusaModule.isInstalled(BLOG_MODULE)) {
+    return
+  }
+
+  await migrateBlogDataWorkflow(container).run({})
+}
+
+const migrateBlogDataWorkflow = createWorkflow(
+  "migrate-blog-data",
+  () => {
+    // Assuming you have these steps
+    createDefaultSiteStep()
+
+    assignBlogDataToSiteStep()
+  }
+)
+```
+
+In the above example, you default export an asynchronous function that receives an object parameter with the [Medusa Container](../../medusa-container/page.mdx) property.
+
+In the function, you first ensure that the Blog Module is installed to avoid errors otherwise. Then, you run a workflow that you've created in the same file that performs the necessary data migration.
+
+#### Test Data Migration Script
+
+To test out the data migration script, run the migration command:
+
+```bash
+npx medusa db:migrate
+```
+
+Medusa will run any pending migrations and migration scripts, including your script.
+
+If the script runs successfully, Medusa won't run the script again.
+
+If there are errors in the script, you'll receive an error in the migration script logs. Medusa will keep running the script every time you run the migration command until it runs successfully.