Bind a cache

Bind an app to a managed Valkey cache so that every rollout generates REDIS_URL and VALKEY_URL with the cache's private address.

Last updated 18 November 2026View as Markdown

Every rollout generates REDIS_URL and VALKEY_URL (redis://default:<password>@<private address>:<port>, rediss:// for a cache with TLS), with a prefix if you give one (SESSIONS_REDIS_URL). A highly available cache adds REDIS_READ_URL, REDIS_SENTINELS and REDIS_SENTINEL_MASTER. The password is read from the cache at each rollout, so nothing is stored with the app. An app has one cache binding per prefix: binding again with the same prefix replaces the cache it points at. Replace app-id with the app's id and ewc-0123456789ab with the cache's id.

Prerequisites

  • A managed Valkey cache whose status is available. Every machine of the app must be in the cache's network; an app without machines yet can bind only a cache in the organization's default network, where its machines will run.
  • Permission for deploy:ManageCacheBinding on the app and cache:ModifyCacheCluster on the cache. To redeploy in the same step, deploy:DeployApp.
  • In the console, also deploy:DescribeApp to open the app's page (without it the page is not found).

Bind the cache

  1. Open the app, then choose the Environment tab. Under Connected resources, choose Connect a resource, then Valkey cache (offered with deploy:ManageCacheBinding).
  2. For Cache, choose the cache. Only available caches are listed.
  3. (Optional) For Variable prefix, enter a prefix such as SESSIONS_.
  4. Leave Redeploy now on to apply it at once (offered with deploy:DeployApp), then choose Bind cache. The binding is listed under Connected resources with the variables it generates; its row's panel shows the private address.

The binding is refused (409) when:

  • the cache is not available yet (The cache <id> is <status>; bind it once it is available) or has no private address;
  • a machine of the app is outside the cache's network (The cache <id> is reachable only inside its network, and <machine> is not in it), or, for an app without machines, the cache is not in the default network;
  • the app's environment or a database binding already defines one of the generated variables (Remove <keys> from the environment first: the binding generates them);
  • the app is being deleted.

Unbind

In the binding's row choose Unbind, or run dcloud deploy cache unbind app-id --env-prefix SESSIONS_ (leave out --env-prefix for a binding without a prefix). The variables are left out of the next rollout; the cache is unchanged.

Result

Saving does not restart the app. With Redeploy now (--redeploy) the live deployment's source is rolled out again with the new variables; otherwise the variables reach the app with its next rollout.

Did this page help you?