- Documentation
- Services
- Persistent Storage
Persistent Storage
By default, data inside a container is ephemeral — it is lost when the service restarts or a new deployment is made. Persistent volumes solve this problem by preserving data across restarts and deployments.
What are named persistent volumes?
Named persistent volumes are project-scoped disk storage spaces that can be attached to a service. Unlike the container’s file system, data in a named volume survives:
- Service restarts
- New deployments
- Image updates
- Detaching from one service and attaching to another service in the same project
Use persistent volumes to store data such as uploaded files, embedded databases (SQLite), disk caches, or any data that needs to persist.
Creating and attaching a volume
- Go to the service page in the dashboard
- Navigate to the Volume tab
- Under Create and attach, set the volume name and size (in MiB)
- Set the mount path — the directory inside the container where the volume will be accessible (for example,
/dataor/app/uploads) - Click Create and attach
To mount a free volume that already exists in the project, use Attach existing volume in the same tab.
The volume will be created and attached to the service. A new deployment will be triggered automatically to mount the volume.
You can also create and manage named volumes from the CLI:
guara volumes create --name uploads --size 1Gi
guara volumes attach uploads --service api --mount-path /data
guara volumes move uploads --service api-v2 --mount-path /data
guara volumes resize uploads --size 5Gi
guara volumes health uploads
guara volumes backups uploads
Mount path
The mount path defines where the volume appears inside the container. Your application accesses the volume’s data as regular files in that directory.
Common examples:
| Use case | Suggested path |
|---|---|
| SQLite database | /data |
| Uploaded files | /app/uploads |
| Disk cache | /app/cache |
| Persistent logs | /var/log/app |
Limits by plan
| Resource | Starter | Pro | Max | Business | Enterprise |
|---|---|---|---|---|---|
| Persistent volumes per project | 5 | 10 | 15 | 20 | 100 |
| Storage per volume | 10 GiB | 15 GiB | 25 GiB | 50 GiB | 50 GiB |
| Total storage per project | 20 GiB | 30 GiB | 50 GiB | 100 GiB | 500 GiB |
During the free trial, your account uses the Starter limits.
Important considerations
- One attachment at a time. A named volume can be attached to only one service at a time.
- Resizing. You can increase a volume’s size, but you cannot reduce it.
- Portable volumes. New named volumes can be detached, moved, resized, renamed, and deleted when their current state allows it.
- Legacy protected volumes. Imported service-owned volumes can be renamed and resized, but cannot be moved, detached, or deleted from the CLI.
- Deletion. Deleting a portable volume is separate from deleting a service. Detach or move storage deliberately before deleting data.
- Replicas. Persistent volumes are shared across replicas of the same service. Make sure your application handles concurrent access correctly.