A volume is persistent disk storage mounted into your app at a path you choose, such as /data. Files written there survive restarts and deploys. Use one for uploads, an embedded SQLite database, or any app that keeps its data on local disk.
Adding a volume#
On the app's Resources tab, choose Add dependency → Volume:
- Create new: set the Volume name, Capacity (GB) (20 by default) and Mount path (
/databy default), and optionally Read only. - Attach existing: pick a volume your organization already has and set its mount path.
The app restarts with the volume mounted. Adding a SQLite database creates its volume for you.
From the CLI:
nimbus volumes create --name uploads --size 20
nimbus volumes attach --volume <volume-id> --app <app-id> --path /data
nimbus volumes listThe HTTP API offers the same through POST /api/v1/volumes and POST /api/v1/volumes/:id/attachments.
What to know#
- An app with a volume stops its old instance before starting the new one on each deploy, so there is a short gap instead of a rolling update.
- Volumes are mounted in production only. Staging and preview environments run without them.
- Volumes are not available to static sites.
What happens to the data#
| Action | The data |
|---|---|
| Detach | Kept. The volume shows as kept from the app it came from, and can be attached again to that app or another app in your organization. |
| Attach a kept volume | Moves with it, to the same app or another one. A volume that has data never gets empty storage in its place. |
| Delete the volume | Destroyed. Its snapshots are kept for 7 days. |
| Delete the app | Volumes still attached are destroyed, with all their snapshots. Volumes you detached earlier are kept. |
If a step fails, the volume stays as it was and its entry shows the reason; try the action again. Deleting a volume, or an app with volumes attached, asks you to type its name first. Detaching has a one-step confirm, because nothing is lost.
To keep a volume's data before deleting an app, detach the volume first.
Snapshots#
Every attached volume gets point-in-time snapshots: automatic daily ones, plus manual ones you take whenever you like. Manage them in the Snapshots section of the volume's Edit dialog on the Resources tab.
A snapshot is crash-consistent: it holds exactly what a sudden power loss would have left on the volume at that moment. Software that survives a power cut, such as SQLite, Postgres or files written in one go, restores cleanly. Taking a snapshot never pauses or restarts your app.
Snapshots are kept on the same storage as the volume. They protect against deletion and mistakes (an app deleting its own files, a migration gone wrong, a volume deleted by accident), not against losing that storage. They are not an off-site copy. Keep your own copy of anything irreplaceable.
Schedule and retention#
- Automatic daily snapshots are on by default and run once a day after 03:30 UTC. You can switch them off per volume; existing snapshots stay.
- Automatic snapshots kept: the newest 7 by default, settable from 1 to 30. The oldest is removed only once a newer one is ready. Lowering the number below what is kept now deletes the oldest ones, so you are asked to type the volume's name first.
- Manual snapshots: choose Take snapshot, with an optional label of up to 80 characters. A volume can keep up to 10. They don't count toward the automatic retention and stay until you delete them.
- Failed snapshots show the reason, are never offered for restore, and are removed after a day. A failed automatic snapshot is retried an hour later, up to three times a day.
The section shows how many snapshots the volume has and an approximate size, which overstates the real space because snapshots share unchanged data with the volume.
Restoring a snapshot#
Restoring never overwrites the volume the snapshot came from. It creates a new volume of the same size, named after the volume and the snapshot time. The restore dialog offers to attach it now in place of the current volume at the same mount path: the current volume is detached and kept, the new one attached, and the app restarts once. Untick that option to attach the new volume later from Add dependency → Volume → Attach existing.
Until it is first attached, a restored volume can only be attached to the app its snapshot came from.
After deleting a volume#
A deleted volume's snapshots are kept for 7 days. During that time the volume is listed under Recently deleted in Add dependency → Volume, with the days left and a Restore action for each snapshot. After 7 days the snapshots are removed.
Snapshots don't survive deleting the whole app: every snapshot of every volume the app has goes with it, and the delete dialog says how many.
Snapshots from the API#
| Request | What it does |
|---|---|
GET /api/v1/volumes/:id/snapshots | The volume's snapshots, newest first |
POST /api/v1/volumes/:id/snapshots | Take a manual snapshot; optional body {"label": "before schema change"} |
PUT /api/v1/volumes/:id/snapshot-policy | Body {"automatic_snapshots": true, "snapshot_retention": 14}; lowering retention below the snapshots kept now also needs "confirm": "<volume name>" |
DELETE /api/v1/volume-snapshots/:id | Delete a snapshot |
POST /api/v1/volume-snapshots/:id/restore | Restore into a new volume; body {"attach": "in_place"} or {"attach": "none"} (the default) |
GET /api/v1/apps/:id/volume-snapshots | Every snapshot of the app's volumes, including those of volumes deleted in the last 7 days |
Reading snapshots needs the View storage permission; changing them needs Manage storage, plus Manage apps to attach a restored volume in place.
Also available as Markdown.