From b43287afc9899063b051b2ea1b83b7bd0e060057 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Thu, 8 Oct 2026 14:07:07 +0100 Subject: [PATCH] DOC-7165 Add a connection URLs page covering all client libraries Adds develop/clients/connection-urls.md. It covers the portable core of the redis/rediss URL format, rules for writing URLs that behave the same across clients, a summary table, and one section per client. Each client's connect page (or index, for Ruby and Rust) gets a NOTE callout that links to its section. The old inline format string on the node-redis pages is gone. Every client-specific fact was checked against parser source and tests at these releases: redis-py 8.1.0, node-redis 6.3.0, ioredis 6.0.0, Jedis 8.0.2, Lettuce 7.8.0, go-redis 9.23.0, redis-rs 1.7.1, redis-rb 6.0.0 (whose URL parsing lives in the redis-client gem, pinned to exactly 0.30.1), Predis 3.6.1, hiredis 1.4.1, StackExchange.Redis 3.3.1 and NRedisStack 1.8.0. Where a toolchain was available, parse-only runs backed this up. Nothing connected to a server, so the page describes parse behavior, not handshakes. The client projects' own docs were not reliable sources: - Jedis javadoc shows the port as optional, but isValid() rejects a URI without one. - Lettuce's URI guide uses Builder methods that no longer exist. - The redis-rb docstring says the URL overrides explicit options. In fact the explicit options win. - The node-redis clustering docs show a URL without a scheme, which parseURL rejects. Read the parser source instead. Some findings contradict common assumptions: - redis://@host without a colon is a username in most clients, a password in Lettuce and redis-rb, and an error in Jedis. - go-redis rejects unknown query keys. redis-py, ioredis and Predis pass them through. The others ignore them. - ioredis passes ?protocol=3 through as a string, so the RESP3 check fails and it silently uses RESP2. The page tells readers to set protocol in the options instead of describing the bug. The IANA provisional registration (mirrored in redis/redis-specifications uri/) is the closest thing to a spec. It explicitly says query parameters are implementation-defined and not portable, which is why the page puts the per-client sections after the portable core. Learned: client URL docs (javadoc, READMEs, guides) contradict their own parsers in Jedis, Lettuce, redis-rb, node-redis; verify against parser source Constraint: per-client facts on connection-urls.md are pinned to the releases listed in the body; re-verify a client's section against its parser source when bumping its version Directive: keep query-parameter examples out of the portable-URL guidance; the spec defines no portable query keys Gaps: StackExchange.Redis given a redis:// URL was read from code only (Parse treats it as a literal DnsEndPoint host); not executed Gaps: handshake behavior (AUTH/SELECT/HELLO) after parsing was not exercised for any client Recheck: ioredis protocol-as-string bug, if a fix lands the ioredis section can mention ?protocol= Ticket: DOC-7165 Co-Authored-By: Claude Opus 5.5 --- content/develop/clients/connection-urls.md | 374 ++++++++++++++++++++ content/develop/clients/dotnet/connect.md | 7 + content/develop/clients/go/_index.md | 7 +- content/develop/clients/go/connect.md | 7 +- content/develop/clients/ioredis/connect.md | 5 + content/develop/clients/jedis/connect.md | 5 + content/develop/clients/lettuce/connect.md | 5 + content/develop/clients/nodejs/_index.md | 8 +- content/develop/clients/nodejs/connect.md | 9 +- content/develop/clients/php/connect.md | 5 + content/develop/clients/redis-py/connect.md | 5 + content/develop/clients/ruby/_index.md | 5 + content/develop/clients/rust/_index.md | 5 + 13 files changed, 443 insertions(+), 4 deletions(-) create mode 100644 content/develop/clients/connection-urls.md diff --git a/content/develop/clients/connection-urls.md b/content/develop/clients/connection-urls.md new file mode 100644 index 0000000000..2ad2cf55a7 --- /dev/null +++ b/content/develop/clients/connection-urls.md @@ -0,0 +1,374 @@ +--- +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +description: Learn the Redis connection URL format and how each client library interprets it +linkTitle: Connection URLs +title: Connection URLs +weight: 35 +--- + +Most Redis client libraries can connect using a URL such as +`redis://default:@:6379/0`. Only the basic form of the URL +means the same thing in every client. Everything else, including how you +set timeouts, TLS options, and the RESP protocol version, is specific to +each client library. + +The `redis` and `rediss` URL schemes have a +[provisional IANA registration](https://www.iana.org/assignments/uri-schemes/prov/redis), +but this is not a formal standard. The registration describes the basic form +and says that query parameters are implementation-defined and not portable +between clients. + +## URL format + +The basic form of a Redis URL is: + +``` +redis[s]://[[][:]@][][:][/] +``` + +| Part | Meaning | Default | +| :-- | :-- | :-- | +| `redis` or `rediss` | Use `redis` for a plain TCP connection and `rediss` for a TLS connection. | (required) | +| `` | Username for [ACL authentication](/content/operate/oss_and_stack/management/security/acl.md). | `default` | +| `` | Password for authentication. | No authentication | +| `` | Hostname or IP address of the server. Enclose an IPv6 address in square brackets, for example `[::1]`. | `localhost` | +| `` | Port number of the server. | `6379` | +| `` | Number of the logical database to select. | `0` | + +## Write portable URLs + +Follow these rules to write a URL that works the same way in every client +that accepts URLs: + +- **Use a lowercase scheme.** Lettuce, Predis, and synchronous redis-py + reject `REDIS://`, and ioredis only enables TLS for a lowercase `rediss://`. +- **Always include the port.** Jedis rejects a URL without one. +- **Always include the username with the password.** Write + `redis://default:@:6379` rather than leaving out the username. + The form `redis://:@` also means "password only" in every client. + However, the form `redis://@`, without a colon, is not portable: + + | Client | `` in `redis://@` means | + | :-- | :-- | + | redis-py, node-redis, ioredis, go-redis, redis-rs, Predis | Username, with no password | + | Lettuce, redis-rb | Password | + | Jedis | Error | + +- **Percent-encode special characters in the username and password.** + Encode any character that has a special meaning in URLs, such as `@`, `:`, `/`, + `?`, `#`, `%`, and `+`. For example, the password `p@ss:w+rd` becomes + `p%40ss%3Aw%2Brd`. See [Predis](#predis-php) and [redis-rb](#redis-rb-ruby) + for exceptions. +- **Select the database with the path, not a query parameter.** + `redis://:6379/2` selects database 2 in every client. The `?db=` query + parameter is ignored by some clients and has a different name in others. +- **Don't put query parameters in a URL that more than one client reads.** + Clients recognize different parameter names, and they handle a name they + don't recognize differently: + + | Behavior for an unknown query parameter | Clients | + | :-- | :-- | + | Ignored | node-redis, Jedis, Lettuce, redis-rs, redis-rb | + | Passed to the client as an option | redis-py, ioredis, Predis | + | Error | go-redis | + +- **Don't set the same option in both the URL and the client's options.** + Clients disagree about which one takes precedence. + +A URL often contains a password, so treat it as a secret. For example, keep it +out of logs and error messages. + +## Client support + +The following table summarizes how each client library handles URLs. See the +sections after the table for details. + +| Client | URL entry point | Schemes | Unix socket | Database in query | RESP version in query | +| :-- | :-- | :-- | :-- | :-- | :-- | +| [redis-py](#redis-py-python) | `redis.from_url()` | `redis`, `rediss`, `unix` | `unix:///?db=` | `?db=` | `?protocol=2` or `3` | +| [node-redis](#node-redis-javascript) | `createClient({ url })` | `redis`, `rediss`, `unix` | `unix:///?db=` | Unix socket only | Not supported | +| [ioredis](#ioredis-javascript) | `new Redis(url)` | `redis`, `rediss` | `/?db=` (no scheme) | `?db=` | Not supported | +| [Jedis](#jedis-java) | `RedisClient.create(url)` | `redis`, `rediss` | Not supported | Not supported | `?protocol=2` or `3` | +| [Lettuce](#lettuce-java) | `RedisURI.create(url)` | `redis`, `rediss`, `redis-socket`, `redis-sentinel`, `rediss-sentinel`, and others | `redis-socket:///?database=` | `?database=` or `?db=` | Not supported | +| [go-redis](#go-redis-go) | `redis.ParseURL()` | `redis`, `rediss`, `unix` | `unix:///?db=` | `?db=` | `?protocol=2` or `3` | +| [redis-rs](#redis-rs-rust) | `Client::open(url)` | `redis`, `rediss`, `unix`, `redis+unix` | `unix:///?db=` | Unix socket only | `?protocol=2` or `3` | +| [redis-rb](#redis-rb-ruby) | `Redis.new(url: url)` | `redis`, `rediss`, `unix` | `unix:///?db=` | `?db=` | Not supported | +| [Predis](#predis-php) | `new Predis\Client(url)` | `redis`, `rediss`, `tcp`, `tls`, `unix` | `unix:///?database=` | `?database=` | `?protocol=3` | +| [SE.Redis and NRedisStack](#stackexchangeredis-and-nredisstack-net) | Not supported | | | | | +| [hiredis](#hiredis-c) | Not supported | | | | | + +The `rediss` scheme turns on TLS, but most clients only let you configure +certificates in code. See the TLS section of each client's connection page, +for example +[Connect to your production Redis with TLS](/content/develop/clients/redis-py/connect.md#connect-to-your-production-redis-with-tls) +for redis-py. + +## redis-py (Python) + +Pass the URL to `redis.from_url()`, `Redis.from_url()`, or +`ConnectionPool.from_url()`. The `redis.asyncio` module has the same functions. + +```python +import redis + +r = redis.from_url("rediss://default:@:6379/0?protocol=3") +``` + +- Query parameters become keyword arguments for the connection. redis-py + converts the types of the parameters it recognizes, such as `socket_timeout`, + `socket_connect_timeout`, `health_check_interval`, `protocol`, and + `ssl_check_hostname`. It passes any other parameter as a string, and reports + an error for an unknown name when it creates the first connection. +- Pass Boolean options that redis-py doesn't convert, such as + `decode_responses`, as keyword arguments rather than in the URL. For example, + `?decode_responses=False` passes the string `"False"`, which Python treats as + true. +- A query parameter overrides the keyword argument with the same name. + If you specify both `?db=` and a path, `?db=` wins. +- For TLS connections, you can set `ssl_cert_reqs` (`none`, `optional`, or + `required`) and `ssl_check_hostname` in the query. +- `RedisCluster.from_url()` accepts only database 0 and doesn't support Unix + sockets. There is no URL form for Sentinel. + +See the +[`from_url()` reference](https://redis.readthedocs.io/en/stable/connections.html#redis.Redis.from_url) +for more information. + +## node-redis (JavaScript) + +Pass the URL in the `url` option of `createClient()`: + +```js +import { createClient } from 'redis'; + +const client = createClient({ + url: 'rediss://default:@:6379/0' +}); +``` + +- node-redis ignores all query parameters in `redis://` and `rediss://` URLs. + Set other options, such as `RESP`, in the options object. +- Values in the URL override the `username`, `password`, and `database` + options. +- For a Unix socket, use `unix:///`. You can add the database with + `?db=`. +- For a cluster, set `url` for each of the `rootNodes`. The credentials in + these URLs are only used for the initial connections, so set credentials for + the other nodes in the `defaults` option. There is no URL form for Sentinel. + +## ioredis (JavaScript) + +Pass the URL as an argument to the `Redis` constructor: + +```js +import Redis from 'ioredis'; + +const redis = new Redis('rediss://default:@:6379/0'); +``` + +- ioredis doesn't reject other schemes. It adds `redis://` to the start of + any string that doesn't begin with `redis://` or `rediss://`, so a URL such as + `unix:///tmp/redis.sock` is read as a host named `unix`. +- For a Unix socket, pass the socket path without a scheme, for example + `new Redis('/tmp/redis.sock?db=1')`. +- ioredis passes query parameters to the client as options, with string + values. Set non-string options, such as `protocol`, in the options object + instead. +- If you pass the URL before the options object, values in the URL take + precedence. +- A `rediss://` URL for a cluster startup node doesn't turn on TLS. Set the + `tls` option in `redisOptions` instead. + +## Jedis (Java) + +Pass the URL to `RedisClient.create()`: + +```java +RedisClient jedis = RedisClient.create("rediss://default:@:6379/0"); +``` + +- The URL must include a port. +- For a password with no username, use `redis://:@:`. + A URL such as `redis://@:`, without a colon, is an error. +- The only query parameter is `protocol`, with the value `2` or `3`. + Jedis ignores any other parameter, including `db`. +- Don't add a slash after the database number. Jedis can't parse + `redis://:6379/1/?protocol=3`. +- There is no URL form for a Unix socket, a cluster, or Sentinel. + +## Lettuce (Java) + +Pass the URL to `RedisURI.create()` or `RedisClient.create()`: + +```java +RedisClient client = RedisClient.create("rediss://default:@:6379/0"); +``` + +- Lettuce recognizes these schemes: + - `redis` for TCP. + - `rediss` or `redis+ssl` for TLS, and `redis+tls` for TLS with STARTTLS. + - `redis-socket` or `redis+socket` for a Unix socket. + - `redis-sentinel` or `rediss-sentinel` for Sentinel. +- Lettuce reads `redis://@`, without a colon, as a password. +- Lettuce recognizes these query parameters: + - `timeout`: a number with an optional unit suffix, such as `10s`. With no + suffix, the unit is milliseconds. + - `database` or `db`: the database number. This takes precedence over the + path. + - `clientName`, `libraryName`, and `libraryVersion`. + - `verifyPeer`: `NONE`, `CA`, or `FULL`. + - `sentinelMasterId`: the master name, for Sentinel. +- For Sentinel, list the Sentinel hosts separated by commas and name the + master, for example + `redis-sentinel://@:26379,:26379/0?sentinelMasterId=mymaster`. + The password in the URL is for the data nodes, not the Sentinels. +- For a cluster, pass `RedisClusterClient.create()` a URL with the seed nodes + separated by commas, for example `redis://@:7000,:7001`. + Lettuce doesn't apply `clientName` or the database from this URL to the + cluster nodes. + +See [URI syntax](https://redis.github.io/lettuce/user-guide/connecting-redis/) +in the Lettuce documentation for more information. + +## go-redis (Go) + +Parse the URL with `redis.ParseURL()` and pass the result to +`redis.NewClient()`: + +```go +opt, err := redis.ParseURL("rediss://default:@:6379/0?protocol=3") +if err != nil { + panic(err) +} + +client := redis.NewClient(opt) +``` + +- Query parameters set fields of `redis.Options`, using names in snake case + such as `dial_timeout`, `read_timeout`, `pool_size`, `client_name`, and + `protocol`. `ParseURL()` returns an error for any parameter it doesn't + recognize. +- A duration parameter such as `dial_timeout` takes a number of seconds, such as + `5`, or a Go duration string, such as `500ms`. +- For a `rediss` URL, `skip_verify=true` turns off certificate verification. + `skip_verify` is an error in a `redis` URL. +- For a cluster, use `redis.ParseClusterURL()` and add the other seed nodes with + `addr=:` parameters. This function ignores the path and returns + an error for `db`. +- For Sentinel, use `redis.ParseFailoverURL()`. The credentials in the URL are + for the Sentinels. Set the master name with `master_name=`, the master's + credentials with `username=` and `password=`, and other Sentinels with + `addr=`. + +See the [`ParseURL()` reference](https://pkg.go.dev/github.com/redis/go-redis/v9#ParseURL) +for the full list of parameters. + +## redis-rs (Rust) + +Pass the URL to `Client::open()`: + +```rust +let client = redis::Client::open("rediss://default:@:6379/0?protocol=3")?; +``` + +- The URL must include a host. +- The only query parameter for a TCP connection is `protocol`, with the value + `2`, `3`, `resp2`, or `resp3`. If you don't set it, redis-rs uses RESP2. +- To skip certificate verification for a `rediss` URL, add the fragment + `#insecure` to the end of the URL. With the `tls-rustls` feature, this also + needs the `tls-rustls-insecure` feature. +- For a Unix socket, use `unix:///` or `redis+unix:///`. Pass the + database and credentials as the `db`, `user`, and `pass` query parameters, + not in the address. +- For a cluster, pass a URL for each node to `ClusterClient::new()`. The URLs + must all have the same credentials, protocol, and TLS mode. + +See the [crate documentation](https://docs.rs/redis/latest/redis/) for more +information. + +## redis-rb (Ruby) + +Pass the URL in the `url` option of `Redis.new`: + +```ruby +require 'redis' + +r = Redis.new(url: 'rediss://default:@:6379/0') +``` + +- If you don't pass `url`, `host`, `port`, or `path`, redis-rb reads the URL from + the `REDIS_URL` environment variable. +- Options that you pass to `Redis.new` take precedence over values in the URL. +- The only query parameter is `db`. Set other options, such as `protocol`, in + `Redis.new`. +- redis-rb reads `redis://@`, without a colon, as a password. +- redis-rb decodes percent-encoding in the password, but not in the username. +- For Sentinel, put the master name in place of the host and pass the + Sentinels in the `sentinels` option, for example + `Redis.new(url: 'redis://mymaster', sentinels: [...])`. + +## Predis (PHP) + +Pass the URL to the `Predis\Client` constructor: + +```php +$client = new Predis\Client('rediss://default:@:6379/0'); +``` + +- Predis only reads the credentials and database from the address for the + `redis` and `rediss` schemes. For `tcp`, `tls`, and `unix`, use the + `username`, `password`, and `database` query parameters. +- Predis doesn't decode percent-encoding in the username or password in the + address. If your password contains special characters, pass it as a + percent-encoded `password` query parameter instead. +- The query parameter for the database is `database`, not `db`. +- Predis passes all query parameters to the connection, for example + `timeout`, `read_write_timeout`, `persistent`, and `protocol`. +- You can set TLS options with `ssl` parameters, for example + `?ssl[cafile]=&ssl[verify_peer]=1`. + +## StackExchange.Redis and NRedisStack (.NET) + +StackExchange.Redis doesn't accept URLs. It uses its own configuration string +format, which is a comma-separated list of endpoints and `key=value` options. +NRedisStack connects through StackExchange.Redis and uses the same format. + +```csharp +ConnectionMultiplexer redis = ConnectionMultiplexer.Connect( + ":6379,user=default,password=,ssl=true,defaultDatabase=0" +); +``` + +If you have a URL, convert it to a configuration string: + +| URL part | Configuration string | +| :-- | :-- | +| `rediss` scheme | `ssl=true` | +| `:` | `:` | +| `` | `user=` | +| `` | `password=` | +| `/` | `defaultDatabase=` | +| `?protocol=3` | `protocol=resp3` | + +Always include the port. If you set `ssl=true` and leave out the port, +StackExchange.Redis uses port 6380, not 6379. Don't percent-encode the values. +The configuration string format has no way to escape a comma in a value. + +See [Configuration](https://seredis.dev/Configuration) in the +StackExchange.Redis documentation for the full list of options. + +## hiredis (C) + +hiredis doesn't accept URLs. Pass the host and port to `redisConnect()`, or the +socket path to `redisConnectUnix()`. You can also use `redisConnectWithOptions()` +with a `redisOptions` struct. See [Connect](/content/develop/clients/hiredis/connect.md) +for examples. diff --git a/content/develop/clients/dotnet/connect.md b/content/develop/clients/dotnet/connect.md index 2a2e842cf1..8c8ea59fe9 100644 --- a/content/develop/clients/dotnet/connect.md +++ b/content/develop/clients/dotnet/connect.md @@ -41,6 +41,13 @@ db.StringSet("foo", "bar"); Console.WriteLine(db.StringGet("foo")); // prints bar ``` +> [!NOTE] +> Unlike other clients, StackExchange.Redis doesn't support +> [Connection URLs](/content/develop/clients/connection-urls.md#stackexchangeredis-and-nredisstack-net) +> but it does support its own similar configuration string format. +> See [Connection URLs](/content/develop/clients/connection-urls.md#stackexchangeredis-and-nredisstack-net) +> to learn how to convert a standard URL to a configuration string. + ## Connect to a Redis cluster The basic connection will use the diff --git a/content/develop/clients/go/_index.md b/content/develop/clients/go/_index.md index 3d35ca32bc..fdacb4f46e 100644 --- a/content/develop/clients/go/_index.md +++ b/content/develop/clients/go/_index.md @@ -55,7 +55,7 @@ Then connect to localhost on port 6379 and add a {{< clients-example set="landing" step="connect" lang_filter="Go" description="Foundational: Connect to a Redis server and establish a client connection" difficulty="beginner" >}} {{< /clients-example >}} -You can also connect using a connection string: +You can also connect using a connection URL: ```go opt, err := redis.ParseURL("redis://:@localhost:6379/") @@ -66,6 +66,11 @@ if err != nil { client := redis.NewClient(opt) ``` +> [!NOTE] +> go-redis supports [connection URLs](/content/develop/clients/connection-urls.md#go-redis-go) through `redis.ParseURL()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + After connecting, you can test the connection by storing and retrieving a simple [string](/content/develop/data-types/strings/_index.md): diff --git a/content/develop/clients/go/connect.md b/content/develop/clients/go/connect.md index 49d465cc73..977ead4c9a 100644 --- a/content/develop/clients/go/connect.md +++ b/content/develop/clients/go/connect.md @@ -36,7 +36,7 @@ func main() { } ``` -You can also connect using a connection string: +You can also connect using a connection URL: ```go opt, err := redis.ParseURL("redis://:@localhost:6379/") @@ -47,6 +47,11 @@ if err != nil { client := redis.NewClient(opt) ``` +> [!NOTE] +> go-redis supports [connection URLs](/content/develop/clients/connection-urls.md#go-redis-go) through `redis.ParseURL()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + After connecting, you can test the connection by storing and retrieving a simple [string](/content/develop/data-types/strings/_index.md): diff --git a/content/develop/clients/ioredis/connect.md b/content/develop/clients/ioredis/connect.md index 70935592d8..a5aef1c271 100644 --- a/content/develop/clients/ioredis/connect.md +++ b/content/develop/clients/ioredis/connect.md @@ -35,6 +35,11 @@ const redis = new Redis({ }); ``` +> [!NOTE] +> ioredis supports [connection URLs](/content/develop/clients/connection-urls.md#ioredis-javascript) through the `Redis` constructor. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + Store and retrieve a simple string. ```js diff --git a/content/develop/clients/jedis/connect.md b/content/develop/clients/jedis/connect.md index e5284a0d97..6fbc263197 100644 --- a/content/develop/clients/jedis/connect.md +++ b/content/develop/clients/jedis/connect.md @@ -45,6 +45,11 @@ public class Main { } ``` +> [!NOTE] +> Jedis supports [connection URLs](/content/develop/clients/connection-urls.md#jedis-java) through `RedisClient.create()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + After you have connected, you can check the connection by storing and retrieving a simple string value: diff --git a/content/develop/clients/lettuce/connect.md b/content/develop/clients/lettuce/connect.md index ae8c50f807..63201774fd 100644 --- a/content/develop/clients/lettuce/connect.md +++ b/content/develop/clients/lettuce/connect.md @@ -46,6 +46,11 @@ public class ConnectBasicTest { } ``` +> [!NOTE] +> Lettuce supports [connection URLs](/content/develop/clients/connection-urls.md#lettuce-java) through `RedisClient.create()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + ## Connect to a Redis cluster To connect to a Redis cluster, use `RedisClusterClient`. diff --git a/content/develop/clients/nodejs/_index.md b/content/develop/clients/nodejs/_index.md index 02869a4d03..6dc9e2d773 100644 --- a/content/develop/clients/nodejs/_index.md +++ b/content/develop/clients/nodejs/_index.md @@ -60,13 +60,19 @@ Store and retrieve a map. {{< jupyter-example set="landing" step="set_get_hash" depends="connect" lang_filter="Node.js" description="Foundational: Store and retrieve hash data structures using HSET and HGET commands" difficulty="beginner" />}} -To connect to a different host or port, use a connection string in the format `redis[s]://[[username][:password]@][host][:port][/db-number]`: +To connect to a different host or port, use a connection URL: ```js createClient({ url: 'redis://alice:foobared@awesome.redis.server:6380' }); ``` + +> [!NOTE] +> node-redis supports [connection URLs](/content/develop/clients/connection-urls.md#node-redis-javascript) through the `url` option of `createClient()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + To check if the client is connected and ready to send commands, use `client.isReady`, which returns a Boolean. `client.isOpen` is also available. This returns `true` when the client's underlying socket is open, and `false` when it isn't (for example, when the client is still connecting or reconnecting after a network error). When you have finished using a connection, close it with `client.quit()`. diff --git a/content/develop/clients/nodejs/connect.md b/content/develop/clients/nodejs/connect.md index eef6f44f27..4846d19bf4 100644 --- a/content/develop/clients/nodejs/connect.md +++ b/content/develop/clients/nodejs/connect.md @@ -58,13 +58,20 @@ console.log(JSON.stringify(userSession, null, 2)); */ ``` -To connect to a different host or port, use a connection string in the format `redis[s]://[[username][:password]@][host][:port][/db-number]`: +To connect to a different host or port, use a +[connection URL](/content/develop/clients/connection-urls.md#node-redis-javascript): ```js createClient({ url: 'redis://alice:foobared@awesome.redis.server:6380' }); ``` + +> [!NOTE] +> A [connection URL](/content/develop/clients/connection-urls.md#node-redis-javascript) can +> also set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + To check if the client is connected and ready to send commands, use `client.isReady`, which returns a Boolean. `client.isOpen` is also available. This returns `true` when the client's underlying socket is open, and `false` when it isn't (for example, when the client is still connecting or reconnecting after a network error). ## Connect to a Redis cluster diff --git a/content/develop/clients/php/connect.md b/content/develop/clients/php/connect.md index 9e6d7d3b91..4b1522df83 100644 --- a/content/develop/clients/php/connect.md +++ b/content/develop/clients/php/connect.md @@ -36,6 +36,11 @@ $r = new PredisClient([ ]); ``` +> [!NOTE] +> Predis supports [connection URLs](/content/develop/clients/connection-urls.md#predis-php) through the `PredisClient` constructor. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + Store and retrieve a simple string to test the connection: ```php diff --git a/content/develop/clients/redis-py/connect.md b/content/develop/clients/redis-py/connect.md index 8b2837aeeb..64987512c3 100644 --- a/content/develop/clients/redis-py/connect.md +++ b/content/develop/clients/redis-py/connect.md @@ -23,6 +23,11 @@ Connect to localhost on port 6379, set a value in Redis, and retrieve it. All re r = redis.Redis(host='localhost', port=6379, decode_responses=True) ``` +> [!NOTE] +> redis-py supports [connection URLs](/content/develop/clients/connection-urls.md#redis-py-python) through `redis.from_url()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + Store and retrieve a simple string. ```python diff --git a/content/develop/clients/ruby/_index.md b/content/develop/clients/ruby/_index.md index 8644734476..9360c58c83 100644 --- a/content/develop/clients/ruby/_index.md +++ b/content/develop/clients/ruby/_index.md @@ -39,6 +39,11 @@ Connect to localhost on port 6379: {{< jupyter-example set="landing" step="connect" lang_filter="Ruby" description="Foundational: Connect to a Redis server and establish a client connection" difficulty="beginner" />}} +> [!NOTE] +> redis-rb supports [connection URLs](/content/develop/clients/connection-urls.md#redis-rb-ruby) through the `url` option of `Redis.new`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + Store and retrieve a simple string. {{< jupyter-example set="landing" step="set_get_string" depends="connect" lang_filter="Ruby" description="Foundational: Set and retrieve string values using SET and GET commands" difficulty="beginner" />}} diff --git a/content/develop/clients/rust/_index.md b/content/develop/clients/rust/_index.md index bfa293010e..30bb48e2a6 100644 --- a/content/develop/clients/rust/_index.md +++ b/content/develop/clients/rust/_index.md @@ -65,6 +65,11 @@ The following example shows the simplest way to connect to a Redis server: {{< clients-example set="landing" step="connect" lang_filter="Rust-Sync,Rust-Async" description="Foundational: Connect to a Redis server and establish a client connection" difficulty="beginner" >}} {{< /clients-example >}} +> [!NOTE] +> redis-rs supports [connection URLs](/content/develop/clients/connection-urls.md#redis-rs-rust) through `Client::open()`. +> A URL can set the host, port, credentials, database, and whether to use TLS, +> so you can use one instead of passing those options separately. + After connecting, you can test the connection by storing and retrieving a simple [string](/content/develop/data-types/strings/_index.md):