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.

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

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

Directorysupabase/functions/
- Directory_tasks/
  - fetchUserData.ts
  - sendEmail.ts
- Directory_flows/
  - greet_user.ts
  - greet_user_v2.ts // 👈 new

Create new flow file

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

Compile it

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

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

Run migration
```
npx supabase migrations up --local
```

Old version stays live; new one is separate.

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

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.