On this page

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 Volume tab
  3. Under Create and attach, set the volume name and size (in MiB)
  4. Set the mount path — the directory inside the container where the volume will be accessible (for example, /data or /app/uploads)
  5. 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 caseSuggested path
SQLite database/data
Uploaded files/app/uploads
Disk cache/app/cache
Persistent logs/var/log/app

Limits by plan

ResourceStarterProMaxBusinessEnterprise
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.