memcache: A memcached client library.

[ bsd3, database, library ] [ Propose Tags ] [ Report a vulnerability ]

A client library for a Memcached cluster. Memcached is an in-memory key-value store typically used as a distributed and shared cache. Clients connect to a group of Memcached servers and perform out-of-band caching for things like SQL results, rendered pages, or third-party APIs.

It uses the Memcached Meta Text protocol and requires memcached 1.6.10 or newer: each new connection checks the server's version, and refuses an older server. Until the check passes, the only requests sent are the authentication exchange, when credentials are set, and version. Username/password authentication is supported through memcached's -Y authfile mode; the binary protocol and SASL authentication are no longer supported. It supports connecting to a single, or a cluster of Memcached servers. When connecting to a cluster, keys are routed by ketama consistent hashing, compatible with libmemcached's weighted ketama distribution. Timeouts, retrying failed operations, and failover to a different server are all supported, as is Amazon ElastiCache auto discovery.

Multi-get is supported through the pipelined getMany. Keys containing whitespace or control bytes are sent using the protocol's base64 binary-key mode.

Basic usage is:

{-# LANGUAGE OverloadedStrings #-}

import qualified Database.Memcache.Client as M

main :: IO ()
main = do
    mc <- M.newClient [M.ServerSpec "localhost" "11211" M.NoAuth] M.def
    _ <- M.set mc "key" "value" 0 0
    v <- M.get mc "key"
    print v

You should only need to import Database.Memcache.Client, but other modules are exposed for lower-level use. Version 0.5 is a breaking change from 0.4. Keys are now routed by ketama, so with n servers, upgrading moves all but about one key in n to a different server, once. The optsServerRetries option now counts retries, not attempts. Version 0.5, like 0.4.2.1, needs memcached 1.6.10 or later. See Upgrading from 0.4 in the README, and the changelog, for details.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.0.0, 0.0.1, 0.1.0.0, 0.1.0.1, 0.2.0.0, 0.2.0.1, 0.3.0.0, 0.3.0.1, 0.3.0.2, 0.4.0.0, 0.4.2.0, 0.4.2.1, 0.5.0.0
Change log CHANGELOG.md
Dependencies base (>=4.16 && <5), base64-bytestring (>=1.2.1.0), bytestring (>=0.11.4.0), cryptohash-md5 (>=0.11.101.0), data-default (>=0.7.1.1), hashable (>=1.4.2.0), network (>=3.1.4.0), network-uri (>=2.6.4.2), resource-pool (>=0.2.3.2), text (>=1.2.5.0), time (>=1.11.1.1), unliftio (>=0.2.25.0), vector (>=0.12.3.1) [details]
Tested with ghc >=9.2 && <9.3 || >=9.4 && <9.5 || >=9.6 && <9.7 || >=9.8 && <9.9 || >=9.10 && <9.11 || >=9.12 && <9.13 || >=9.14 && <9.15
License BSD-3-Clause
Copyright 2012-2026 David Terei.
Author David Terei <code@davidterei.com>
Maintainer David Terei <code@davidterei.com>
Uploaded by DavidTerei at 2026-11-19T01:45:33Z
Category Database
Home page https://github.com/dterei/memcache-hs#readme
Bug tracker https://github.com/dterei/memcache-hs/issues
Source repo head: git clone https://github.com/dterei/memcache-hs
Distributions LTSHaskell:0.3.0.2, Stackage:0.5.0.0
Reverse Dependencies 6 direct, 2 indirect [details]
Downloads 5711 total (52 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2026-11-19 [all 1 reports]

Readme for memcache-0.5.0.0

[back to package description]

memcache: Haskell Memcached Client

Hackage BSD3 License CI

A client library for a memcached cluster.

It supports the Meta Text memcached protocol and username/password authentication. Keys containing whitespace or control bytes are sent using its base64 binary-key mode. The encoded key must still fit within 250 bytes. It supports connecting to a single, or a cluster of memcached servers. When connecting to a cluster, keys are routed by ketama consistent hashing, compatible with libmemcached's weighted ketama distribution, so a key goes to the same server as from libmemcached-based clients given the same server list. Version 0.5 changed the routing, so upgrading moves keys to different servers, once; see Upgrading from 0.4.

This library requires memcached 1.6.10 or newer. Older servers reject the meta set command this library stores values with, without reading the value that follows it, and then run the value's bytes as commands. So each new connection asks the server for its version before it is used: until that check passes, the only requests sent are the authentication exchange, when credentials are set, and version. Unless the server reports 1.6.10 or later, the connection is closed and the operation fails with ProtocolError (UnknownOp message), where the message quotes the server's reply, or, if the server answered with an error such as CLIENT_ERROR unauthenticated, with the error that reply gives any request. A refused version isn't retried, and doesn't mark the server as failed. The check sees only the server the client connects to: through a proxy, such as memcached's own -o proxy_config mode, it sees the proxy's version, so every memcached behind a proxy must be 1.6.10 or newer too.

Authentication uses a memcached auth file with -Y authfile, an experimental ASCII-protocol auth mode added in memcached 1.5.15; the old binary protocol -S SASL mode is not supported. Enabling -Y also disables binary and UDP protocols on the server. getMany uses quiet misses, so a server connection failure can be indistinguishable from a cache miss.

The client operations, including getMany, use direct Meta Text encoders and the Response type; the former request and response wrapper types are no longer provided.

Usage

Add memcache to your package's build-depends. Everything most programs need is exported from Database.Memcache.Client:

{-# LANGUAGE OverloadedStrings #-}

module Main (main) where

import qualified Database.Memcache.Client as M

main :: IO ()
main = do
  -- Connect to memcached on 127.0.0.1:11211 with the default options.
  mc <- M.newClient [M.def] M.def

  -- Store a value with flags 0 that never expires, then read it back along
  -- with its flags and CAS version.
  _ <- M.set mc "greeting" "hello" 0 0
  hit <- M.get mc "greeting"
  case hit of
    Nothing -> putStrLn "miss"
    Just (value, _flags, version) -> do
      print value
      -- Only overwrite the value if it hasn't changed since we read it.
      updated <- M.cas mc "greeting" "hello again" 0 0 version
      putStrLn (maybe "changed by someone else" (const "updated") updated)

  -- Create the counter as 1 if it is missing, otherwise add 1 to it.
  visits <- M.increment mc "visits" 1 1 0 0
  print (fst <$> visits)

  M.quit mc

Keys and values are strict ByteStrings. Misses are returned as Nothing, while unexpected failures are thrown as a MemcacheError or a network IOException. Operations that take a CAS Version skip the check when it is 0. increment and decrement create a missing key with the given initial value, unless the expiration is maxBound. The Database.Memcache.Client documentation covers every operation, along with the timeouts, retries and failover configured through Options.

Create one client when your program starts and share it: it is safe to use from many threads, and it keeps its connections to each server open between requests. A client created for each request opens a new connection to every server it uses (and authenticates, if credentials are set) every time. M.withClient closes a client's connections when an action ends, so use it around your whole program, a worker or a test, not around single requests. Each server's pool holds one connection by default (with resource-pool 0.3, one for each capability), so concurrent requests to the same server wait for each other; see Architecture Notes to allow more. The wait counts towards each attempt's optsServerTimeout. An attempt that runs out of time while still waiting is retried like any failed attempt, but if it was the last attempt, the operation fails with Timeout and the server isn't marked dead. An attempt that runs out of time afterwards, while opening, authenticating or using its connection, counts as a server failure, however long it waited first.

A failed operation is retried, except that a request that mustn't be sent twice (increment, decrement, append, prepend, add, delete, and cas or replace with a version) isn't sent again once it may have reached the server: the failure is thrown, and the server is marked dead. Other operations are retried after any failure, so the server may carry out their request twice. Set optsServerRetries to 0 for no retries.

A SERVER_ERROR reply is a failure too, as a timeout is, unless its text names a status, such as running out of memory. One that names a status, and the other error replies, such as CLIENT_ERROR, are thrown at once and don't count against the server. memcached's proxy sends a SERVER_ERROR when a backend fails, so behind it, a request for a key on a failed backend marks the whole proxy dead: at once if the request mustn't be sent twice, and otherwise once its retries get the same reply.

Servers and authentication

newClient takes one ServerSpec per server, and routes each key to one of them. Credentials are set per server:

  mc <- M.newClient
    [ M.ServerSpec "cache1.internal" "11211" (M.Auth "user" "secret")
    , M.ServerSpec "cache2.internal" "11211" (M.Auth "user" "secret")
    ]
    M.def

parseServerSpec, from Database.Memcache.Types, reads a server from a memcached://[user:password@]host[:port] URI instead. The host defaults to 127.0.0.1 and the port to 11211:

import Database.Memcache.Types (parseServerSpec)

  spec <- either fail pure (parseServerSpec "memcached://user:secret@cache1.internal:11211")
  mc <- M.newClient [spec] M.def

The server must be started with -Y <authfile>, where the auth file holds one username:password line per user. This library connects without TLS, so credentials and all data are sent unencrypted; only rely on them within a trusted network.

Unix sockets

A host that begins with / is the path of a Unix socket instead, for a memcached on the same machine. Start memcached with -s <path> to listen on the socket, which stops it listening on the network, and with -a <mode> to set the socket's permissions: the default, 0700, lets only memcached's own user connect.

  mc <- M.newClient [M.ServerSpec "/run/memcached/memcached.sock" "11211" M.NoAuth] M.def

As a URI, the path follows an empty host, and there is no port: memcached:///run/memcached/memcached.sock, or memcached://user:secret@/run/memcached/memcached.sock with credentials. An @ in the path is written %40; a raw one is an error, so that a URI with one slash too many, such as memcached:///user:secret@cache.example, is never taken for a socket path holding the password. The error says that credentials go right after memcached://: such a URI needs a slash fewer, not its @ written %40, which would make it that socket path after all.

The client doesn't use a socket's port to connect, but the port still names the server, along with the path, when keys are routed, so changing it moves keys to other servers. "11211", which a URI gives, names the socket by its path alone, as libmemcached's memcached_server_add does, and "0" names it path:0, as libmemcached's memcached_server_add_unix_socket and pylibmc do.

The operating system limits the path's length: 108 bytes on Linux and 104 on macOS, including the terminating NUL.

Amazon ElastiCache

Database.Memcache.ElastiCacheClient creates a client from an ElastiCache configuration endpoint (the address containing .cfg). It discovers the cluster's nodes, then refreshes the node list in a background thread on the given interval, in microseconds as for threadDelay:

import qualified Database.Memcache.ElastiCacheClient as EC

  endpoint <- either fail pure $
    EC.parseConfigurationEndpoint "memcached://mycluster.abc123.cfg.use1.cache.amazonaws.com:11211"
  mc <- EC.newClient M.def (60 * 1000000) endpoint

Discovery connects to the configuration endpoint like any other server, so it fails for a cluster running a memcached older than 1.6.10.

Upgrading from 0.4

Version 0.5 requires memcached 1.6.10 or newer and refuses an older server, so upgrade any older memcached first, including any behind a proxy.

Version 0.5 routes keys with ketama consistent hashing, where 0.4 sent keys to no more than two servers at a time. With n servers, upgrading moves all but about one key in n to a different server, once: about half the keys with 2 servers, 70% with 3 and 88% with 8. Expect a burst of cache misses.

While old and new versions run side by side, as in a rolling deploy, they read and write a moved key on different servers. One can then read a stale copy of a key that the other has changed or deleted, until the copy expires. To avoid that, either switch every instance at once, at a quiet time, optionally flushing the cache afterwards, or switch in stages, deploying each step to every instance before starting the next:

  1. Upgrade with optsGetServerForKey = legacyServerForKey, 0.4's router, now deprecated, from Database.Memcache.Cluster. Keys stay where they are, as long as the build uses the same hashable version and platform as before. With -Werror, also pass -Wno-deprecations.
  2. Add a second client for the same servers that uses ketamaServerForKey. Whenever a key is changed or deleted, also delete it through that client, unless both clients send it to the same server.
  3. If a server was marked failed less than your longest expiry time ago, flush the cache first. Then swap the two clients' routers.
  4. Once your longest expiry time has passed since step 3 was on every instance, remove the second client. If some keys never expire, flush the cache instead of waiting, and then remove the second client.

The Database.Memcache.Cluster documentation has the details.

optsServerRetries changed too. It now counts the retries after an operation's first attempt, where 0.4 counted the attempts, so a value of 1 or more that you set yourself makes one more attempt than in 0.4. Set it one lower to keep the old number of attempts. The default went from 2 to 1, which still means two attempts.

When a server's host name resolves to several addresses, the client now tries each in turn, where 0.4 tried only the first. If the addresses are separate memcached instances, give each its own ServerSpec: while the first refuses connections, new connections go to the next one that accepts, and so to another cache.

Licensing

This library is BSD-licensed.

Tools

This library also includes a few tools for manipulating and experimenting with memcached servers.

  • OpGen -- A load generator for memcached. Doesn't collect timing statistics, other tools like mutilate already do that very well. This tool is useful in conjunction with mutilate.
  • Loader -- A tool to load random data of a certain size into a memcached server. Useful for priming a server for testing.

Architecture Notes

We're relying on Data.Pool for thread safety right now. Each server has its own pool, and grabbing a connection from it (Server.withSocket) blocks other requests using that connection until the operation completes. getMany, setMany and deleteMany are the exception: they pipeline Meta Text requests to each server in batches, each batch over one pooled connection.

By default each server's pool holds a single connection (soNumResources = 1; with resource-pool 0.3, one for each capability), so concurrent operations against the same server wait for each other. Raising soNumResources in the ServerOptions set through optsServerOptions allows concurrent operations without requiring a separate pool implementation.

Either way, a pool is fine for now.

Other clients

Get involved!

We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.

Please report bugs via the github issue tracker, and security issues as described in the security policy.

Master git repository:

  • git clone https://github.com/dterei/memcache-hs.git

Development

The package builds with Stack or cabal, on GHC 9.2 or newer:

stack build
stack test

cabal build
cabal test all

stack.yaml uses Stackage LTS 22.14 (GHC 9.6). The oldest and newest snapshots CI tests against have their own files, for example stack --stack-yaml stack-lts-20.26.yaml test for GHC 9.2.

There are two test suites:

  • spec holds the unit and property tests, which run against an in-process mock server and need nothing installed.
  • integration starts its own memcached servers on free local ports and tests against them, so it needs memcached 1.6.13 or newer on your PATH. Without it, the suite reports a single pending test instead of failing. With 1.6.10 to 1.6.12, which the library accepts, two of its tests fail, as those servers answer an append or prepend with the version the request carried, or 0, rather than the new one. memcached refuses to run as root without -u, so run the suite as an ordinary user.

CI lints with HLint 3.10, so please check that hlint . prints No hints before opening a pull request. For any user-visible change, propose a line for CHANGELOG.md in the pull request's description; don't edit the file, as the next release's pull request adds the lines.

CI runs both build tools on every pull request. The CI workflow builds and tests with Stack against each stack*.yaml snapshot, and runs HLint and weeder. The Cabal workflow builds and tests with cabal on GHC 9.2 to 9.14, builds the library against the oldest dependency versions its bounds allow, and builds and tests the source distribution; it also runs every Monday, so a new dependency release that breaks the build shows up without a push. Both install memcached, so the integration suite runs in full.

Authors

This library is written and maintained by David Terei (code@davidterei.com).

Contributions have been made by the following great people: