Rollback Guide - Activepieces

Overview

Activepieces ships a rollback command that reverses database migrations when you need to downgrade to a previous version. Most releases are fully rollback-safe — the release notes will let you know if one isn't.

Backups

For most upgrades you won't need a backup, but if you want to be extra safe:

PostgreSQL

bash

pg_dump -Fc $DATABASE_URL > backup-pre-upgrade.dump

PGLite

Copy the pglite folder inside your configured AP_CONFIG_PATH:

bash

cp -r /path/to/config/pglite /path/to/config/pglite-backup

Release Notes

Releases that include non-reversible database changes will have a note at the bottom of the release notes mentioning which migrations are affected. If you don't see a note, the release is rollback-safe.

Rolling Back

The rollback command runs against the current (newer) image since it has the migration reversal logic. After rolling back the database, you swap to the older image.

Step 1: Stop Activepieces

bash

docker compose down

Step 2: Run the rollback command

Replace 0.78.0 with your current version and 0.77.0 with the version you want to go back to:

bash

docker run --rm --env-file .env --entrypoint npm \
  activepieces/activepieces:0.78.0 \
  run rollback -- --to 0.77.0

If the release has breaking migrations, the command will ask you to confirm with --force:

bash

docker run --rm --env-file .env --entrypoint npm \
  activepieces/activepieces:0.78.0 \
  run rollback -- --to 0.77.0 --force

Step 3: Switch to the older image

Update your docker-compose.yml:

yaml

services:
  activepieces:
    image: activepieces/activepieces:0.77.0

Step 4: Start Activepieces

bash

docker compose up -d

Restoring From Backup

If you took a backup and prefer to restore from it:

bash

dropdb activepieces
createdb activepieces
pg_restore -d activepieces backup-pre-upgrade.dump

Then switch your docker-compose.yml to the previous image version and start Activepieces.

For Contributors

Every new database migration must:

Implement Migration instead of MigrationInterface
Set breaking to true (destructive changes) or false (additive only)
Set release to the target release version (e.g., '0.78.0')
Implement down() with working rollback queries

Example:

typescript

import { Migration } from '../../migration'
import { QueryRunner } from 'typeorm'

export class AddNewColumn1710000000000 implements Migration {
    name = 'AddNewColumn1710000000000'
    breaking = false
    release = '0.78.0'

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "project" ADD COLUMN "description" text`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "project" DROP COLUMN "description"`)
    }
}

These requirements are enforced by CI — PRs with migrations that don't meet them will fail checks.