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:
- SailOps generates environment variables with the service credentials
- The variables are injected into the source workload's configuration
- The source is automatically restarted so it picks up the new variables (containers are redeployed; CronJobs pick up changes on the next execution)
- Your application reads the standard environment variables to connect
You never need to copy-paste hostnames, ports, or passwords. Connections handle all of that for you.
Supported Services
| Target Service | URL Variable | Individual Variables |
|---|---|---|
| PostgreSQL | DATABASE_URL | PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGXPOOL_MAX_CONNS (when connection pooling is enabled) |
| MariaDB | DATABASE_URL | MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD |
| Valkey | REDIS_URL, CACHE_URL | REDIS_HOST, REDIS_PORT, REDIS_PASSWORD |
| NATS | NATS_URL | NATS_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
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.
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.
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 Level | Description |
|---|---|
| full | Read, write, and administrative access to the service (default for databases) |
| readwrite | Standard read and write access without administrative privileges (default for Object Storage) |
| readonly | Read-only access, useful for replicas or reporting workloads |
For Object Storage, the access levels control specific S3 actions on the connected bucket:
| Access Level | Permissions |
|---|---|
| readonly | Read objects, previous versions and listings |
| readwrite | Read, upload and delete objects |
| full | Read, write and permanently delete individual versions |
The full access level grants permanent version deletion, which cannot be undone. Bucket settings, policies and user administration are never granted through connections.
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
- Navigate to Containers and select your container
- Go to the Connections tab
- Click New Connection
- Select the Source type (container or job) and the source name
- Select the Target type (Object Storage, PostgreSQL, MariaDB, Valkey, or NATS) and the target service
- Enter an Alias for the variable prefix (e.g.,
MYDB,CACHE,EVENTS) - Choose the Access level (
full,readwrite, orreadonly) - Optionally enable Dedicated database (PostgreSQL/MariaDB only) to create an isolated database on the target cluster
- Click Create
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 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.
- Navigate to your container's Connections tab
- Click New Connection with Service
- Select the Service type (postgresql, mariadb, valkey, or nats)
- 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)
- Select the Source type and source name
- 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
- Go to the container's Connections tab
- Click the delete button on the connection
- Confirm the deletion
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.