Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suga.app/llms.txt

Use this file to discover all available pages before exploring further.

This reference covers persistent storage on Suga: volumes for data persistence, database templates, and backup strategies.

​
Volumes

Volumes provide persistent block storage. Unlike service filesystems (ephemeral), volume data persists across restarts, redeployments, and rollbacks.

​
Creating a Volume

  1. Add a volume to the canvas
  2. Set size (see plan limits below)
  3. Drop the volume onto a service
  4. Set the mount path
  5. Deploy

​
Volume Constraints

  • Services per volume: 1 (volumes cannot be shared between services)
  • Replicas with volumes: 1 (required for data consistency)
  • Size limits: vary by plan, see Plan Limits
Volume storage also counts toward your organization’s overall storage pool.
Services with volumes must have exactly 1 replica. Volumes cannot be shared across multiple instances or services.

​
Data Persistence

Data survives:
  • Container restarts
  • Redeployments
  • Service crashes
  • Rollbacks (data stays current, not rolled back)
Data is lost if:
  • Volume is deleted
  • Environment is deleted
Rolling back a deployment does NOT roll back volume data. However, rolling back to a deployment before the volume existed will result in it being deleted.

​
Database Templates

Templates provide pre-configured databases with volumes attached.

​
PostgreSQL

Image: postgres:16-alpine
Port: 5432
Volume: /var/lib/postgresql/data
Environment:
  POSTGRES_USER: postgres
  POSTGRES_PASSWORD: [your password]
  POSTGRES_DB: postgres
Connection from other services: 
postgresql://postgres:PASSWORD@postgres:5432/postgres

​
Redis

Image: redis:7-alpine
Port: 6379
Volume: /data
Command: redis-server --requirepass [password] --appendonly yes
Connection: 
redis://:PASSWORD@redis:6379

​
MariaDB

Image: mariadb:11
Port: 3306
Volume: /var/lib/mysql
Environment:
  MYSQL_ROOT_PASSWORD: [your password]
  MYSQL_DATABASE: mydb
Connection: 
mysql://root:PASSWORD@mariadb:3306/mydb

​
Connecting to Databases

Use service names as hostnames for private networking: 
// Node.js - PostgreSQL
const pool = new Pool({
  host: 'postgres',  // Service name
  port: 5432,
  password: process.env.DB_PASSWORD
});

// Node.js - Redis
const redis = new Redis({
  host: 'redis',
  port: 6379,
  password: process.env.REDIS_PASSWORD
});

​
Volume vs External Storage

Use Volumes when:
  • Running your own database
  • Need direct filesystem access
  • Storing small uploads or state
Use External Storage (S3, R2) when:
  • Files exceed your plan’s storage limits
  • Need to share files across services
  • Require public CDN access
  • Want automatic scaling

​
Common Questions

No, each volume can only mount to one service. For shared data, use a database or external object storage.
Yes. Volumes can be increased in size, however for safety they can’t be shrunk. If you need to shrink a volume create a new smaller volume and transfer the data manually.
You can only access volume data from within the container. Use database connections or application APIs.