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

1. Go to the service page in the dashboard
2. Navigate to the Storage tab
3. Click New Volume
4. Set the size of the volume (in GB)
5. Set the mount path — the directory inside the container where the volume will be accessible (for example, /data or /app/uploads)
6. Click Create

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

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.