> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade to a maintained version of a runtime or service

> Upgrade a runtime or service to a maintained version to avoid build failures and stay protected against known CVEs.

Use a maintained runtime or service version — outdated images can fail to build or carry known CVEs. See [Image statuses](#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](https://developer.upsun.com/docs/languages) or your service in [Add services](https://developer.upsun.com/docs/add-services).

## Image statuses

"Maintained" means **Active** or **Supported**, depending on the classification below.

> [!NOTE]
>
> Some runtimes and services (for example, [Redis](https://developer.upsun.com/docs/add-services/redis.md)) use the **Active/Sunset/Decommissioned** classification below.
>
> Others currently use the **Supported/Deprecated/Retired** classification, until they migrate to **Active/Sunset/Decommissioned**.

> [tab] Active/Sunset/Decommissioned
>
> The Console shows an image's status as a banner on your project's Overview page, or as a decoration on the relevant activity in the **Activity** panel (active images show no decoration, since they're always supported).
>
> An image's status shows what's supported and what to do:
>
> | Image status | What it means | What to do |
> | - | - | - |
> | Active | Fully maintained, Upsun Cloud applies software and security updates received from upstream. | No action needed. |
> | Sunset | Existing projects (including code pushes) keep working; new projects can't use this image. Upsun Cloud applies only critical security updates from upstream, and the image is decommissioned 180 calendar days after entering Sunset. | Upgrade to an active version before the decommission date (180 calendar days after entering Sunset). |
> | Decommissioned | Upsun Cloud no longer supports this image. Existing projects with a decommissioned image continue to run as is. All code pushes are blocked. | Upgrade to an active version to continue deploying. |

> [tab] Supported/Deprecated/Retired
>
> "Image status" is the classification shown on each runtime's ([Languages](https://developer.upsun.com/docs/languages)) or service's ([Add services](https://developer.upsun.com/docs/add-services)) own docs page:
>
> | Image status | What it means | What to do |
> | - | - | - |
> | Supported | Fully maintained, Upsun Cloud applies software and security updates received from upstream. | No action needed. |
> | Deprecated | Still available and functional, but at end of life and no longer receiving security updates from upstream. | Switch to a supported version to keep receiving security updates. |
> | Retired | No longer available from upstream and not receiving further updates. This reflects the upstream project's own status only — Upsun Cloud doesn't enforce it, so the image keeps working with no scheduled decommission date. | Upgrade to a supported version, since no further security updates are available. |
> | Decommissioned\* | No longer supported by upstream. This reflects the upstream project's own status only — Upsun Cloud doesn't enforce it, so builds and deployments aren't blocked. | Upgrade to a supported version as soon as possible. |
>
> \* At this time, decommissioned images are not listed in the product docs.

## Before you upgrade

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

## Upgrade a runtime

Runtimes are defined by the `type` key on your application in `.upsun/config.yaml`. Updating to a new version means changing that value and pushing it. This is a version change you choose and push yourself, so it applies on deploy as usual, whether or not your project has a [maintenance window](https://developer.upsun.com/docs/core-concepts/build-deploy.md#maintenance-window) — maintenance windows only govern the platform's own automatic patch updates.

1. Check your runtime's docs page in [Languages](https://developer.upsun.com/docs/languages) for supported versions — new versions may include breaking changes — then update the `type` key with the correct version number:


    applications:
      myapp:
        type: php:\{\{version:php:latest}}

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

```bash theme={null}
upsun branch upgrade-runtime
git add .upsun/config.yaml
git commit -m "Update runtime version"
upsun push
```

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

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

```bash theme={null}
upsun activity:log
```

Then open the environment and test your app manually:

```bash theme={null}
upsun environment:url --primary
```

4. Merge to production:

```bash theme={null}
upsun merge
```

If your project uses a source integration (GitHub, GitLab, Bitbucket), `upsun merge` isn't available — merge through a pull/merge request in your Git provider instead.

## Upgrade a service

Services are defined under the `services:` key in `.upsun/config.yaml`. Updating the `type` value triggers a version change on the next deploy, the same as [upgrading a runtime](#upgrade-a-runtime): it's a change you choose and push yourself, independent of any [maintenance window](https://developer.upsun.com/docs/core-concepts/build-deploy.md#maintenance-window). Whether data migrates automatically depends on the service. Check [Add services](https://developer.upsun.com/docs/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:


    services:
      database:
        type: postgresql:\{\{version:postgresql:latest}}

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

```bash theme={null}
upsun branch upgrade-service
git add .upsun/config.yaml
git commit -m "Update service version"
upsun push
```

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

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

```bash theme={null}
upsun activity:log
```

Then open the environment and test your app manually:

```bash theme={null}
upsun environment:url --primary
```

4. Create a production backup, then merge to production:

```bash theme={null}
upsun backup:create --environment main
upsun merge
```

If your project uses a source integration (GitHub, GitLab, Bitbucket), `upsun merge` isn't available — merge through a pull/merge request in your Git provider instead.

Downgrading is not 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 (for example, if you use composable image or Docker images), or when you're moving across several major versions, you need to export your data, provision a new service at the target version, and import.

1. [Export your data](https://developer.upsun.com/docs/core-concepts/common-tasks/exporting.md) from the current service.

2. Rename the service in `.upsun/config.yaml` and set the target version. Renaming forces the platform to create a fresh service container.


    services:
      database-target:
        type: postgresql:\{\{version:postgresql:latest}}

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


    applications:
      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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.