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. The Cache section is shown only 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. Choose Bind, or Bind & redeploy (shown only with deploy:DeployApp). The binding is listed with its cache, its private address and the variables it generates.

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 Bind & redeploy (--redeploy) the live deployment's source is rolled out again with the new variables; otherwise the console says Not redeployed yet. Redeploy to apply. and the variables reach the app with its next rollout.

Did this page help you?