Databases and backups
Fix database connections, startup, backups, restores, and encryption problems.
An app cannot reach its database
| Check | Why |
|---|---|
| Are they on the same server? | App-to-database name resolution works within one server |
| Is the host the database's name? | Use the database name, not an IP or localhost |
| Is the database running? | Its status badge |
| Did the password change? | Rotating it does not update the app's variable. Update it and redeploy |
| Did you redeploy after setting the variable? | Variables apply on the next deploy |
A database does not start
provisioning: the agent could not pull the image, or the server is unreachable. Redeploy and Rebuild cannot help until it is ready.- After a version change: a major version may reject the old data directory. Dump, rebuild, and restore.
- After a custom command: for Redis, keep
--requirepassif clients use a password. - After a server move: resolve the data-copy error before starting the engine. An empty volume can initialise a new database over the old data.
A Rebuild removed the data
Rebuild deletes the volume
It tears down the stack and provisions a fresh database. The connection string can still work even when the old data is gone.
Use Redeploy for a data-preserving change. Restore a backup if data is missing.
Deleting a database is refused
Deletion is refused until the host confirms that both the container and volume are gone.
If the host is permanently gone, a force option appears after the refusal.
A backup destination test fails
A failed probe is a result, not a platform error. Open Connection log in the destination's menu for the failed step and the equivalent commands.
| Symptom | Usual cause |
|---|---|
| A bucket fails on write | The key is read-only. The probe writes a zero-byte object on purpose, so a read-only key correctly reads as failed |
| A bucket fails on head | Wrong endpoint or region for that bucket |
| A folder fails to resolve | The path does not exist on that server, or the agent cannot write there |
| Anything on a private address | The outbound guard refuses non-public endpoints unless an instance admin allowed it |
A backup run fails
- No space on the destination server.
- The workload is not running. Backups read from the live target.
- The server is unreachable. Check its health.
The app's data was not in the backup
An app schedule does not include its databases. Schedule the databases too.
A restore fails
- Checksum mismatch: the artifact is corrupt and was rejected.
- Wrong encryption key: use Restore from file and paste the recovery key.
- Target name mismatch: type the target name again. Restore is destructive.
A backup artifact will not decrypt
Artifacts use age, with one key pair per destination.
age -d -i recovery-key.txt backup.sql.gz.age > backup.sql.gzKeep the recovery key
Download the recovery key from the destination's menu and store it safely. If the control plane is gone, that copy is the only way to decrypt the artifact.
Old backups are disappearing
Keep is a count, not a number of days. Keep 7 retains the seven most
recent successful artifacts; older ones are removed after a successful run.
Next steps
Did this page help you?