Docs

Redis API reference

The Redis API is how your code finds and authenticates to a linked Redis server. Its binding is the connection details Alien injects into each workload linked to the resource: where the server is and how to authenticate.

Your code connects with its own client: the binding wraps no commands, because every backend speaks the Redis protocol.

A handle comes from these calls, where name is the resource ID from alien.ts:

  • TypeScript: redis(name) from @alienplatform/sdk
  • Python: redis(name) from alienplatform
  • Rust: Bindings::from_env()?.redis(name).await? from alien-sdk

connection

Returns the connection details.

import { redis } from "@alienplatform/sdk"
import { Redis } from "ioredis"

const conn = await redis("cache").connection()

const client = new Redis({
  host: conn.host,
  port: conn.port,
  username: conn.username,
  password: conn.password,
  tls: conn.tls || undefined,
})

On AWS, Google Cloud, and Azure, resolving the binding reads the password from the cloud with the workload's identity. To pick up a rotated password, create a new handle with redis(name) and call connection() again.

RedisConnection

type RedisConnection = {
  url: string        // redis:// locally, otherwise rediss://user:password@host:port/0
  host: string
  port: number       // 6379 on AWS, Google Cloud, and Local; 10000 on Azure
  username: string
  password: string
  database: 0
  tls: false | { ca?: string[]; servername?: string }
}
  • url percent-encodes the username and password, so a generated password with URL-special characters can't break it.
  • tls is false on Local. Otherwise it's an object you can pass to ioredis as tls, or spread into node-redis socket options with tls: true. ca holds the provider's PEM certificates when the provider signs with its own CA (Google Cloud). It's absent when the system trust store applies (AWS and Azure).

Python's RedisConnection has url, host, port, username, password, tls, ca_certificates, and database, plus helpers:

MethodReturns
ssl_context()An ssl.SSLContext that trusts ca_certificates. None when tls is false.
redis_kwargs()Keyword arguments for redis.asyncio.Redis(...).

The Python repr hides the password.

Rust returns RedisConnectionParams with host, port, username, password, and tls, plus connection_url(). Its Debug output hides the password.

TLS

PlatformTLSTrust
AWSOnSystem trust store.
Google CloudOnThe instance's CA chain, two certificates, carried in the binding. The certificate lists the endpoint's IP, so no server name override is needed.
AzureOnSystem trust store.
LocalOffNone. The server is reachable only from your machine.
ExternalOn by default. Off with tls: false.System trust store.

The binding

A linked Redis resource injects ALIEN_<NAME>_BINDING, uppercased with hyphens as underscores: cache becomes ALIEN_CACHE_BINDING. The SDKs read it for you. It's JSON tagged by service:

servicePlatformFields
elasticacheAWShost, port, username, passwordSecretArn
memorystoreGoogle Cloudhost, port, username, serverCaCertificates, instanceName
azure-managed-redisAzurehost, port, username, databaseResourceId
externalKubernetes, Machines, or your own serverhost, port, username, password, tls (default true)
local-redisLocalhost, port, username, password

The cloud variants never contain the password, only where to read it: a Secrets Manager ARN, the Memorystore instance whose auth token the workload reads, or the database whose access keys the workload lists. The workload's identity authorizes the read through redis/data-access.

External and Local carry the password inline. Keep it out of logs.

The username is default on AWS, Google Cloud, and Azure for the generated credentials. Read it from the connection instead of hard-coding it.

Errors

CodeRetryableWhen
REDIS_CREDENTIAL_RESOLUTION_FAILEDFollows the cloud errorReading the password failed, for example because the workload lacks redis/data-access. Throttling stays retryable.
REDIS_CREDENTIAL_INVALIDNoThe secret or key exists but isn't usable as a password.
BINDING_NOT_CONFIGUREDNoThe workload isn't linked to this resource.

Errors name where the credential was read from, never its value. Errors from the server itself come from your client.

On this page