Docs

Redis

Redis is a managed, in-memory store next to your code, for caches, queues, locks, streams, and pub/sub. Your code keeps its usual client: ioredis, node-redis, redis-py, or BullMQ. It has no public endpoint: only workloads in the same deployment can reach it.

alien.ts
import * as alien from "@alienplatform/core"

const cache = new alien.Redis("cache")
  .memory("4Gi")
  .evictionPolicy("volatile-lru")
  .build()

const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
  .cpu(1)
  .memory("1Gi")
  .port(8080)
  .link(cache)
  .permissions("execution")
  .build()

export default new alien.Stack("acme")
  .add(cache, "frozen")
  .add(api, "live")
  .permissions({ profiles: { execution: { cache: ["redis/data-access"] } } })
  .build()

In this stack:

  • .link(cache) connects the server to the api Container, the workload (the running code) that uses it. Alien injects the server's connection details, its binding, into the Container.
  • The execution permission profile, the named set of cloud permissions a workload runs with, grants redis/data-access.
  • "frozen" means the customer's admin creates the server during initial setup. "live" resources, like the Container, are created and updated by Alien on every release. See Frozen and live.

The api Container reads the connection details from the binding and connects with its usual client:

src/cache.ts
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,
})

Platforms

cache becomes a single-endpoint server on a private network:

PlatformBacking serviceCreated by
AWSElastiCache for Valkey 9.0, a replication group with cluster mode disabledAlien
Google CloudMemorystore for Valkey 9.0, instance mode CLUSTER_DISABLED, reached through Private Service ConnectAlien
AzureAzure Managed Redis (Redis 7.4), clustering policy NoCluster, reached through a private endpointAlien
KubernetesAny Redis-compatible server the customer providesThe customer, through an external binding
MachinesAny Redis-compatible server the customer providesThe customer, through an external binding. The resource must be "frozen". See Machines.
LocalThe official Valkey 9.0 image, run in DockerAlien

On AWS, Google Cloud, and Azure, a Redis resource adds a Network to the stack, because the server lives on a private network.

Every platform runs a single shard with one endpoint. Multi-key Lua scripts, MULTI/EXEC, Streams, pub/sub, and blocking commands work as on a plain Redis server, with no hash tags needed. Cluster mode is not offered.

Frozen or live

Redis can be "frozen" or "live":

  • Frozen: the setup template creates the server during initial setup, and Alien monitors it.
  • Live: Alien creates, updates, and deletes it.

See Frozen and live.

Alternatives

The binding only resolves connection details. You connect with your usual client.

  • For small values looked up by key with a TTL, and no server to size, use KV.
  • For a managed message queue, use Queue.
  • For relational data, use Postgres.

Options

MethodTypeDefaultNotes
.memory(v)stringsmallest tier of at least 1 GiBMemory for data, a binary unit (Ki, Mi, Gi, Ti), such as "4Gi". A number without a unit means GiB. Alien picks the smallest tier that fits. Larger than the biggest single-endpoint tier is rejected, not capped. See sizing.
.evictionPolicy(p)"noeviction" | "allkeys-lru" | "allkeys-lfu" | "allkeys-random" | "volatile-lru" | "volatile-lfu" | "volatile-random" | "volatile-ttl""volatile-lru"What the server does when memory is full. volatile-* policies only evict keys that have a TTL. Queues such as BullMQ need "noeviction". Pure caches usually want "allkeys-lru".
.persistence(on = true)booleanfalseKeep data across a restart or maintenance. On AWS, Google Cloud, and Azure it requires .highAvailability(). See Persistence.
.highAvailability(on = true)booleanfalseOne replica in another zone with automatic failover. Can't change after the server exists. No effect on Local.
.encryptionKey(key)Keyprovider-managed keyEncrypts data at rest with a customer-managed Key. Can't change after the server exists.
.enabled(input)boolean stack inputalways onCreates the resource only when the input is true.

Not options: engine and version, node size, cluster mode, public access, TLS, authentication, and the port. Alien sets them, and TLS and a password are always on in the clouds.

Use it from code

redis(name).connection() returns everything a client needs. On AWS, Google Cloud, and Azure it reads the password from the cloud with the workload's own identity.

src/cache.ts
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,
})

await client.set("greeting", "hello", "EX", 60)

With node-redis, pass the same fields:

import { createClient } from "redis"

const client = createClient({
  url: conn.url,
  socket: conn.tls ? { tls: true, ...conn.tls } : undefined,
})
await client.connect()

With BullMQ, pass the connection options and set maxRetriesPerRequest: null, which BullMQ requires:

import { Queue } from "bullmq"

const queue = new Queue("jobs", {
  connection: {
    host: conn.host,
    port: conn.port,
    username: conn.username,
    password: conn.password,
    tls: conn.tls || undefined,
    maxRetriesPerRequest: null,
  },
})

Set the queue's server to .evictionPolicy("noeviction").

Every connection field is in the API reference.

Common patterns

Apps that read REDIS_URL

If your app reads one environment variable at startup, set it before importing the module that creates the client:

src/index.ts
import { redis } from "@alienplatform/sdk"

process.env.REDIS_URL = (await redis("cache").connection()).url
await import("./app.js")

url has the username and password percent-encoded, so a generated password can't break it. If your app takes TLS and the database index as separate settings, such as REDIS_SSL=true and REDIS_DB=0, set those from conn.tls and conn.database. The database is always 0.

Queues

BullMQ and similar job queues store jobs as keys without a TTL. Use .evictionPolicy("noeviction") so the server rejects writes when full instead of dropping jobs, and alert on memory use.

Caches

For a pure cache, use .evictionPolicy("allkeys-lru") and leave persistence off. Code should treat any key as able to disappear.

Permissions

SetGrants
redis/data-accessReading the connection password: the Secrets Manager secret on AWS, the instance's auth token in Memorystore on Google Cloud, and listing access keys on the one database on Azure.
redis/heartbeatUsed by Alien's management identity to read server status and memory metrics.

On AWS, a "live" Redis resource takes the grant at stack scope, execution: { "*": ["redis/data-access"] }. The deploy refuses a grant on the resource ID, because exact-resource policies on AWS are created at initial setup. A "frozen" server, like cache above, can take either.

Network access is separate from permissions. On the clouds, only workloads in the deployment's network can reach the server. See Permissions.

Next

On this page