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

# Upgrades

> How to upgrade Foggy to a new release: preview, upgrade command, verify, rollback.

Releases and changelogs: [github.com/foggylabs/helm-charts/releases](https://github.com/foggylabs/helm-charts/releases). Subscribe via **Watch → Custom → Releases** on GitHub.

## How upgrades work

Foggy upgrades are standard Helm chart upgrades. Three things change:

* **Foggy code.** New Docker images in the Deployments.
* **Kubernetes manifests.** Any chart template or values changes.
* **Database schema.** Forward-only [dbmate](https://github.com/amacneil/dbmate) migrations that run when the new pod starts.

Kubernetes rolls out via `RollingUpdate`; most upgrades are **zero-downtime**. Releases with breaking database migrations are flagged in the release notes.

## Breaking changes policy

Foggy follows semantic versioning. During `0.x.y`, **MINOR** bumps (e.g. `0.1.0 → 0.2.0`) may include breaking changes, typically renamed `values.yaml` keys or changed API contracts. Every release flags breaking changes in the release notes.

After `1.0.0`, only **MAJOR** bumps (e.g. `1.x → 2.0.0`) will include breaking changes. **PATCH** bumps (e.g. `0.1.0 → 0.1.1`) are always safe.

## Before you upgrade

1. **Back up PostgreSQL.**

   **Bundled Postgres.** Dump via `kubectl exec`:

   ```bash theme={null}
   kubectl exec -n foggy statefulset/foggy-postgresql -- \
     pg_dump -U foggy foggy > foggy-backup-$(date +%Y%m%d-%H%M%S).sql
   ```

   Copy the `.sql` file to durable storage (S3, your backup system). `pg_dump` works without `VolumeSnapshotClass` or CSI snapshot drivers.

   **External Postgres.** Use your managed backup (AWS RDS snapshot, Cloud SQL backup, Azure Database backup).
2. **Read the release notes** for breaking changes and migration notes: [GitHub Releases](https://github.com/foggylabs/helm-charts/releases).
3. **Check current version:**

   ```bash theme={null}
   helm ls -n foggy
   ```

## Upgrade command

```bash theme={null}
helm repo update
helm upgrade foggy foggy/foggy --namespace foggy -f values.yaml
```

<Tip>
  If you installed Foggy without a custom `values.yaml`, extract the current values into a file you can track in git:

  ```bash theme={null}
  helm get values foggy -n foggy > values.yaml
  ```

  Then upgrade with `-f values.yaml` from that file going forward.
</Tip>

Without a custom values file:

```bash theme={null}
helm upgrade foggy foggy/foggy --namespace foggy --reuse-values
```

## Monitor rollout

```bash theme={null}
kubectl rollout status -n foggy deployment/foggy-console
kubectl rollout status -n foggy deployment/foggy-agent
```

Tail logs during rollout:

```bash theme={null}
kubectl logs -n foggy -l app=foggy-console -f --tail=50
kubectl logs -n foggy -l app=foggy-agent -f --tail=50
```

## Verify

1. **Log in.** Existing sessions continue to work.
2. Open **Settings → License**. The `appVersion` should reflect the new release.
3. **Run a test investigation.** Confirm data fetch, LLM call, and response work end-to-end.

## Rollback

Revert to the previous Foggy revision:

```bash theme={null}
helm rollback foggy <PREVIOUS_REVISION> --namespace foggy
```

Get the revision number from `helm history foggy -n foggy`.

<Warning>
  **Database migrations are forward-only.** `helm rollback` reverts the Foggy code and Kubernetes manifests, but does **not** revert PostgreSQL schema changes. To rollback past a release that included a schema migration, restore PostgreSQL from your backup **first**, then run `helm rollback`. Release notes flag releases that include migrations.
</Warning>

<Warning>
  **Rollback does not wipe Secrets or Postgres data.** A rollback to a pre-first-install revision is not equivalent to a clean install — `foggy-admin`, `foggy-secrets`, and the bundled Postgres PVC survive by design (see [Uninstall](#uninstall) for the same mechanics and rationale).
</Warning>

## Uninstall

`helm uninstall foggy -n foggy` removes the Deployments, Services, ClusterRole, ClusterRoleBinding, ServiceAccount, and ConfigMap. It does **not** remove the two Secrets or the bundled Postgres PVC. This is intentional.

### What is kept and why

* **`foggy-admin` Secret.** The one-time bootstrap password for first login. Annotated `helm.sh/resource-policy: keep`. No practical reason to retain it post-bootstrap, but the annotation is applied uniformly with the app Secret below.
* **`foggy-secrets` Secret.** Holds `JWT_SECRET`, `AGENT_API_TOKEN`, and `CONNECTOR_ENCRYPTION_KEY`. Keeping it means that if you reinstall to the same release name, existing user sessions stay valid (`JWT_SECRET` unchanged) and any previously-encrypted LLM provider credentials in an external Postgres stay decryptable (`CONNECTOR_ENCRYPTION_KEY` unchanged).
* **`data-foggy-postgresql-0` PVC.** Bundled Postgres data — users, license state, encrypted connector and LLM provider credentials. Standard StatefulSet behaviour: Kubernetes never deletes PVCs on StatefulSet deletion.

### Full wipe

To erase everything — data, secrets, and all bound storage:

```bash theme={null}
helm uninstall foggy -n foggy
kubectl delete namespace foggy

# Only if your StorageClass has reclaimPolicy=Retain — the PV survives the
# namespace delete and must be removed explicitly:
kubectl get pv | grep foggy | awk '{print $1}' | xargs -r kubectl delete pv
```

On external Postgres, the chart never touches your database on uninstall. Drop the database via your provider's console if needed.