# Upgrading Between Versions {#upgrading-between-versions}


Version upgrade procedures and breaking change migration.


## General Upgrade Process {#general-upgrade-process}



### 1. Check Release Notes {#1-check-release-notes}


Before upgrading, always review:

- [GitHub Releases](https://github.com/ever-co/ever-gauzy/releases)
- [API Changelog](https://sourcey-gauzy.pages.dev/reference/api-changelog/index.md)


### 2. Backup {#2-backup}


```bash
# Database backup
pg_dump -h $DB_HOST -U $DB_USER gauzy > backup_$(date +%Y%m%d).sql

# File storage backup
tar -czf uploads_backup.tar.gz ./apps/api/public/
```


### 3. Update Code {#3-update-code}


```bash
git fetch origin
git checkout main
git pull
```


### 4. Update Dependencies {#4-update-dependencies}


```bash
yarn install
```


### 5. Run Migrations {#5-run-migrations}


```bash
yarn typeorm migration:run
```


### 6. Build {#6-build}


```bash
yarn build
```


### 7. Restart Services {#7-restart-services}


```bash
# Docker
docker compose down && docker compose up -d

# PM2
pm2 restart all

# Systemd
sudo systemctl restart gauzy-api
```


## Breaking Changes by Version {#breaking-changes-by-version}



### v0.x → v1.0 {#v0x--v10}


| Change                     | Action Required                 |
| -------------------------- | ------------------------------- |
| Relation whitelisting      | Update custom API clients       |
| UUID validation on all IDs | Ensure UUIDs in requests        |
| Auth endpoint changes      | Update login flow               |
| MikroORM 6.x               | Update custom entity decorators |


### Docker Image Changes {#docker-image-changes}


```diff
- ghcr.io/ever-co/gauzy-api:0.x
+ ghcr.io/ever-co/gauzy-api:latest
```


## Rollback Procedure {#rollback-procedure}


If upgrade fails:

```bash
# Restore database
psql -h $DB_HOST -U $DB_USER gauzy < backup_20250101.sql

# Revert code
git checkout v0.x.x

# Rebuild and restart
yarn install && yarn build
```


## Related Pages {#related-pages}


- [Release Process](https://sourcey-gauzy.pages.dev/development/release-process/index.md) — release workflow
- [API Changelog](https://sourcey-gauzy.pages.dev/reference/api-changelog/index.md) — API changes
- [Database Backup](https://sourcey-gauzy.pages.dev/devops/database-backup/index.md) — backup strategy