Skip to main content

Service Connections

Link your containers and jobs to managed services and let SailOps inject credentials automatically.

Service connections provide a secure, declarative way to wire your containers and jobs to managed services such as PostgreSQL, MariaDB, Valkey, NATS, and Object Storage. When you create a connection, SailOps automatically injects the appropriate environment variables into the source workload so your application can connect without manual configuration.

How Connections Work​

A connection binds a source (container or job) to a target (a managed service). Once created:

  1. SailOps generates environment variables with the service credentials
  2. The variables are injected into the source workload's configuration
  3. The source is automatically restarted so it picks up the new variables (containers are redeployed; CronJobs pick up changes on the next execution)
  4. Your application reads the standard environment variables to connect
No Manual Config Required

You never need to copy-paste hostnames, ports, or passwords. Connections handle all of that for you.

Supported Services​

Target ServiceURL VariableIndividual Variables
PostgreSQLDATABASE_URLPGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGXPOOL_MAX_CONNS (when connection pooling is enabled)
MariaDBDATABASE_URLMYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD
ValkeyREDIS_URL, CACHE_URLREDIS_HOST, REDIS_PORT, REDIS_PASSWORD
NATSNATS_URLNATS_HOST, NATS_PORT, NATS_USER, NATS_PASSWORD
Object Storage—ACCESS_KEY_ID, SECRET_ACCESS_KEY, ENDPOINT_URL, ENDPOINT_URL_S3, REGION, DEFAULT_REGION, BUCKET_NAME, S3_FORCE_PATH_STYLE

Alias Prefix​

Every connection has an alias that acts as a prefix for the injected variables. This lets you connect a single container to multiple services of the same type without variable name collisions.

The alias must be uppercase letters, numbers, and underscores, starting with a letter (pattern: ^[A-Z][A-Z0-9_]*$).

How the Alias Affects Variable Names​

  • The primary URL variable uses the alias directly as its name
  • All other variables are prefixed with ALIAS_

Example with alias ANALYTICS connected to PostgreSQL:

ANALYTICS=postgresql://user:pass@host:5432/mydb?application_name=my-container
ANALYTICS_PGHOST=my-pg.my-project-abc123
ANALYTICS_PGPORT=5432
ANALYTICS_PGDATABASE=mydb
ANALYTICS_PGUSER=user
ANALYTICS_PGPASSWORD=s3cret

Example with alias CACHE connected to Valkey:

CACHE=redis://:[email protected]:6379
CACHE_CACHE_URL=redis://:[email protected]:6379
CACHE_REDIS_HOST=my-cache.my-project-abc123
CACHE_REDIS_PORT=6379
CACHE_REDIS_PASSWORD=s3cret

Example with alias AWS connected to Object Storage bucket media:

AWS_ACCESS_KEY_ID=<access-key>
AWS_SECRET_ACCESS_KEY=<secret-key>
AWS_ENDPOINT_URL=https://s3.example.com
AWS_ENDPOINT_URL_S3=https://s3.example.com
AWS_REGION=us-east-1
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET_NAME=media
AWS_S3_FORCE_PATH_STYLE=true
Object Storage alias

Use AWS as the alias for Object Storage connections. Most AWS SDKs automatically read AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, AWS_DEFAULT_REGION and other AWS_-prefixed variables without extra code.

PostgreSQL DSN details

The DATABASE_URL includes an application_name query parameter set to the source container or job name. This helps identify connections in PostgreSQL monitoring tools (pg_stat_activity). When connection pooling is enabled on the target PostgreSQL cluster, SailOps also injects PGXPOOL_MAX_CONNS with the configured default pool size.

Why CACHE_CACHE_URL?

The CACHE_CACHE_URL variable looks redundant because the alias CACHE is prepended to the standard suffix _CACHE_URL. If you choose a different alias like SESSION, the variable becomes SESSION_CACHE_URL which reads more naturally. The primary URL variable (CACHE) always uses the alias directly without any suffix.

Access Levels​

Access LevelDescription
fullRead, write, and administrative access to the service (default for databases)
readwriteStandard read and write access without administrative privileges (default for Object Storage)
readonlyRead-only access, useful for replicas or reporting workloads

For Object Storage, the access levels control specific S3 actions on the connected bucket:

Access LevelPermissions
readonlyRead objects, previous versions and listings
readwriteRead, upload and delete objects
fullRead, write and permanently delete individual versions
warning

The full access level grants permanent version deletion, which cannot be undone. Bucket settings, policies and user administration are never granted through connections.

tip

Use readonly access for containers that only need to read data, such as analytics dashboards or read replicas. This follows the principle of least privilege.

Creating a Connection​

From an Existing Service​

  1. Navigate to Containers and select your container
  2. Go to the Connections tab
  3. Click New Connection
  4. Select the Source type (container or job) and the source name
  5. Select the Target type (Object Storage, PostgreSQL, MariaDB, Valkey, or NATS) and the target service
  6. Enter an Alias for the variable prefix (e.g., MYDB, CACHE, EVENTS)
  7. Choose the Access level (full, readwrite, or readonly)
  8. Optionally enable Dedicated database (PostgreSQL/MariaDB only) to create an isolated database on the target cluster
  9. Click Create
Auto-Redeploy

By default, creating a connection automatically redeploys the source container so it picks up the new environment variables. You can disable this if you prefer to redeploy manually.

Object Storage connections

Object Storage connections target an existing bucket — the bucket must be created first. The Create with Service option is not available for Object Storage.

Create with Service​

The Create with Service option lets you provision a new managed service and connect it to your container in a single atomic operation. This is useful when you need a new database or cache dedicated to a specific workload.

  1. Navigate to your container's Connections tab
  2. Click New Connection with Service
  3. Select the Service type (postgresql, mariadb, valkey, or nats)
  4. Configure the new service:
    • Service name: lowercase letters, numbers, and hyphens
    • Flavor: small, medium, large, or xlarge
    • Compute class: eco, standard, or production
    • Storage size: e.g., 10Gi, 20Gi (required for databases)
  5. Select the Source type and source name
  6. Click Create

SailOps creates the service, generates credentials, creates the connection, injects environment variables, and redeploys the container -- all in one step.

Dedicated Database​

When connecting to PostgreSQL or MariaDB, you can enable the Dedicated database option. This creates a new, isolated database on the existing cluster specifically for this connection, along with a dedicated user. This provides better isolation between workloads sharing the same database cluster.

Job Connections​

Jobs and CronJobs have their own Connections tab.

  • CronJobs support full connection management: add, edit, and delete connections at any time. Changes take effect on the next scheduled execution.
  • One-time Jobs show connections in read-only mode because a Job's pod template is immutable after creation. Connections must be declared when the job is created.

Managing Connections​

Viewing Connections​

Go to your container's or job's Connections tab to see all active connections with their:

  • Target service type and name
  • Alias prefix
  • Access level
  • Creation date

Viewing Injected Variables​

Click on a connection to see the environment variables it injects. Sensitive values (passwords, connection URLs with credentials) are masked in the UI for security.

Deleting a Connection​

  1. Go to the container's Connections tab
  2. Click the delete button on the connection
  3. Confirm the deletion
Environment Variable Removal

Deleting a connection removes all associated environment variables from the source workload. Make sure your application can handle the absence of these variables, or it may fail to start after the next deployment.

Best Practices​

Use Meaningful Aliases​

Choose aliases that describe the purpose of the connection, not the service type:

# Good - describes the purpose
ANALYTICS_DB
SESSION_CACHE
EVENT_BUS

# Avoid - just repeats the service type
POSTGRESQL
REDIS
NATS

Prefer Readonly for Read-Heavy Workloads​

If a container only reads data (e.g., a reporting dashboard, an API that only queries), use the readonly access level. This improves security and can leverage read replicas where available.

One Connection Per Purpose​

Rather than sharing a single database connection across many containers, create separate connections with dedicated databases. This provides better isolation and makes it easier to track which workload uses which resources.

Let Auto-Redeploy Handle Restarts​

Keep auto-redeploy enabled so your containers always have the latest credentials. If you disable it, remember to manually redeploy after creating or deleting connections.