Upgrade to a maintained version of a runtime or service

Use a maintained runtime or service image. Outdated images can fail to build and may carry known CVEs. See Image statuses to check your image’s status and what to do next.

Once you know you need to upgrade, the steps are the same regardless of which runtime or service you use. For version-specific details, see the docs page for your runtime in Languages or your service in Add services.

Image statuses

“Maintained” means Active or Supported, depending on the classification below.

Before you upgrade

Test any version change on a non-production environment before merging.

Upgrade a runtime

The type key on your application in .platform.app.yaml defines the runtime. Updating to a new version means changing that value and pushing it.

1. Check the supported versions on the runtime page under Languages, then update the type key with the correct version number:

   .platform.app.yaml

   name: myapp
   type: 'php:8.5'

2. Push to a non-production branch. If you don’t already have one, create it first:

   platform branch upgrade-runtime
   git add .platform.app.yaml
   git commit -m "Update runtime version"
   platform push

   Pushing triggers Upsun Fixed to automatically build and deploy the environment.

3. Verify that your app builds and behaves correctly. Check the deploy log for errors:

   platform activity:log

   Then open the environment and test your app manually:

   platform environment:url --primary

4. Merge to production:

   platform merge

   If your project uses a source integration (GitHub, GitLab, Bitbucket), merge through a pull request or merge request in your Git provider instead.

Upgrade a service

Services are defined under the services key in .platform/services.yaml. Updating the type value triggers a version change on the next deploy. Whether data migrates automatically depends on the service. Check the supported versions on your service’s page under Add services before you begin.

In-place upgrade

Some services upgrade automatically when you change the version. PostgreSQL 10 and later, for example, include a built-in upgrade utility that runs at deploy time.

1. Update the type key for your service:

   .platform/services.yaml

   database:
     type: postgresql:18

2. Push to a non-production branch. If you don’t already have one, create it first:

   platform branch upgrade-service
   git add .platform/services.yaml
   git commit -m "Update service version"
   platform push

   Pushing triggers Upsun Fixed to automatically build and deploy the environment.

3. Confirm the service starts and your app connects. Check the deploy log for errors:

   platform activity:log

   Then open the environment and test your app manually:

   platform environment:url --primary

4. Create a backup, then merge to production:

   platform backup:create --environment main
   platform merge

   If your project uses a source integration (GitHub, GitLab, Bitbucket), merge through a pull request or merge request in your Git provider instead.

Downgrading isn’t supported after an in-place upgrade. If you need to roll back, restore from a backup.

Manual data migration

When a service doesn’t support in-place upgrades, or when you’re moving across several major versions, export your data, provision a new service at the target version, and import the data.

1. Export your data from the current service.

2. Rename the service in .platform/services.yaml and set the target version. Renaming forces Upsun Fixed to create a fresh service container.

   .platform/services.yaml

   database-target:
     type: postgresql:18

3. Update the relationships of any application that references the old service name:

   .platform.app.yaml

   name: myapp
   relationships:
     database:
       service: database-target
       endpoint: postgresql

4. Push to a non-production branch and import your data into the new service.

5. Verify your app works correctly, then merge to production.