From b7ae4ee60a822b977b9b13856abd1e53b4d50eb9 Mon Sep 17 00:00:00 2001 From: Jessica Rynkar <67977755+jessrynkar@users.noreply.github.com> Date: Tue, 29 Apr 2025 13:23:49 +0100 Subject: [PATCH] docs: adds warning about handling different environments with migrations (#12249) ### What? Migrating configs that include environment specific options can cause issues and confusion for users. ### How? Adds new section to `database/migrations` docs to highlight potential issues with environment-specific settings when generating and running migrations and includes some recommendations for addressing these issues. Closes #12241 --- docs/database/migrations.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/database/migrations.mdx b/docs/database/migrations.mdx index 2281412015..a0d96d72e5 100644 --- a/docs/database/migrations.mdx +++ b/docs/database/migrations.mdx @@ -298,3 +298,15 @@ Passing your migrations as shown above will tell Payload, in production only, to may slow down serverless cold starts on platforms such as Vercel. Generally, this option should only be used for long-running servers / containers. + +## Environment-Specific Configurations and Migrations + +Your configuration may include environment-specific settings (e.g., enabling a plugin only in production). If you generate migrations without considering the environment, it can lead to discrepancies and issues. When running migrations locally, Payload uses the development environment, which might miss production-specific configurations. Similarly, running migrations in production could miss development-specific entities. + +This is an easy oversight, so be mindful of any environment-specific logic in your config when handling migrations. + +**Ways to address this:** + +- Manually update your migration file after it is generated to include any environment-specific configurations. +- Temporarily enable any required production environment variables in your local setup when generating the migration to capture the necessary updates. +- Use separate migration files for each environment to ensure the correct migration is executed in the corresponding environment.