rewording

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

Author: SteelRazor47

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

@@ -105,9 +105,9 @@ So, always rollback the migration before deleting it.
 
 ## Data Migration Scripts
 
-Some features might require data migrations to ensure new functionality works as expected after an upgrade. Typically, these migrations can be dealt with by database migrations within a module. However, this is not the case when the changes affect the data models in several modules or if the data is stored in a third-party system. In those scenarios, the data needs to be brought to the desired state.
+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.
 
-To do so, you can use data migration scripts. They are very similar to regular scripts, in the sense that you have access to the dependency container, i.e. all modules. However, instead of running manually, data migration scripts are run automatically as part of running `medusa db:migrate`.
+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 they work
 
@@ -125,26 +125,62 @@ The flow is as follows:
   - Mark script as finished
 - Release lock
 
-### Example
+### How to Create a Data Migration Script
 
-```ts title="src/migration-scripts/example.tsx"
-import { MedusaModule } from "@medusajs/framework/modules-sdk"
-import { ExecArgs } from "@medusajs/framework/types"
-import { Modules } from "@medusajs/framework/utils"
+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.
 
-export default async function migrationScript({
-  container,
-}: ExecArgs) {
-  // Check if the required modules are present
-  if (!MedusaModule.isInstalled(Modules.PRODUCT))
+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
-  
-  // Migrate data
-  await migrateDataWorkflow(container).run(...)
+  }
 
+  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.
+
 ---
 
 ## More Database Commands