Upgrades
Learn how to upgrade your ByteChef instance
Upgrading to a new version
ByteChef ships as a container image, so upgrading means pulling a newer tag and restarting:
- Back up the database first (see below).
- Update the image tag to the target version (or
latest) in yourdocker-compose.yml, Helm values, or cloud service definition. - Restart the instance.
On startup ByteChef runs its Liquibase schema migrations automatically. This behavior is controlled by BYTECHEF_UPGRADE_ENABLED (default true):
- Leave it
trueon the instance that should own the schema. - Set it to
falseon read-only replicas, or on every replica except one, so that only a single designated instance applies schema changes during a rolling upgrade of a multi-instance deployment.
Because migrations run at startup, always take a database backup before deploying a new version.
Kinds of upgrade
| Change | What it involves | Typical window |
|---|---|---|
| Patch / minor version | Backwards compatible. Liquibase changes are additive; a rolling restart onto the new image is enough. | Minutes, no downtime. |
| Major version | May include breaking schema changes. Liquibase applies them at startup, but the change is one-way — take a backup first, and re-read the environment-variable reference for renamed or newly required settings. | Announce a maintenance window. |
| Community → Enterprise | Not a different artifact. Both editions ship in the same image and the same schema (there is no separate EE Liquibase context); set BYTECHEF_EDITION=EE and restart. Existing workflows, executions, and connections carry over unchanged, and you enable EE features incrementally. | Minutes. |
| Single instance → several | Align the encryption key, the message broker, the cache provider and the remember-me key across instances first, and keep migrations owned by one of them. See Running multiple instances. | One restart per instance. |
| Broker swap | Drain in-flight tasks on the old broker, change BYTECHEF_MESSAGE_BROKER_PROVIDER and its connection settings, restart the coordinator and workers. Suspended executions resume against the new substrate. See Message brokers. | Minutes, after the drain. |
| Region or host migration | Bring up the new cluster, replicate the database, move the encryption key and any filesystem-provider storage directory with it, then cut over DNS. | Depends on database size. |
Before every upgrade
- Take a database backup — and confirm you have a tested restore procedure, not just a dump file.
- Back up the encryption key (see below). A restored database without its key is unreadable.
- Commit your Helm values or Compose file so the configuration you are running is recoverable.
- Have observability in place before you start, so you can tell a slow migration from a stuck one.
- Cover the change window with someone on call.
The Helm chart is safe to re-apply: every value has a default and re-applying does not reset what you customized.
Backing up and restoring
All persistent state lives in PostgreSQL, so a standard PostgreSQL backup captures everything except externally-stored files (see below):
# Back up
pg_dump -Fc -h <host> -U <user> -d bytechef > bytechef-backup.dump
# Restore into an empty database
pg_restore -h <host> -U <user> -d bytechef --clean bytechef-backup.dumpIf you configured BYTECHEF_FILE_STORAGE_PROVIDER=FILESYSTEM or BYTECHEF_DATA_STORAGE_PROVIDER=FILESYSTEM, also back up the directory in BYTECHEF_FILE_STORAGE_FILESYSTEM_BASEDIR (default ${user.home}/bytechef/data/file-storage). With the JDBC provider (the default for data and output storage) that data is already in the database; with the AWS provider it lives in your S3 bucket and is covered by your bucket's own backup policy.
Also preserve the encryption key across restores — if BYTECHEF_ENCRYPTION_PROVIDER=FILESYSTEM, the generated key file must be restored alongside the database, or stored connection credentials become undecryptable. Using BYTECHEF_ENCRYPTION_PROVIDER=PROPERTY with a key you hold avoids this coupling.
How is this guide?
Last updated on