frappe-ops-upgrades

# Version Upgrades

Complete guide for upgrading Frappe/ERPNext between major versions, handling failed migrations, and rolling back safely.

**Versions**: v14 → v15 → v16

---

## Quick Reference: Upgrade Commands

| Task | Command |
|------|---------|
| Full update | `bench update` |
| Update specific app | `bench update --pull --app erpnext` |
| Switch branch | `bench switch-to-branch version-15 frappe erpnext` |
| Run migrations only | `bench --site mysite migrate` |
| Check migration readiness | `bench --site mysite ready-for-migration` |
| Backup before upgrade | `bench --site mysite backup` |
| Restore from backup | `bench --site mysite restore /path/to/backup.sql.gz` |
| Re-run failed patch | Add `#YYYY-MM-DD` suffix in patches.txt |

---

## Decision Tree: Upgrade Strategy

```
Need to upgrade?
├── Single minor version bump (e.g., v15.10 → v15.20)?
│   └── YES → Run `bench update` directly
├── Major version jump (e.g., v14 → v15)?
│   ├── Have custom apps?
│   │   ├── YES → Test on staging FIRST, check breaking changes
│   │   └── NO → Follow standard upgrade path
│   └── Multiple major versions (v14 → v16)?
│       └── ALWAYS upgrade one version at a time: v14 → v15 → v16
└── Production environment?
    ├── YES → ALWAYS test on staging clone first
    └── NO → Proceed with standard upgrade
```

---

## Pre-Upgrade Checklist

**ALWAYS** complete these steps before ANY major version upgrade:

1. **Full backup** — `bench --site mysite backup --with-files`
2. **Test on staging** — Clone production to a staging bench and test there first
3. **Check breaking changes** — Review the breaking changes section below
4. **Audit custom apps** — Run custom apps against new version's API changes
5. **Check Python/Node versions** — v15 requires Node 18+; v16 requires Node 24+, Python 3.14+
6. **Disable scheduler** — `bench --site mysite scheduler disable`
7. **Check pending jobs** — `bench --site mysite ready-for-migration`
8. **Read release notes** — Check GitHub release notes for each version

---

## Standard Upgrade Process

### Step-by-Step

```bash
# 1. Backup all sites
bench backup-all-sites

# 2. Switch to target version branch
bench switch-to-branch version-15 frappe erpnext

# 3. Update (pulls code, installs deps, builds, migrates)
bench update

# 4. Verify
bench --site mysite migrate  # if not done by update
bench version                # confirm versions
```

### What `bench update` Executes (In Order)

1. Backup all sites
2. Pull latest code for all apps (`git pull`)
3. Install Python requirements (`pip install`)
4. Install Node requirements (`yarn install`)
5. Build static assets (`bench build`)
6. Run migrations on all sites (`bench migrate`)
7. Restart bench processes

---

## v14 → v15 Breaking Changes

### Environment Requirements

| Requirement | v14 | v15 |
|-------------|-----|-----|
| Node.js | v14+ | **v18+** |
| Python packaging | setup.py | **pyproject.toml** |

### Backend Breaking Changes

- **`db.set()` removed** — Use `doc.db_set()` instead
- **`db.sql()` parameters removed** — `as_utf8` and `formatted` no longer accepted
- **`db.set_value()` for Singles** — Use `frappe.db.set_single_value()` instead
- **`job_name` deprecated** — Use `job_id` parameter in `enqueue()`
- **`frappe.new_doc()` arguments** — `parent_doc`, `parentfield`, `as_dict` MUST be keyword args
- **`frappe.get_installed_apps()`** — No longer accepts `sort` or `frappe_last` args
- **Method override order reversed** — Last override now takes precedence
- **Timezone functions renamed** — `convert_utc_to_user_timezone` → `convert_utc_to_system_timezone`

### Frontend Breaking Changes

- **Vue 2 → Vue 3** — All Vue components MUST be migrated
- **Window globals removed** — `get_today` → `frappe.datetime.get_today`, `user` → `frappe.session.user`
- **`this` in Client Scripts** — Local scope access no longer supported
- **Image lazy loading** — Replace `website-image-lazy` class with native `loading="lazy"`

### Security Changes

- **Server Scripts disabled by default** — Enable: `bench set-config -g server_script_enabled 1`
- **"Desk User" role added** — Replaces "All" role for desk user permissions
- **`currentsite.txt` removed** — Use `bench use sitename` or `FRAPPE_SITE` env var

### Removed Features

- Event Streaming moved to separate app
- Cordova support removed
- `setup.py` removed (use `pyproject.toml`)
- `--make_copy` and `--restore` build flags removed (use `--hard-link`)

See [breaking-changes.md](references/breaking-changes.md) for the complete list.

---

## v15 → v16 Breaking Changes

### Environment Requirements

| Requirement | v15 | v16 |
|-------------|-----|-----|
| Node.js | v18+ | **v24+** |
| Python | 3.10+ | **3.14+** |

### Backend Breaking Changes

- **Default sort order changed** — `creation` instead of `modified` for all list queries
- **`has_permission` hooks** — MUST return explicit `True`; `None` no longer accepted
- **`frappe.get_doc(doctype, name, field=value)`** — No longer updates values
- **DB commits in document hooks** — No longer allowed to prevent data integrity issues
- **`frappe.sendmail(now=True)`** — No longer commits transactions implicitly
- **`db.get_value()` for Singles** — Now returns proper types instead of strings
- **State-changing methods require POST** — `/api/method/logout`, `/api/method/upload_file`, etc.

### Separated Modules (Install Separately)

- Energy Points → `frappe/eps`
- Newsletter → `frappe/newsletter`
- Backup Integrations → `frappe/offsite_backups`
- Blog → `frappe/blog`

### Frontend Breaking Changes

- Report/Dashboard/Page JS evaluated as IIFEs (no global scope pollution)
- Awesome Bar redesigned, moved to sidebar (`Cmd+K`)
- List view right sidebar removed
- `/apps` endpoint deprecated; `/app` reroutes to `/desk`

### Configuration Changes

- Site config cached for up to one minute (changes not immediate)
- Country field requires valid ISO 3166 ALPHA-2 code
- `bench version` output format changed to "plain" (use `-f legacy` for o