Version flows

When you need to update a flow’s structure or add new steps, create a new flow version with a unique slug. This approach keeps existing runs safe while allowing you to deploy new functionality.

Flow immutability

Flows are immutable by design. Once registered in the database, their structure cannot be modified to protect running workflows and maintain data integrity.

Changing flow shape requires a new flow definition with a unique flow_slug. Use pgflow compile to generate the proper migration.

Prohibited Changes

Never modify these in an existing flow:

• Step slugs
• Dependencies between steps
• Adding or removing steps
• Altering the flow’s input type structure

They break active runs and corrupt data.

Safe vs. breaking changes

Safe (No New Version Needed)	Breaking (Requires New Version)
✅ Modifying step handler code	❌ Adding/removing steps
✅ Adjusting retry parameters	❌ Changing step dependencies
✅ Updating timeout values	❌ Modifying input/output types
✅ Bug fixes within handlers	❌ Changing step slug names

Create a new version

Put the new flow in its own file with a versioned slug.

• Directorysupabase/

  • Directoryflows/

    • greet-user.ts
    • greet-user-v2.ts // new version
    • index.ts
  • Directorytasks/

    • fetchUserData.ts
    • sendEmail.ts

1. Create new flow file

   supabase/flows/greet-user-v2.ts

   export const GreetUserV2 = new Flow<Input>({
     slug: 'greetUserV2',
     // ...new configuration and step definitions
   })

   Then add it to supabase/flows/index.ts:

   export { GreetUserV2 } from './greet-user-v2.ts';

2. Compile it

   Compile the new flow to SQL to generate a migration file:

   npx pgflow@latest compile greetUserV2

3. Run migration

   npx supabase migrations up --local

Old version stays live; new one is separate.

See Also

Delete flow and its data Development cleanup

Tune deployed flows Adjust production flow settings