{
  "schema_version": 2,
  "id": "develop/clients/ruby/connect",
  "title": "Connect to the server",
  "url": "https://redis.io/docs/latest/develop/clients/ruby/connect/",
  "summary": "Connect your Ruby application to a Redis database",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-10-12T12:46:23+01:00",
  "page_type": "content",
  "content_hash": "0d6a227b3146fe4e667c4914cff9b0af7ca849f1ec916becc3529fa50dabda70",
  "sections": [
    {
      "id": "basic-connection",
      "title": "Basic connection",
      "role": "overview",
      "text": "Create a `Redis` object with the host, port, and database number of your server. The\ndefaults are `localhost`, port 6379, and database 0. If you don't pass a host, port, socket\npath, or URL, the client uses the URL in the `REDIS_URL` environment variable, if it's set.\n\n[code example]\n\nStore and retrieve a string to test the connection.\n\n[code example]\n\nTo connect as an [access control list (ACL)](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl)\nuser, pass `username` and `password`:\n\n[code example]\n\nYou can also pass the connection details as a `redis://` URL. If you pass other options\nwith `url`, such as `password`, those options override the values in the URL.\n\n[code example]\n\nThe client URL-decodes the username and password, so you must URL-encode any special\ncharacters in them, such as `@`, `:`, `/`, or `+`:\n\n[code example]\n\nTo connect through a Unix socket, pass the socket path in `path`, or use a `unix://` URL:\n\n[code example]"
    },
    {
      "id": "connect-to-a-redis-cluster",
      "title": "Connect to a Redis cluster",
      "role": "content",
      "text": "Cluster support is in the separate `redis-clustering` gem:\n\n[code example]\n\nCreate a `Redis::Cluster` object with a list of cluster nodes. The list doesn't need to\ninclude every node, because the client discovers the rest of the cluster from the nodes\nyou list.\n\n[code example]\n\nTo send read-only commands to replicas, set `replica: true`. Use `replica_affinity` to\nchoose a replica: `:random` (the default) picks a random replica, `:random_with_primary`\npicks from the replicas and the primary, and `:latency` picks the replica with the lowest\nlatency. Replication is asynchronous, so a replica can return stale data.\n\n[code example]"
    },
    {
      "id": "connect-to-redis-sentinel",
      "title": "Connect to Redis Sentinel",
      "role": "content",
      "text": "To connect through [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel),\npass `sentinels` and `name` to `Redis.new`. Set `name` to the name of the primary that the\nSentinels monitor. The client asks the Sentinels for the current address of the primary.\n\n[code example]\n\nThe Sentinels and the data nodes have separate credentials, and neither inherits the\nother's. Set `sentinel_password` (and `sentinel_username`, if your Sentinels use ACL users)\nfor the Sentinels, and `username` and `password` for the primary and replicas:\n\n[code example]\n\nThe Sentinel connections use your other options, such as the timeouts and `ssl`.\n\nTo connect to a replica, set `role: :replica`. The client connects to a random replica.\nReplication is asynchronous, so a replica can return stale data, and writes fail with\n`Redis::ReadOnlyError`.\n\n[code example]\n\nredis-rb doesn't listen for failover announcements from the Sentinels. After a failover,\nthe client keeps using the old primary until Sentinel reconfigures it as a replica and it\nstarts rejecting writes. The client then reconnects to the new primary. Any writes that the\nold primary accepts during that time are lost."
    },
    {
      "id": "connect-to-your-production-redis-with-tls",
      "title": "Connect to your production Redis with TLS",
      "role": "content",
      "text": "When you deploy your application, use Transport Layer Security (TLS) and follow the\n[Redis security](https://redis.io/docs/latest/operate/oss_and_stack/management/security) guidelines.\n\nSet `ssl: true`, or use a `rediss://` URL, and pass the TLS settings in `ssl_params`. Set\n`ca_file` to the certificate authority (CA) certificate that signed the server's\ncertificate:\n\n[code example]\n\nIf the server requires clients to authenticate with a certificate, also pass the client\ncertificate and private key in `cert` and `key`:\n\n[code example]\n\n`cert` and `key` also accept file paths, such as `cert: \"./redis_user.crt\"`. If you use the\n`hiredis` driver, `cert` and `key` must be file paths."
    },
    {
      "id": "connect-with-a-connection-pool",
      "title": "Connect with a connection pool",
      "role": "content",
      "text": "A `Redis` object holds a single connection, and a lock serializes access to it. You can\nshare one object between threads safely, but each thread waits for the others to finish\ntheir commands. To run commands from several threads in parallel, use a pool of `Redis`\nobjects from the `connection_pool` gem:\n\n[code example]\n\nCreate a `ConnectionPool` and call `with` to check out a connection for a block of\ncommands:\n\n[code example]\n\n`ConnectionPool::Wrapper` wraps a pool in an object that you call like a `Redis` object.\nEach method call checks out a connection for that call only, so consecutive calls can run on\ndifferent connections. Use `with` when several commands must run on the same connection.\n\n[code example]\n\nSee [Connection pools and multiplexing](https://redis.io/docs/latest/develop/clients/pools-and-muxing) for\nmore information."
    },
    {
      "id": "timeouts-and-reconnection",
      "title": "Timeouts and reconnection",
      "role": "content",
      "text": "The connect, read, and write timeouts default to 1 second. Set `timeout` to change all\nthree, or set `connect_timeout`, `read_timeout`, and `write_timeout` individually. All\nvalues are in seconds.\n\n[code example]\n\nAfter a connection error, the client reconnects and retries the command once by default.\nSet `reconnect_attempts` to an `Integer` to change the number of retries, or to an `Array`\nof delays in seconds to wait before each retry:\n\n[code example]\n\nA retry can run a command twice: if the connection fails after the server runs a command\nbut before the client reads the reply, the client sends the command again. For commands\nthat aren't idempotent, such as `INCR` or `LPUSH`, set `reconnect_attempts: 0`, or run them\ninside `without_reconnect`:\n\n[code example]"
    },
    {
      "id": "protocol",
      "title": "Protocol",
      "role": "content",
      "text": "Starting with redis-rb 6.0, the client uses\n[RESP3](https://redis.io/docs/latest/develop/reference/protocol-spec#resp-versions) (Redis serialization\nprotocol version 3) by default. If the server doesn't support RESP3, the client falls\nback to RESP2 and prints a warning. To use RESP2, set `protocol: 2`:\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "basic-connection-ex0",
      "language": "ruby",
      "code": "require \"redis\"\n\nr = Redis.new(host: \"localhost\", port: 6379, db: 0)",
      "section_id": "basic-connection"
    },
    {
      "id": "basic-connection-ex1",
      "language": "ruby",
      "code": "r.set(\"foo\", \"bar\")\n# => \"OK\"\n\nr.get(\"foo\")\n# => \"bar\"",
      "section_id": "basic-connection"
    },
    {
      "id": "basic-connection-ex2",
      "language": "ruby",
      "code": "r = Redis.new(\n  host: \"localhost\",\n  port: 6379,\n  username: \"default\", # use your Redis user\n  password: \"secret\",  # use your Redis password\n)",
      "section_id": "basic-connection"
    },
    {
      "id": "basic-connection-ex3",
      "language": "ruby",
      "code": "r = Redis.new(url: \"redis://default:secret@localhost:6379/0\")",
      "section_id": "basic-connection"
    },
    {
      "id": "basic-connection-ex4",
      "language": "ruby",
      "code": "require \"uri\"\n\npassword = URI.encode_www_form_component(\"p@ss/word+1\")\nr = Redis.new(url: \"redis://default:#{password}@localhost:6379\")",
      "section_id": "basic-connection"
    },
    {
      "id": "basic-connection-ex5",
      "language": "ruby",
      "code": "r = Redis.new(path: \"/var/run/redis/redis.sock\")\n\nr = Redis.new(url: \"unix:///var/run/redis/redis.sock\")",
      "section_id": "basic-connection"
    },
    {
      "id": "connect-to-a-redis-cluster-ex0",
      "language": "bash",
      "code": "gem install redis-clustering",
      "section_id": "connect-to-a-redis-cluster"
    },
    {
      "id": "connect-to-a-redis-cluster-ex1",
      "language": "ruby",
      "code": "require \"redis-clustering\"\n\nrc = Redis::Cluster.new(nodes: [\n  \"redis://localhost:16379\",\n  \"redis://localhost:16380\",\n  \"redis://localhost:16381\",\n])\n\nrc.set(\"foo\", \"bar\")\n# => \"OK\"\n\nrc.get(\"foo\")\n# => \"bar\"",
      "section_id": "connect-to-a-redis-cluster"
    },
    {
      "id": "connect-to-a-redis-cluster-ex2",
      "language": "ruby",
      "code": "rc = Redis::Cluster.new(\n  nodes: [\"redis://localhost:16379\"],\n  replica: true,\n  replica_affinity: :latency,\n)",
      "section_id": "connect-to-a-redis-cluster"
    },
    {
      "id": "connect-to-redis-sentinel-ex0",
      "language": "ruby",
      "code": "require \"redis\"\n\nSENTINELS = [\n  { host: \"localhost\", port: 26379 },\n  { host: \"localhost\", port: 26380 },\n  { host: \"localhost\", port: 26381 },\n]\n\nr = Redis.new(name: \"mymaster\", sentinels: SENTINELS)\n\nr.set(\"foo\", \"bar\")\n# => \"OK\"\n\nr.get(\"foo\")\n# => \"bar\"",
      "section_id": "connect-to-redis-sentinel"
    },
    {
      "id": "connect-to-redis-sentinel-ex1",
      "language": "ruby",
      "code": "r = Redis.new(\n  name: \"mymaster\",\n  sentinels: SENTINELS,\n  sentinel_password: \"sentinel-secret\", # use your Sentinel password\n  username: \"default\",                  # use your Redis user\n  password: \"secret\",                   # use your Redis password\n)",
      "section_id": "connect-to-redis-sentinel"
    },
    {
      "id": "connect-to-redis-sentinel-ex2",
      "language": "ruby",
      "code": "replica = Redis.new(name: \"mymaster\", sentinels: SENTINELS, role: :replica)\n\nreplica.get(\"foo\")\n# => \"bar\"",
      "section_id": "connect-to-redis-sentinel"
    },
    {
      "id": "connect-to-your-production-redis-with-tls-ex0",
      "language": "ruby",
      "code": "r = Redis.new(\n  url: \"rediss://default:secret@my-redis.example.com:6379\",\n  ssl_params: { ca_file: \"./redis_ca.pem\" },\n)",
      "section_id": "connect-to-your-production-redis-with-tls"
    },
    {
      "id": "connect-to-your-production-redis-with-tls-ex1",
      "language": "ruby",
      "code": "r = Redis.new(\n  host: \"my-redis.example.com\",\n  port: 6379,\n  username: \"default\", # use your Redis user\n  password: \"secret\",  # use your Redis password\n  ssl: true,\n  ssl_params: {\n    ca_file: \"./redis_ca.pem\",\n    cert: OpenSSL::X509::Certificate.new(File.read(\"./redis_user.crt\")),\n    key: OpenSSL::PKey.read(File.read(\"./redis_user_private.key\")),\n  },\n)\n\nr.set(\"foo\", \"bar\")\n# => \"OK\"\n\nr.get(\"foo\")\n# => \"bar\"",
      "section_id": "connect-to-your-production-redis-with-tls"
    },
    {
      "id": "connect-with-a-connection-pool-ex0",
      "language": "bash",
      "code": "gem install connection_pool",
      "section_id": "connect-with-a-connection-pool"
    },
    {
      "id": "connect-with-a-connection-pool-ex1",
      "language": "ruby",
      "code": "require \"connection_pool\"\nrequire \"redis\"\n\npool = ConnectionPool.new(size: 5, timeout: 5) do\n  Redis.new(host: \"localhost\", port: 6379)\nend\n\npool.with do |r|\n  r.set(\"foo\", \"bar\")\n  r.get(\"foo\")\nend\n# => \"bar\"",
      "section_id": "connect-with-a-connection-pool"
    },
    {
      "id": "connect-with-a-connection-pool-ex2",
      "language": "ruby",
      "code": "redis = ConnectionPool::Wrapper.new(size: 5, timeout: 5) do\n  Redis.new(host: \"localhost\", port: 6379)\nend\n\nredis.set(\"foo\", \"bar\")\nredis.get(\"foo\")\n# => \"bar\"",
      "section_id": "connect-with-a-connection-pool"
    },
    {
      "id": "timeouts-and-reconnection-ex0",
      "language": "ruby",
      "code": "r = Redis.new(\n  host: \"localhost\",\n  port: 6379,\n  connect_timeout: 0.5,\n  read_timeout: 2.0,\n  write_timeout: 2.0,\n)",
      "section_id": "timeouts-and-reconnection"
    },
    {
      "id": "timeouts-and-reconnection-ex1",
      "language": "ruby",
      "code": "r = Redis.new(host: \"localhost\", port: 6379, reconnect_attempts: [0.05, 0.25, 1.0])",
      "section_id": "timeouts-and-reconnection"
    },
    {
      "id": "timeouts-and-reconnection-ex2",
      "language": "ruby",
      "code": "r.without_reconnect do\n  r.incr(\"counter\")\nend",
      "section_id": "timeouts-and-reconnection"
    },
    {
      "id": "protocol-ex0",
      "language": "ruby",
      "code": "r = Redis.new(host: \"localhost\", port: 6379, protocol: 2)",
      "section_id": "protocol"
    }
  ]
}