Skip to content

# 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

Section titled “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

Section titled “Safe vs. breaking changes”

✅ Modifying step implementation | ❌ Adding/removing steps
✅ Adjusting retry parameters | ❌ Changing step dependencies
✅ Updating timeout values | ❌ Modifying input/output types
✅ Bug fixes within steps | ❌ Changing step slug names

## Create a new version

Section titled “Create a new version”

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

- Directory
  supabase/functions/
  - Directory
    _tasks/
    - fetchUserData.ts
    - sendEmail.ts
  - Directory
    _flows/
    - greet_user.ts
    - greet_user_v2.ts // 👈 new

1. Create new flow file

   supabase/functions/_flows/greet_user_v2.ts

       export default new Flow<Input>({  slug: 'greet_user_v2',  // ...new configuration and step definitions})

2. Compile it

   Compile the new flow to SQL which generates a migration file:

       npx pgflow@latest compile supabase/functions/_flows/greet_user_v2.ts

3. Run migration

       npx supabase migrations up --local

Old version stays live; new one is separate.

## Update runtime settings

Section titled “Update runtime settings”

For simple configuration changes like retry counts or timeouts, update the database directly without creating a new version.

See the updating flow options for SQL commands to modify runtime settings safely.

## Development reset

Section titled “Development reset”

In development, you can delete the entire flow to start fresh when testing structural changes. This permanently removes all flow data and should never be used in production.

## See Also

Section titled “See Also”
Delete flow and its data Delete flow & data
Update flow options Change options via SQL