asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: add data migration scripts section (#12975)

Browse Source 
* docs: add data migration scripts section

* rewording

Co-authored-by: Shahed Nasser <shahednasser@gmail.com>

* reordering

---------

Co-authored-by: SteelRazor47 <steelrazor47@gmail.com>
Co-authored-by: Shahed Nasser <shahednasser@gmail.com>
This commit is contained in:
SteelRazor47
2025-07-18 10:57:39 +02:00
committed by GitHub
parent 238e7d53c1
commit ed39a3742e
1 changed files with 64 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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.