Last Updated October 2014

Memcached is a distributed memory caching system that caches data and objects in RAM and can be a great tool for optimizing your app. After reading this doc, you will be familiar with:

  • Adding a Memcached service to your app
  • Connecting to and using to your Memcached service

Memcached and Red Frowny Faces

Memcached services are by nature different from web and database services. Instead of using RAM to access information, Memcached uses RAM to store information. This means the more Memcached does what it's supposed to do (store cached files), the more RAM it will use. Eventually, it will use all the RAM allocated to it and start to drop the oldest cached files (just like it's designed to do).

So what does this mean? It means that a red frowny face on your Memcached service is totally normal. Scaling will allow you to store more information, but a Memcached service will commonly use most of its available RAM.

Creating a Memcached Service

Through the Dashboard

To create a Memcached service through your dashboard, click on "New Service," then click the Memcached icon.

You're given the option to name your Memcached service and select which version you'd like use. If no name is provided, we will create one for you. Click "Create Service" to begin provisioning your Memcached service.

Through the Boxfile

To creating a Memcached service through your Boxfile, include a cache service with the type set to "memcached". You can provide a name for your service if you'd like. If you don't provide one, we will generate one for you.

Creating a Memcached Service from Your Boxfile YAML

    type: memcached
    name: custom_name

On your next deploy, a Memcached service will be created.

Configuring Memcached

All environment configuration is handled in the Boxfile. The Memcached Settings in the Boxfile doc walks through all of the configurable Memcached options.

Connecting to Memcached

Because applications vary widely in how they connect to Memcached, it's hard to give you a generic code example of how to connect to your Memcached service. What is uniform is the need for a Host and Port to connect to. You can include these in your codebase by either hard-coding them, or by including the auto-generated environment variables.

Hard Coding the Connection Credentials

After the service has been created, you can find the proper connection credentials for your Memcached service in your App Dashboard . Click on your service to expand the service options. Underneath the scaling controls, click on the Credentials tab.

Once these credentials are in the correct location in your source code, you should be good to go.

Using Environment Variables

Whenever a Memcached service is created on Pagoda Box, we automatically generate environment variables for each of the necessary connection credentials. This allows you to include the proper connection credentials in your codebase before the service is even created. It also allows you to obscure your connection credentials by never actually having to store them in your repo.


Be Sure to Enable the Necessary Extension

When using PHP, you must include add the proper extension in your Boxfile in order to connect to your memcached service. Depending on which memcached adapter your app is coded to use, you can add either the "memcache" extension or the "memcached" extension to your web/worker service(s).

Enabling Extensions in Your Boxfile YAML

      - memcache
     ## OR ##
      - memcached
    type: memcached

Managing Your Memcached Service

Your Memcached service can be managed remotely through the use of the Pagoda Tunnel or by SSH'ing into a web service and interacting with memcached from there. The SSH Access doc walks through how.

Below is an example of opening a tunnel using the Pagoda CLI, then using telnet to connect to Memcached using the connection credentials provided in the dashboard.

Tunnel & Telnet Into Your Memcached Service Terminal

  # Open a tunnel using the pagoda cli
  $ pagoda tunnel cache1

  Tunnel established, use the following credentials to connect:

  Host      :
  Port      : 11211
  Username  :
  Password  :
  Database  : gopagoda

  (note : ctrl-c To close this tunnel)

  # In another shell session with the tunnel still open,
  # telnet into memcached through the tunnel

  $ telnet 11211

Once telnet has connected, you can run commands like:

Memcached Telnet Commands Terminal

  $ flush_all
  $ stats
  $ stats slabs

If you have any questions, suggestions, or corrections, let us know.