|
| 1 | +export const metadata = { |
| 2 | + title: `Cloud Best Practices: Update Medusa Application`, |
| 3 | +} |
| 4 | + |
| 5 | +# {metadata.title} |
| 6 | + |
| 7 | +In this guide, you'll learn how to update your Medusa application that is deployed on Cloud. |
| 8 | + |
| 9 | +<Note title="Looking for the general update guide?"> |
| 10 | + |
| 11 | +Refer to the [Update guide](!docs!/learn/update) to learn how to update your Medusa application. |
| 12 | + |
| 13 | +</Note> |
| 14 | + |
| 15 | +## Why Update Your Medusa Application? |
| 16 | + |
| 17 | +Medusa regularly releases new versions of the core application with bug fixes, performance improvements, and new features. |
| 18 | + |
| 19 | +It's highly recommended to always keep your Medusa application up to date. You'll benefit from the latest improvements and security patches. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Update Your Deployed Medusa Application |
| 24 | + |
| 25 | +This section provides best practices for updating your Medusa application on Cloud and how to update your application in a safe manner. |
| 26 | + |
| 27 | +### Don't Push Directly to Production |
| 28 | + |
| 29 | +It's **strongly discouraged** to push a new update directly to your production branch. While Medusa updates are generally safe and stable, it's always a good practice to test the update in a separate environment before deploying it to production. |
| 30 | + |
| 31 | +By using a separate environment, you mitigate any unexpected issues that may arise during the update process. This way, you ensure that your customizations and configurations work correctly with the new version of Medusa. |
| 32 | + |
| 33 | +The **recommended** approach is to [create a long-lived environment](../environments/page.mdx#create-a-long-lived-environment), such as Staging. You can push the new update and test it thoroughly in a production-like environment before deploying it to production. |
| 34 | + |
| 35 | +<Note title="Tip"> |
| 36 | + |
| 37 | +Each environment has its own database, so you can safely update other environments and make data changes without affecting the production environment. |
| 38 | + |
| 39 | +</Note> |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +Alternatively, you can open a pull request to the production branch, which will [create a preview environment](../environments/page.mdx#preview-environments). The preview environment allows you to test the update before merging it into the production branch. |
| 44 | + |
| 45 | + |
| 46 | + |
| 47 | +### Ensure Custom Migrations Have Rollback Methods |
| 48 | + |
| 49 | +When creating custom migrations, it's important to include both `up` and `down` methods. The `up` method should define the changes to be made to the database schema, while the `down` method should reverse those changes. |
| 50 | + |
| 51 | +By including both methods, you can easily roll back database changes if you need to revert the application's update. |
| 52 | + |
| 53 | +If you use the [db\:generate](!resources!/medusa-cli/commands/db#dbgenerate) command to generate migrations, it will automatically create both `up` and `down` methods for you. If you're creating the migrations manually, you can learn more in the [Migrations](!docs!/learn/fundamentals/data-models/write-migration) guide. |
| 54 | + |
| 55 | +### Update Your Medusa Application |
| 56 | + |
| 57 | +To update your Medusa application deployed on Cloud: |
| 58 | + |
| 59 | +1. Update your Medusa application locally either on the long-lived environment's branch (for example, Staging) or in a new branch that will be used to create a pull request. |
| 60 | + - To learn how to update your Medusa application, refer to the [Update guide](!docs!/learn/update). It includes all the details you need to update the Medusa application locally. |
| 61 | +2. Once you're done updating your application locally, push the changes in `package.json`, lock file (for example, `yarn.lock`), and any other affected files to the branch. |
| 62 | + - If you're using a long-lived environment, Cloud will automatically deploy the changes to the branch's environment. |
| 63 | + - If you're using a new branch to create a pull request, open the pull request to the production branch. This will create a preview environment that you can use to test the update before merging it into the production branch. |
| 64 | + |
| 65 | +Then, you can access the environment's [live deployment](../deployments/page.mdx#access-live-deployment) to test the update. You can also use the [build](../logs/page.mdx#view-build-logs) and [runtime](../logs/page.mdx#view-runtime-logs) logs of the environment to debug any issues that occur during the update process or testing. |
| 66 | + |
| 67 | +### Push Update to Production |
| 68 | + |
| 69 | +Once you've thoroughly tested the update in your long-lived or preview environment, you can merge the changes into your production branch. |
| 70 | + |
| 71 | +Cloud will automatically deploy the changes to the production environment. This will update the production's code and database. |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +## Rollback Medusa Application Update |
| 76 | + |
| 77 | +If you encounter any issues after updating your deployed Medusa application, you can [redeploy a previous deployment](../deployments/page.mdx#redeploy-a-deployment) to roll back the code changes made by the update. |
| 78 | + |
| 79 | +However, redeploying a previous deployment will not roll back the database changes made by the update. If you need to roll back the database changes, [contact support](../support/page.mdx) for assistance. |
0 commit comments