# Upgrade safely

Check versions, preserve a recovery path, and validate application behavior before upgrading ParticleDB.

Source: https://particledb.ai/guides/upgrades/

## Record the current environment

```bash
particledb --version
```

Record client package versions, configuration and the data directory. Read the target release's changes before replacing the binary.

## Prepare a recovery path

Use the [backup or export process](/operations/durability/) supported by your edition. Verify a restore on a separate instance. Do not assume an older binary can read a directory written by a newer version.

## Test the application

Run representative queries, writes, transactions and error handling. Verify Particles and their dependencies separately. Run schema changes on a test copy before applying them in production.

## Roll out

Stop writes using your application's maintenance process. Follow the release-specific upgrade procedure, start the new version, check health and sample records, then restore traffic.

If validation fails, use the planned recovery process instead of opening the same directory with an unverified older binary.

## Related

[Documentation home](/docs/) · [Troubleshooting](/guides/troubleshooting/)