Upgrading Between Versions

Version upgrade procedures and breaking change migration.

General Upgrade Process

1. Check Release Notes

Before upgrading, always review:

• GitHub Releases
• API Changelog

2. Backup

# 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

git fetch origin
git checkout main
git pull

4. Update Dependencies

yarn install

5. Run Migrations

yarn typeorm migration:run

6. Build

yarn build

7. Restart Services

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

# PM2
pm2 restart all

# Systemd
sudo systemctl restart gauzy-api

Breaking Changes by Version

v0.x → v1.0

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

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

Rollback Procedure

If upgrade fails:

# 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

• Release Process — release workflow
• API Changelog — API changes
• Database Backup — backup strategy