Skip to content

# Update pgflow

This guide explains how to update pgflow to the latest version, including package updates and database migrations. pgflow updates involve two main components that need to be updated together.

Unified Versioning

All pgflow packages (npm and jsr) are versioned together. When you update one pgflow package, all others should be updated to the same version to maintain compatibility.

## What needs to be updated?

Section titled “What needs to be updated?”

When updating pgflow, you need to update:

1. npm packages - CLI, core libraries, client, and DSL packages
2. JSR package - The Edge Worker package (published to JSR registry)
3. Database migrations - Schema and function updates

## Update Process

Section titled “Update Process”

### 1. Update npm packages

Section titled “1. Update npm packages”

Update all pgflow npm packages to the latest version:

    npm update @pgflow/client # or @pgflow/dsl, @pgflow/core etc.

Or if using yarn:

    yarn upgrade @pgflow/client # or @pgflow/dsl, @pgflow/core etc.

Or if using pnpm:

    pnpm update @pgflow/client # or @pgflow/dsl, @pgflow/core etc.

### 2. Update Edge Worker (JSR package)

Section titled “2. Update Edge Worker (JSR package)”

Update the Edge Worker package in your JSR imports. In your Edge Function files, update the import:

    // Beforeimport { EdgeWorker } from "jsr:@pgflow/edge-worker@^0.5.0";
    // After (replace with latest version)import { EdgeWorker } from "jsr:@pgflow/edge-worker@^0.6.0";

### 3. Run pgflow install to update migrations

Section titled “3. Run pgflow install to update migrations”

Always run the install command after updating packages to check for and apply new database migrations:

    npx pgflow@latest install

Use @latest

Always use `npx pgflow@latest install` to ensure you’re running the install command from the latest version. This guarantees you get any new migrations that were added in the update.

The install command will:

- Detect any new migrations that need to be installed
- Copy new migrations with timestamps that place them after your existing migrations
- Skip migrations that are already installed
- Show you exactly which migrations will be added before proceeding

### 4. Apply configuration changes (if needed)

Section titled “4. Apply configuration changes (if needed)”

If the installer made configuration changes, restart your Supabase instance:

    npx supabase stopnpx supabase start

### 5. Apply new migrations

Section titled “5. Apply new migrations”

Apply the new migrations to your database:

    npx supabase migrations up

## Understanding Migration Timestamps

Section titled “Understanding Migration Timestamps”

pgflow uses a simple but effective migration system to ensure migrations are applied correctly:

How Migration Prefixing Works

pgflow uses a simple but effective trick with two timestamps: it keeps the original filename in the migration it creates in your project, so it can search for already-installed migrations, while prefixing with a new timestamp that ensures the migration appears as the newest in your Supabase migrations folder. This prevents Supabase from complaining about applying migrations with timestamps older than already-applied ones.

For example, a pgflow migration `20250429164909_pgflow_initial.sql` might be installed as `20250430000010_20250429164909_pgflow_initial.sql` in your project.

### Migration Naming Convention

Section titled “Migration Naming Convention”

pgflow migrations follow this naming pattern when installed:

    [NEW_TIMESTAMP]_[ORIGINAL_TIMESTAMP]_[ORIGINAL_NAME].sql

Where:

- `NEW_TIMESTAMP` - Generated timestamp that makes this the newest migration in your folder
- `ORIGINAL_TIMESTAMP` - The original pgflow migration timestamp
- `ORIGINAL_NAME` - The original migration file name

The original timestamp allows pgflow to search for and detect which migrations have already been installed, while the new timestamp prefix ensures Supabase can apply the migration without timestamp ordering errors.

## Troubleshooting Updates

Section titled “Troubleshooting Updates”

### No migrations to install

Section titled “No migrations to install”

If `pgflow install` reports “All pgflow migrations are already in place”, this means:

- You already have the latest migrations installed
- No database schema updates are needed for this version
- You can proceed with using the updated packages

### Version mismatches

Section titled “Version mismatches”

If you encounter issues after updating, verify all packages are on the same version:

    npm list | grep pgflow

All pgflow packages should show the same version number.

### Migration conflicts

Section titled “Migration conflicts”

If you encounter migration conflicts:

1. Check if you have custom migrations that conflict with pgflow schema
2. Review the migration files in `supabase/migrations/` for any obvious conflicts
3. Consider using the manual installation approach for more granular control

## Best Practices

Section titled “Best Practices”

Recommended Update Workflow

1. Update packages first
2. Always run `npx pgflow@latest install` after updating
3. Review what migrations will be installed before confirming
4. Test your flows after updating to ensure compatibility
5. Keep all pgflow packages on the same version

### When to update

Section titled “When to update”

Pre-1.0 Versioning

Until pgflow reaches 1.0 (production-ready), we use a modified versioning scheme:

- Patch releases (0.5.1 → 0.5.2) - Bug fixes and small backward-compatible features
- Minor releases (0.5.0 → 0.6.0) - Breaking changes and major updates
- Major release (0.x.x → 1.x.x) - Production-ready milestone

- Patch releases - Safe to update immediately, include bug fixes and small backward-compatible improvements
- Minor releases - Review changelog carefully as these may contain breaking changes
- Major release to 1.0 - Production-ready milestone, will include comprehensive migration guide

### Staying informed

Section titled “Staying informed”

- Check the pgflow releases page for release notes
- Review changelog files for detailed changes
- Test updates in a development environment first

## Development vs Production

Section titled “Development vs Production”

### Development Environment

Section titled “Development Environment”

In development, you can update frequently to take advantage of new features and bug fixes:

    npm update @pgflow/cli @pgflow/core @pgflow/client @pgflow/dslnpx pgflow@latest install -y  # Auto-confirm for faster developmentnpx supabase migrations up

### Production Environment

Section titled “Production Environment”

For production updates, follow a more careful approach:

1. Test the update in a staging environment first
2. Review all new migrations carefully
3. Plan for any necessary downtime
4. Keep backups of your database before applying migrations
5. Monitor your workflows after updating

Production Considerations

Always test pgflow updates in a non-production environment first. While pgflow migrations are designed to be safe, any database schema change carries inherent risks in production systems.

Your pgflow installation is now updated with the latest features, bug fixes, and database schema improvements!