How Does PayloadCMS Support the Expand, Migrate, and Contract (EMC) Pattern?

[SychMusti]

Introduction

The Expand, Migrate, and Contract (EMC) pattern is a widely adopted strategy for making safe and backward-compatible database schema changes. It ensures smooth transitions without downtime or breaking existing functionality. I am interested in understanding how PayloadCMS supports this pattern and how the community implements it for migrations.

Questions for the Community

• How does PayloadCMS facilitate the Expand, Migrate, and Contract (EMC) pattern in your experience?
• What are your best practices for performing migrations in PayloadCMS while ensuring minimal downtime?
• Have you faced any challenges when following this pattern in PayloadCMS, and how did you overcome them?
• Do you use PayloadCMS’s migration system as-is, or do you integrate additional tools to manage schema changes?

Looking forward to your insights and experiences!

[jakenorthey]

When using relational databases like PostGres with Payload, we are finding that it is essential to use the EMC pattern. As an example say you have a field: body which is of type text:

{
    name: 'body',
    type: 'text',
}

If you decide that body needs to be richText and try to generate a migration, the migration will fail as the varchar column cannot be converted directly to jsonb.

{
      name: 'body',
      type: 'richText',
      editor: lexicalEditor(),
},

What needs to happen is that you add a temporary column bodyRich in a migration, create a custom migration to migrate existing data over to bodyRich from body, then drop body, and rename bodyRich to body. These types of changes need to follow the EMC pattern.