{
  "schema_version": 2,
  "id": "integrate/openresty",
  "title": "Redis with OpenResty",
  "url": "https://redis.io/docs/latest/integrate/openresty/",
  "summary": "Use Redis from NGINX through OpenResty for rate limiting and caching.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:52:03Z",
  "children": [],
  "page_type": "content",
  "content_hash": "076c08d8fc82416fb4be242516ec2da47cc240d89e4d2eeda4a17a1bfe27617d",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Open source [NGINX](https://nginx.org/) has no built-in Redis module. The modules index lists none. You can use\nRedis from NGINX with [OpenResty](https://openresty.org/), a web platform that bundles NGINX,\nLuaJIT, and the [lua-resty-redis](https://github.com/openresty/lua-resty-redis) client, which\ntalks to Redis without blocking NGINX's event loop. See the\n[rate limiter](https://redis.io/docs/latest/develop/use-cases/rate-limiter) and\n[cache-aside](https://redis.io/docs/latest/develop/use-cases/cache-aside) use cases for when to choose\nthese patterns."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "The examples on this page were run with OpenResty 1.31 (the `openresty/openresty:alpine` image),\nwhich includes lua-resty-redis 0.34, against Redis 8.0.\n\nYou also need a running Redis server. You can run one locally with\n[Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),\nuse [Docker](https://hub.docker.com/_/redis), or connect to\n[Redis Cloud](https://redis.io/cloud/)."
    },
    {
      "id": "limit-requests-with-redis",
      "title": "Limit requests with Redis",
      "role": "limits",
      "text": "Use `access_by_lua_block` to count requests in Redis before NGINX proxies them. This example\nallows 3 requests a minute for each client address. A Lua script runs `INCR` and `EXPIRE` in one\natomic step, so a crash between the two commands can't leave a counter without an expiry:\n\n[code example]\n\nIn a test, five requests returned `200`, `200`, `200`, `429`, and `429`. The counter was a string,\n`ratelimit:<client-ip>`, with a TTL of 60 seconds, and it held `5` because the script also counts\nrejected requests."
    },
    {
      "id": "cache-responses-with-redis",
      "title": "Cache responses with Redis",
      "role": "content",
      "text": "This route implements [cache-aside](https://redis.io/docs/latest/develop/use-cases/cache-aside) in NGINX. It\nreads the response from Redis if it's there, and otherwise fetches it from an upstream, stores it with\na 30-second expiry, and returns it:\n\n[code example]\n\nIn a test, the first request returned `X-Cache: MISS` and the next two returned `X-Cache: HIT`, and\nthe key `cache:/cached` had a TTL of 30 seconds."
    },
    {
      "id": "when-redis-is-unavailable",
      "title": "When Redis is unavailable",
      "role": "content",
      "text": "The rate limiter above fails open: with the Redis server stopped, a request returned `200`\nafter about 1 second, which is the connect timeout. The cache route uses `assert`, so it fails the\nrequest if Redis is down. Handle the error in your own code if you want a different behavior."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [lua-resty-redis](https://github.com/openresty/lua-resty-redis)\n- [OpenResty](https://openresty.org/)"
    }
  ],
  "examples": [
    {
      "id": "limit-requests-with-redis-ex0",
      "language": "nginx",
      "code": "location /api {\n  access_by_lua_block {\n    local redis = require \"resty.redis\"\n    local red = redis:new()\n    red:set_timeouts(1000, 1000, 1000)  -- connect, send, read (ms)\n\n    local ok, err = red:connect(\"<your-redis-host>\", 6379)\n    if not ok then\n      ngx.log(ngx.ERR, \"redis unavailable: \", err)\n      return  -- fail open: let the request through\n    end\n\n    local script = [[\n      local n = redis.call('INCR', KEYS[1])\n      if n == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end\n      return n\n    ]]\n    local n = red:eval(script, 1, \"ratelimit:\" .. ngx.var.remote_addr, 60)\n    red:set_keepalive(10000, 100)\n\n    if n and n > 3 then\n      return ngx.exit(429)\n    end\n  }\n  proxy_pass http://<your-upstream>;\n}",
      "section_id": "limit-requests-with-redis"
    },
    {
      "id": "cache-responses-with-redis-ex0",
      "language": "nginx",
      "code": "location = /upstream { internal; proxy_pass http://<your-upstream>/; }\n\nlocation = /cached {\n  content_by_lua_block {\n    local redis = require \"resty.redis\"\n    local red = redis:new()\n    red:set_timeouts(1000, 1000, 1000)\n    assert(red:connect(\"<your-redis-host>\", 6379))\n\n    local key = \"cache:\" .. ngx.var.uri\n    local body = red:get(key)\n    if body and body ~= ngx.null then\n      ngx.header[\"X-Cache\"] = \"HIT\"\n      ngx.say(body)\n    else\n      local res = ngx.location.capture(\"/upstream\")\n      red:set(key, res.body, \"EX\", 30)\n      ngx.header[\"X-Cache\"] = \"MISS\"\n      ngx.say(res.body)\n    end\n    red:set_keepalive(10000, 100)\n  }\n}",
      "section_id": "cache-responses-with-redis"
    }
  ]
}
