Database Services

Slipway provisions and manages databases for your Sails applications from the same platform.

For another trusted container image, use private custom services. Custom images do not receive database-specific backup or schema tools.

Supported Databases

Database	Type	Use Case
PostgreSQL	Relational	Primary database for most apps
MySQL	Relational	Alternative relational database
Redis	Key-Value	Caching, sessions, queues
MongoDB	Document	Document-based storage

Tested image versions

Slipway provisions new services from tested numeric Docker tags and records the immutable digest or image ID that Docker actually ran. New services never store latest.

Service	Default	Other tested line	Automated upgrade
PostgreSQL	17	16	16 → 17
MySQL	8.4	8.0	8.0 → 8.4
Redis	7.2	—	Not yet
MongoDB	8.0	7.0	7.0 → 8.0

Docker may publish newer patches within a supported line, but restarting, recreating, restoring, or updating Slipway reuses the exact image recorded for that service.

Existing services created with latest are migrated conservatively. Slipway inspects the running container, records its actual image and digest, and leaves its volume untouched. If the original container no longer exists, the version remains visibly unresolved rather than being guessed.

Creating a Database

Via CLI

# Interactive (prompts for type)
slipway db:create mydb

# Explicit type
slipway db:create mydb --type=postgresql
slipway db:create cache --type=redis
slipway db:create docs --type=mongodb

# Choose another tested line
slipway db:create legacy-db --type=postgresql --version=16

Custom versions must be numeric tags such as 17.4 or 8.0.12. Mutable aliases, image variants, repository names, and shell syntax—such as latest, 17-alpine, or postgres:17—are rejected.

Via Dashboard

1. Go to your project and select an environment
2. In the Services section, click + Add service (or use the dropdown menu and select Create service)
3. Select the database type
4. Configure name and version
5. Click Create

Linking Databases to Apps

The magic of Slipway's service linking: automatic environment variable injection.

How It Works

When you link a database to an app, Slipway automatically sets the appropriate connection environment variable:

slipway db:link mydb myapp

This automatically sets:

Database Type	Environment Variable
PostgreSQL	DATABASE_URL=postgres://user:pass@host:5432/mydb
MySQL	DATABASE_URL=mysql://user:pass@host:3306/mydb
Redis	REDIS_URL=redis://host:6379
MongoDB	DATABASE_URL=mongodb://user:pass@host:27017/mydb

Sails Configuration

Your Sails app can read these directly in config/datastores.js:

// config/datastores.js
module.exports.datastores = {
  default: {
    // Slipway sets DATABASE_URL automatically when you link a database
    url: process.env.DATABASE_URL
  }
}

For Redis (sessions, caching):

// config/session.js
module.exports.session = {
  adapter: '@sailshq/connect-redis',
  url: process.env.REDIS_URL
}

Unlinking

To remove a database link:

slipway db:unlink mydb myapp

This removes the environment variable. The database itself is not deleted.

Upgrading a service

Supported adjacent upgrades appear on the service settings page. An upgrade is a recoverable data migration, not an in-place image restart:

1. Slipway creates and verifies a logical backup in configured object storage.
2. It resolves the target image before interrupting the running service.
3. It starts the target version on a fresh named volume.
4. It restores the verified backup and waits for the database to become ready.
5. It promotes the restored container to the canonical service name.
6. It retains the stopped previous container and volume for explicit recovery.

The settings page streams every step. Backup, image pull, startup, and restore failures stop before promotion.

Slipway only automates tested adjacent major-version upgrades. It does not automate downgrades, skipped releases, custom-version upgrades, or Redis upgrades without a verified restore path.

Verify before cleanup

After an upgrade, verify application reads and writes before deleting the retained previous container or volume. The service settings page records the exact previous container and backup used for recovery.

Detailed connection, credential-rotation and recovery guidance is available in Private backup storage and External PostgreSQL.

Private backup storage

In Settings → File storage → Backup storage, keep the existing private R2/S3/Spaces configuration or select separate S3-compatible storage or Azure Blob Storage. Public upload settings remain separate; Azure is offered for private backups only.

For Azure, enter an existing private container and storage account. Prefer a container-scoped SAS token with read, write, delete permissions and a future expiry. Encrypted account keys are also supported. Credentials are never returned to the browser. Custom endpoints are optional; HTTP requires explicit opt-in for a trusted private network.

Test connection verifies a temporary upload, download, checksum, anonymous-access rejection and deletion. Save repeats that verification before storing the configuration. Backup objects must deny anonymous reads; an existing public upload bucket may need a separate private backup bucket.

Manual and scheduled database backups, restore downloads, retention deletion, service upgrades and pre-update Slipway database snapshots use this storage. Existing S3 backup records remain supported. New backups retain their original provider and encrypted connection when settings change; saving verified replacement credentials for the same location also renews matching backup records.

Transfers have size/time limits and checksum verification. Failed object deletion preserves the backup record for a later retry. Provider-managed historical versions and soft-delete retention follow the provider's lifecycle rules; Slipway's retention count controls current backup objects, not all historical bytes. Keep the instance encryption keys with recovery material.

The automated contract uses local S3 and Azure emulators, including real SDK transfers, scoped SAS, cancellation, cleanup, credential renewal and the backup lifecycle. Before relying on a new provider, create a backup and restore it into a disposable database to verify its contents and your real network/account policy.

Connecting Directly

Need to run SQL queries or inspect data? Connect directly to your database:

# PostgreSQL - opens psql
slipway db:connect mydb

# MySQL - opens mysql client
slipway db:connect mysql-db

# Redis - opens redis-cli
slipway db:connect cache

# MongoDB - opens mongosh
slipway db:connect docs

Example Session

$ slipway db:connect mydb

Connecting to PostgreSQL database 'mydb'...

psql (16.1)
Type "help" for help.

mydb=> \dt
         List of relations
 Schema |   Name   | Type  | Owner
--------+----------+-------+-------
 public | user     | table | slipway
 public | post     | table | slipway
 public | comment  | table | slipway
(3 rows)

mydb=> SELECT COUNT(*) FROM "user";
 count
-------
   156
(1 row)

Database Management

List All Databases

slipway db:list

Output:

NAME        TYPE        STATUS    LINKED TO       CREATED
mydb        postgres    running   myapp           2 days ago
cache       redis       running   myapp, api      5 days ago
analytics   postgres    running   -               1 week ago

Get Connection URL

Retrieve the connection string for a database:

slipway db:url mydb

Output:

postgres://slipway_abc123:secretpass@mydb.internal:5432/mydb

Security

Connection strings contain credentials. Don't share them or commit them to version control.

Database Info

Get detailed information about a database:

slipway db:info mydb

Output:

Database: mydb
Type: PostgreSQL 16
Status: running
Container: slipway-db-mydb-abc123

Connection:
  Internal Host: mydb.internal
  Internal Port: 5432
  Database: mydb
  Username: slipway_abc123

Linked Apps:
  - myapp (DATABASE_URL)

Created: 2024-01-15 10:30:00

Backups

Create a Backup

slipway db:backup mydb

This creates a timestamped backup:

Creating backup of 'mydb'...
✓ Backup created: mydb-2024-01-20-143022.sql.gz (2.3 MB)

Backup to S3-Compatible Storage

Store backups offsite in S3-compatible storage (R2, Spaces, S3):

1. Configure global storage credentials:

slipway config:set \
  R2_ACCESS_KEY=your-access-key \
  R2_SECRET_KEY=your-secret-key \
  R2_BUCKET=my-backups \
  R2_ENDPOINT=https://account-id.r2.cloudflarestorage.com

2. Backup directly to S3:

slipway db:backup mydb --to-s3

Output:

Creating backup of 'mydb'...
✓ Backup created: mydb-2024-01-20-143022.sql.gz (2.3 MB)
✓ Uploaded to S3: s3://my-backups/slipway/backups/mydb-2024-01-20-143022.sql.gz

3. Configure automatic S3 backups:

# Enable automatic daily backups to S3
slipway db:update mydb --backup-to-s3=true --backup-schedule="0 3 * * *"

Backup Schedule Format

The schedule uses cron format: minute hour day month weekday

• 0 3 * * * - Daily at 3 AM
• 0 3 * * 0 - Weekly on Sundays at 3 AM
• 0 */6 * * * - Every 6 hours

List Backups

slipway db:backups mydb

Output:

BACKUP                           SIZE      LOCATION    CREATED
mydb-2024-01-20-143022.sql.gz   2.3 MB    s3          2 hours ago
mydb-2024-01-19-100000.sql.gz   2.1 MB    s3          1 day ago
mydb-2024-01-18-100000.sql.gz   2.0 MB    local       2 days ago

Restore from Backup

# Restore from local backup
slipway db:restore mydb mydb-2024-01-20-143022.sql.gz

# Restore from S3 backup
slipway db:restore mydb mydb-2024-01-20-143022.sql.gz --from-s3

Destructive Operation

Restoring a backup will replace all data in the database. Make sure you have a recent backup before restoring.

Large backups and restores

Backup creation, object-storage upload/download, restore, and Dock SQL imports are streamed through files and child processes instead of being buffered into Slipway's memory. Slipway checks disk capacity before materializing temporary data and enforces configured byte limits while streaming.

This lets backup size be governed by available disk and configured limits rather than the Slipway Node.js process heap. A failed stream or database process produces an explicit error and cleans up its temporary files.

Download Backup

Download a backup to your local machine:

# From local storage
slipway db:backup:download mydb mydb-2024-01-20-143022.sql.gz

# From S3
slipway db:backup:download mydb mydb-2024-01-20-143022.sql.gz --from-s3

Backup Retention

Configure how long to keep backups:

# Keep backups for 30 days
slipway db:update mydb --backup-retention=30d

# Keep last 10 backups
slipway db:update mydb --backup-retention=10

Database Versions

Supported Versions

Database	Versions
PostgreSQL	16 (default), 15, 14, 13
MySQL	8.0 (default), 5.7
Redis	7 (default), 6
MongoDB	7 (default), 6, 5

Specifying Version

slipway db:create mydb --type=postgres --version=15

Connection Pooling

For high-traffic applications, Slipway automatically configures connection pooling:

• PostgreSQL: PgBouncer (optional)
• MySQL: ProxySQL (optional)

Enable pooling when creating a database:

slipway db:create mydb --type=postgres --pooling

Best Practices

1. Use Meaningful Names

# Good - descriptive names
slipway db:create myapp-production --type=postgres
slipway db:create myapp-cache --type=redis

# Avoid - generic names
slipway db:create db1 --type=postgres

2. Separate Databases per Environment

# Production
slipway db:create myapp-prod-db --type=postgres
slipway db:link myapp-prod-db myapp --env=production

# Staging
slipway db:create myapp-staging-db --type=postgres
slipway db:link myapp-staging-db myapp --env=staging

3. Regular Backups

Set up automated backups (coming soon) or run manual backups before major changes:

# Before a migration
slipway db:backup mydb
slipway slide --message "Run migrations"

4. Use Redis for Sessions in Production

# Create Redis for sessions
slipway db:create sessions --type=redis
slipway db:link sessions myapp

Then configure Sails:

// config/env/production.js
module.exports = {
  session: {
    adapter: '@sailshq/connect-redis',
    url: process.env.REDIS_URL
  }
}

Troubleshooting

Connection Refused

If your app can't connect to the database:

1. Verify the database is running:

   slipway db:info mydb

2. Check if the database is linked:

   slipway db:list

3. Verify environment variables:

   slipway env:list myapp

Database Won't Start

Check the database logs:

slipway db:logs mydb

Common issues:

• Out of disk space: Free up space or resize your server
• Out of memory: Reduce max_connections or upgrade server
• Corrupted data: Restore from backup

Slow Queries

1. Connect to the database:

   slipway db:connect mydb

2. For PostgreSQL, check slow queries:

   SELECT query, calls, mean_time
   FROM pg_stat_statements
   ORDER BY mean_time DESC
   LIMIT 10;

What's Next?

• Learn about Helm for querying your database via the Sails REPL
• Set up Environment Variables for other configuration
• Configure Auto-Deploy for continuous deployment

External PostgreSQL

You can connect an existing PostgreSQL 14–17 database to an environment without moving it to Slipway's Docker host. Under Add service, select External PostgreSQL, name the connection, enter its PostgreSQL URL, and select Connect. Then use Verify connection on the service page. Registering and editing connections requires a team owner or administrator.

Verification reports Unverified, Reachable, or Unreachable. It checks access from Slipway's client network, including DNS, TCP, TLS, authentication and read permissions. Reachable describes the last check; a successful backup confirms actual dump access. It is not continuous monitoring or a high-availability guarantee.

Verified TLS is the default. The hostname must match the server certificate; an optional PEM CA supports private trust chains. Unverified encryption or plaintext requires explicit acknowledgement. Allow the Slipway server's outbound address through your database firewall, and make private DNS/VPN routes available from the slipway Docker network. No inbound public database port is opened. The URL accepts only the sslmode query parameter, matching the selected TLS setting.

Slipway saves the encrypted connection as a managed secret: DATABASE_URL if available, otherwise <SERVICE_NAME>_URL. A custom CA is available as <CONNECTION_VARIABLE>_CA_CERT. Configure your application's database driver to use the appropriate TLS policy and CA; Slipway's verification configures its own client, not arbitrary application libraries. Readiness recognizes the verified connection when it matches the effective runtime configuration. Existing variables are preserved and saved connection values are omitted from browser/API responses.

Use Edit connection to rotate credentials. Blank URL and CA fields keep saved values. Saving resets verification and preserves unrelated variables. Verify again and redeploy applications to apply changed connection settings; running apps are not restarted automatically.

After configuring private backup storage and verifying the connection, create a manual backup or include the service in the instance backup schedule. Slipway uses a temporary PostgreSQL 17 client pinned to an immutable image, with bounded resources, private memory-backed credentials, and size/time-limited dumps. Existing private storage, checksum, notification and retention handling applies. Docker and access to the PostgreSQL client image are required; interrupted client cleanup is retried.

These are single-database logical backups, not physical snapshots or point-in-time recovery. Restore into an external database is disabled. Recover through your provider or a reviewed pg_restore workflow into a separate database, verify the result, then deliberately change your application's connection. Slipway does not stop, restart, upgrade or delete the external database server. Existing managed database services keep their current lifecycle.