Connect to your database

Once you have provisioned a database, your services need to reach it. Helicarrier gives you two paths: an automatic internal link for service-to-service traffic, and external credentials for tools on your own machine.

Internal vs external URLs

• Internal URL — how your other services reach the database over Helicarrier’s private network. It never leaves the platform, so it is fast and does not require exposing the database publicly.
• External URL — how tools outside Helicarrier (a local psql, a GUI client, a migration script) connect. External access is off by default for safety; enable it on the database when you need it (see below).

Both are shown on the database’s Connect panel, along with the individual credentials (host, port, user, password, database name).

Link a service (recommended)

The cleanest way to connect an app to a database is to link them, so the connection string is injected as an environment variable automatically:

1. On the canvas, drag an edge from your service to the database — or use the Reference a variable option on the service’s Variables tab.
2. Helicarrier injects the right variable into your service, for example DATABASE_URL for Postgres or REDIS_URL for Redis.

Because the value is a reference (not a copied string), it always tracks the database’s current credentials — if the database is re-provisioned or its password rotates, linked services follow automatically on their next deploy. You can rename the injected key if your app expects a different name. See Service references for more.

Connect from external tools

To connect from your laptop or an external service:

1. On the database, enable external access. By default the database only accepts connections from inside the platform (loopback-only); enabling external access exposes it off-box.
2. Optionally turn on TLS to encrypt the connection (additive — existing plaintext connections keep working).
3. Use the external URL and credentials from the Connect panel.

Note

Leave external access off unless you actually need it. Service-to-service traffic uses the internal URL and never requires exposing the database to the internet.

Reconnecting after a restart

A database restarts whenever it is redeployed, resized, upgraded, or picks up a renewed certificate. Each restart replaces the container, and for a few seconds its internal hostname does not resolve. Clients see one of:

dial tcp: lookup heli-<id> on 127.0.0.11:53: server misbehaving
connection refused

This is normal and short — typically two to five seconds. Configure your client to retry, and it becomes invisible:

// go-redis — retry rather than giving up on the first failures
redis.NewClient(&redis.Options{
    Addr:            fmt.Sprintf("%s:%s", os.Getenv("REDIS_HOST"), os.Getenv("REDIS_PORT")),
    MaxRetries:      10,
    MinRetryBackoff: 100 * time.Millisecond,
    MaxRetryBackoff: 3 * time.Second,
})

Most pooled clients have equivalents — retryStrategy in ioredis, retry_on_timeout with health_check_interval in redis-py, and connection-pool pool_pre_ping in SQLAlchemy. The principle is the same everywhere: treat a failed dial as retryable, not fatal.

Caution

Switching to the external URL to avoid this is the wrong fix. It sends your traffic out to the public internet and back for every command, adds TLS handshakes and latency to a connection that was already private, and still breaks during the same restart. Keep the internal address and let the client retry.

If your app resolves the address once at startup and caches it, restart the app after the database finishes restarting — or better, use a service reference so the address is injected and tracked for you.

TLS and certificates

With TLS enabled, your database serves a publicly-trusted certificate issued by Let’s Encrypt, covering its *.on.helicarrier.xyz hostname.

That means you connect with certificate verification on, and there is nothing to download or import — the certificate chains to the same public roots your operating system and language runtime already trust:

# Redis
redis-cli --tls -u rediss://default:<password>@<db>.on.helicarrier.xyz:<port>

# Postgres — full verification, including the hostname
psql "postgresql://<user>:<password>@<db>.on.helicarrier.xyz:<port>/<db>?sslmode=verify-full"

In GUI tools such as Redis Insight, TablePlus, DBeaver or MongoDB Compass, simply enable TLS/SSL and leave the CA field empty. Do not turn on “allow insecure certificates” or supply a custom CA — neither is needed, and both weaken the connection.

TLS is additive: turning it on does not break clients that are already connecting in plaintext, so you can enable it before your applications are ready for it.

Verifying it yourself

openssl s_client -connect <db>.on.helicarrier.xyz:<port> \
  -servername <db>.on.helicarrier.xyz -verify_hostname <db>.on.helicarrier.xyz </dev/null

A healthy connection reports Verify return code: 0 (ok) and an issuer of Let’s Encrypt.

Note

Postgres, MySQL and MariaDB negotiate TLS after the connection opens (StartTLS), so a plain openssl s_client will appear to return nothing for them. Add -starttls postgres or -starttls mysql to inspect their certificate.

Certificates renew automatically. A renewal restarts the database briefly so it picks up the new certificate — databases read their certificate once at startup — so expect a short reconnect roughly every two months. Clients that reconnect automatically will not notice.

Object storage (Heli Bucket) and Qdrant are HTTP services rather than wire-protocol databases, so this toggle does not apply to them.

Next

Protect your data with Backups & restore.