README.txt 6.74 KB
Newer Older
robertDouglass's avatar
robertDouglass committed
1 2
// $Id$

robertDouglass's avatar
robertDouglass committed

5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
These are the broad steps you need to take in order to use this software. Order
is important.

1. Install the memcached binaries on your server.
2. Install the PECL memcache extension for PHP.
3. Put your site into offline mode.
4. Download and install the memcache module.
5. If you have previously been running the memcache module, run update.php.
6. Apply the DRUPAL-5-cache-serialize.patch that comes with the module to your
   Drupal installation.
7. Start at least one instance of memcached on your server.
8. Edit settings.php to configure the servers, clusters and bins that memcache
   is supposed to use.
9. Edit settings.php to include either or
10. Optionally, edit settings.php to include either or
11. Bring your site back online.

For instructions on 1 and 2 above, please see the INSTALLATION.txt file that
comes with the memcache module download.

Either the or the file is intended to be used
instead of, utilizing Drupal's pluggable cache system. The
variant saves all data to the database as well, so the site will still have
the performance benefits of cache even if you take your memcache offline. The
site should not ever break due to memcache not being available... it is only
a question of whether caching is still available or not. The file
doesn't save any data to the database and thus has the biggest potential for
increasing your site's performance. If you use this file it is important to
have enough memory allocated to memcache to store everything (including the page
cache), otherwise the cache misses will negate the benefit of the cache hits.

Update $conf in settings.php to tell Drupal which cache_inc file to use:
38 39

 $conf = array(
robertDouglass's avatar
robertDouglass committed
40 41 42
   // The path to wherever is. The easiest is to simply point it
   // to the copy in your module's directory.
   'cache_inc' => './sites/all/modules/memcache/',
43 44
   // or
   // 'cache_inc' => './sites/all/modules/memcache/',
45 46

robertDouglass's avatar
robertDouglass committed

49 50 51 52 53 54 55
If you want the simple version, you can start one default memcache instance on
your web server like this: memcached -m 24 -p 11211 -d
If that is enough to meet your needs, there is no more configuration needed. If
you want to utilize this module's sophisticated clustering feature and spread
your cache over several machines, or if your cache is found on a machine other
than your web server, read on.

lyricnz's avatar
lyricnz committed
56 57 58 59 60
The available memcached servers are specified in $conf in settings.php. If
you do not specify any servers, assumes that you have a
memcached instance running on localhost:11211. If this is true, and it is
the only memcached instance you wish to use, no further configuration is
robertDouglass's avatar
robertDouglass committed

lyricnz's avatar
lyricnz committed
62 63 64
If you have more than one memcached instance running, you need to add two
arrays to $conf; memcache_servers and memcache_bins. The arrays follow this
robertDouglass's avatar
robertDouglass committed
65 66 67 68 69 70 71 72

'memcache_servers' => array(host1:port => cluster, host2:port => cluster, hostN:port => cluster)

'memcache_bins' => array(bin1 => cluster, bin2 => cluster, binN => cluster)

The bin/cluster/server model can be described as follows:

- Servers are memcached instances identified by host:port.
lyricnz's avatar
lyricnz committed
73 74

- Bins are groups of data that get cached together and map 1:1 to the $table
  param in cache_set(). Examples from Drupal core are cache_filter,
lyricnz's avatar
lyricnz committed
76 77
  cache_menu. The default is 'cache'.

- Clusters are groups of servers that act as a memory pool.
lyricnz's avatar
lyricnz committed

robertDouglass's avatar
robertDouglass committed
- many bins can be assigned to a cluster.
lyricnz's avatar
lyricnz committed

robertDouglass's avatar
robertDouglass committed
82 83
- The default cluster is 'default'.

84 85 86 87 88 89 90 91 92 93 94 95 96
Here is a simple setup that has two memcached instances, both running on
localhost. The 11212 instance belongs to the 'pages' cluster and the table
cache_page is mapped to the 'pages' cluster. Thus everything that gets cached,
with the exception of the page cache (cache_page), will be put into 'default',
or the 11211 instance. The page cache will be in 11212.

$conf = array(
  'memcache_servers' => array('localhost:11211' => 'default',
                              'localhost:11212' => 'pages'),
  'memcache_bins' => array('cache_page' => 'pages'),

lyricnz's avatar
lyricnz committed
97 98 99 100
Here is an example configuration that has two clusters, 'default' and
'cluster2'. Five memcached instances are divided up between the two
clusters. 'cache_filter' and 'cache_menu' bins goe to 'cluster2'. All other
bins go to 'default'.
robertDouglass's avatar
robertDouglass committed
101 102 103

$conf = array(
  'cache_inc' => './includes/',
robertDouglass's avatar
robertDouglass committed
104 105 106 107
  'memcache_servers' => array('localhost:11211' => 'default',
                              'localhost:11212' => 'default',
                              '' => 'default',
                              '' => 'cluster2',
robertDouglass's avatar
robertDouglass committed
108 109
                              '' => 'cluster2'),

robertDouglass's avatar
robertDouglass committed
110 111
  'memcache_bins' => array('cache' => 'default',
                           'cache_filter' => 'cluster2',
lyricnz's avatar
lyricnz committed
                           'cache_menu' => 'cluster2'),
robertDouglass's avatar
robertDouglass committed
114 115 116 117 118 119 120 121 122 123
If you want to have multiple Drupal installations share memcached instances,
you need to include a unique prefix for each Drupal installation in the $conf
array of settings.php:
$conf = array(
  'memcache_key_prefix' => 'something_unique',
robertDouglass's avatar
robertDouglass committed
124 125


127 128 129 130 131 132 133 134 135 136
The DRUPAL-5-cache-serialize.patch must be applied to your Drupal installation
for this software to work. The patch depends on a column that needs to get added
to all of the existing cache tables for your site. This column has been
introduced in the DRUPAL-6 development branch so this patch is future-safe if
you ever upgrade to DRUPAL-6. To actually add the column to your database, you
need to either install the memcache.module, or, if it is already installed and
you are updating to this version, run update.php. Either installing the module
or running update.php will add the needed column, Uninstalling the module will
remove the column.

137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160

Warning: require_once(a) [function.require-once]: failed to open stream:
No such file or directory in /includes/ on line 853

This error occurs after you apply the DRUPAL-5-cache-serialize.patch because
the code in the patch now expects the cached variables to be unserialized
but they are still serialized in the cache. Clear the cache table:

mysql> TRUNCATE cache;
Query OK, 0 rows affected (0.01 sec)

Fatal error: Cannot use string offset as an array in includes/ on line 452

Similar to the error above, this occurs after applying the
DRUPAL-5-cache-serialize.patch due to the conflict between the existing
cached menu and what the patched code is expecting. Clear cache_menu:

mysql> TRUNCATE cache_menu;
Query OK, 0 rows affected (0.33 sec)

robertDouglass's avatar
robertDouglass committed

lyricnz's avatar
lyricnz committed
164 165
A module offering a UI for memcache is on the way. It will provide stats, a
way to clear the cache, and an interface to organize servers/bins/clusters.