Memcached - Convox

Overview

Memcached is a high-performance, distributed memory caching system. Convox supports both containerized Memcached and AWS ElastiCache-managed instances.

Basic Configuration

Define a Memcached resource in convox.yml:

resources:
  cache:
    type: memcached

services:
  web:
    resources:
      - cache

Containerized Memcached

For development and staging environments, use containerized Memcached:

resources:
  cache:
    type: memcached

Custom Images

Use custom Memcached images:

resources:
  cache:
    type: memcached
    image: memcached:1.6-alpine

The image field allows you to use any compatible Memcached image. Always include an image tag.

AWS ElastiCache Memcached

For production workloads requiring horizontal scaling, use AWS ElastiCache:

resources:
  cache:
    type: elasticache-memcached
    options:
      class: cache.t3.micro
      version: "1.6.6"
      nodes: 2
      deletionProtection: true

Configuration Options

nodes

integer

required

Required. The number of cache nodes in the Memcached cluster. Memcached scales horizontally by adding nodes.

class

string

required

The compute and memory capacity per cache node. Common values:

cache.t3.micro - 0.5 GiB memory
cache.t3.small - 1.37 GiB memory
cache.t3.medium - 3.09 GiB memory
cache.m5.large - 6.38 GiB memory
cache.r5.large - 13.07 GiB memory (memory-optimized)

version

string

required

Memcached engine version (e.g., 1.6.6, 1.6.17)

deletionProtection

boolean

default:"false"

Prevent accidental deletion of the cache cluster. This is a Convox-managed feature that prevents resource removal even if deleted from convox.yml.

durable

boolean

default:"false"

Spread cache nodes across multiple Availability Zones for improved availability

encrypted

boolean

default:"false"

Enable encryption at rest for data stored on disk

autoMinorVersionUpgrade

boolean

default:"true"

Automatically apply minor engine version patches during maintenance windows

import

string

ElastiCache cluster ID to import an existing cluster

deletionProtection is a Convox feature, not an AWS feature. It prevents the resource from being deleted if removed from convox.yml.

The nodes parameter is required for ElastiCache Memcached. Set it to the desired number of cache nodes for your cluster.

Advanced Features

Horizontal Scaling

Memcached scales horizontally by adding more nodes:

resources:
  cache:
    type: elasticache-memcached
    options:
      class: cache.t3.medium
      version: "1.6.17"
      nodes: 3
      durable: true

To scale up, increase the nodes value and redeploy. To scale down, decrease the value. Total cache capacity = (node memory) × (number of nodes).

Multi-AZ Deployment

Distribute nodes across Availability Zones for improved availability:

resources:
  cache:
    type: elasticache-memcached
    options:
      class: cache.m5.large
      version: "1.6.17"
      nodes: 2
      durable: true
      deletionProtection: true

Import Existing ElastiCache

Import an existing AWS ElastiCache Memcached cluster:

resources:
  imported-cache:
    type: elasticache-memcached
    options:
      import: my-existing-memcached-cluster
      nodes: 2

services:
  web:
    resources:
      - imported-cache

import

string

The cluster ID of the existing ElastiCache Memcached cluster

While import is set, the cache cluster is read-only from Convox’s perspective. Remove import to allow Convox to manage the cluster configuration.

Environment Variables

When linked to a service, Memcached resources inject these environment variables:

CACHE_URL=memcached://hostname:11211
CACHE_HOST=hostname
CACHE_PORT=11211

For multi-node clusters, the URL may include multiple endpoints:

CACHE_URL=memcached://node1:11211,node2:11211,node3:11211

CLI Operations

List Resources

$ convox resources -a myapp
NAME   TYPE                   URL
cache  elasticache-memcached  memcached://hostname:11211

Get Resource Information

$ convox resources info cache -a myapp
Name  cache
Type  elasticache-memcached
URL   memcached://hostname:11211

Proxy to Memcached

Create a local tunnel to the Memcached cluster:

$ convox resources proxy cache -a myapp
Proxying localhost:11211 to hostname:11211

Connect using telnet:

telnet localhost 11211

The proxy command is particularly useful for ElastiCache instances that are not publicly accessible.

Connection Examples

Node.js
Python
Ruby
PHP

const Memcached = require('memcached');

// Parse the CACHE_URL to get host(s)
const cacheUrl = process.env.CACHE_URL.replace('memcached://', '');
const memcached = new Memcached(cacheUrl);

memcached.set('key', 'value', 3600, (err) => {
  if (err) console.error(err);
});

memcached.get('key', (err, data) => {
  console.log(data);
});

from pymemcache.client.base import Client
import os

# Parse CACHE_HOST from environment
host = os.environ['CACHE_HOST']
port = int(os.environ['CACHE_PORT'])

client = Client((host, port))

client.set('key', 'value', expire=3600)
value = client.get('key')

require 'dalli'

# Parse CACHE_URL
cache_url = ENV['CACHE_URL'].gsub('memcached://', '')

dc = Dalli::Client.new(cache_url)

dc.set('key', 'value', 3600)
value = dc.get('key')

<?php
$memcached = new Memcached();

// Parse CACHE_HOST and CACHE_PORT
$host = getenv('CACHE_HOST');
$port = intval(getenv('CACHE_PORT'));

$memcached->addServer($host, $port);

$memcached->set('key', 'value', 3600);
$value = $memcached->get('key');
?>

Memcached vs Redis

Choose Memcached when:

Simple Caching

You need simple key-value storage without complex data structures

Horizontal Scaling

You want to scale by adding more nodes (Memcached’s strength)

Multi-threaded

You want to take advantage of multi-core processors

Large Cache

You need to cache large amounts of data across multiple nodes

Choose Redis when:

Complex Data Types

You need lists, sets, sorted sets, or other data structures

Persistence

You need data persistence or replication

Pub/Sub

You need publish/subscribe messaging patterns

Transactions

You need atomic operations or transactions

Production Best Practices

Enable Deletion Protection

Set deletionProtection: true to prevent accidental deletion of production cache clusters.

Use Multiple Nodes

Deploy at least 2 nodes for better availability and horizontal scaling.

Enable Multi-AZ

Set durable: true to distribute nodes across Availability Zones.

Monitor Memory Usage

Track cache hit rates and memory usage to optimize node count and size.

Common Use Cases

Page Caching

Cache rendered HTML pages to reduce server load and improve response times.

Database Query Cache

Store frequently accessed database query results.

Session Storage

Store user session data across multiple web servers.

API Response Cache

Cache external API responses to reduce latency and API costs.

Example Configurations

Development
Staging
Production

resources:
  cache:
    type: memcached

services:
  web:
    resources:
      - cache

resources:
  cache:
    type: elasticache-memcached
    options:
      class: cache.t3.small
      version: "1.6.17"
      nodes: 2

services:
  web:
    resources:
      - cache

resources:
  cache:
    type: elasticache-memcached
    options:
      class: cache.m5.large
      version: "1.6.17"
      nodes: 3
      durable: true
      deletionProtection: true
      encrypted: true
      autoMinorVersionUpgrade: true

services:
  web:
    resources:
      - cache
  worker:
    resources:
      - cache

Primitives

App Primitives

Resources

CLI Reference

​Overview

​Basic Configuration

​Containerized Memcached

​Custom Images

​AWS ElastiCache Memcached

​Configuration Options

​Advanced Features

​Horizontal Scaling

​Multi-AZ Deployment

​Import Existing ElastiCache

​Environment Variables

​CLI Operations

​List Resources

​Get Resource Information

​Proxy to Memcached

​Connection Examples

​Memcached vs Redis

Simple Caching

Horizontal Scaling

Multi-threaded

Large Cache

Complex Data Types

Persistence

Pub/Sub

Transactions

​Production Best Practices

Enable Deletion Protection

Use Multiple Nodes

Enable Multi-AZ

Monitor Memory Usage

​Common Use Cases

Page Caching

Database Query Cache

Session Storage

API Response Cache

​Example Configurations

Build docs developers (and LLMs) love

Overview

Basic Configuration

Containerized Memcached

Custom Images

AWS ElastiCache Memcached

Configuration Options

Advanced Features

Horizontal Scaling

Multi-AZ Deployment

Import Existing ElastiCache

Environment Variables

CLI Operations

List Resources

Get Resource Information

Proxy to Memcached

Connection Examples

Memcached vs Redis

Production Best Practices

Common Use Cases

Example Configurations