Skip to content

[Cache] fixes #16310 unclear alternate Redis DSN format #17234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 14, 2022
Merged

[Cache] fixes #16310 unclear alternate Redis DSN format #17234

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 64 additions & 17 deletions components/cache/adapters/redis_adapter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,12 +67,18 @@ replaced by ``rediss`` (the second ``s`` means "secure").

.. note::

A `Data Source Name (DSN)`_ for this adapter must use the following format.
A `Data Source Name (DSN)`_ for this adapter must use either one of the following formats.

.. code-block:: text

redis[s]://[pass@][ip|host|socket[:port]][/db-index]

.. code-block:: text

redis[s]:[[user]:pass@]?[ip|host|socket[:port]][&params]

Values for placeholders ``[user]``, ``[:port]``, ``[/db-index]`` and ``[&params]`` are optional.

Below are common examples of valid DSNs showing a combination of available values::

use Symfony\Component\Cache\Adapter\RedisAdapter;
Expand All @@ -89,20 +95,35 @@ Below are common examples of valid DSNs showing a combination of available value
// socket "/var/run/redis.sock" and auth "bad-pass"
RedisAdapter::createConnection('redis://bad-pass@/var/run/redis.sock');

// a single DSN can define multiple servers using the following syntax:
// host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
// host "redis1" (docker container) with alternate DSN syntax and selecting database index "3"
RedisAdapter::createConnection('redis:?host[redis1:6379]&dbindex=3');

// providing credentials with alternate DSN syntax
RedisAdapter::createConnection('redis:default:verysecurepassword@?host[redis1:6379]&dbindex=3');

// a single DSN can also define multiple servers
RedisAdapter::createConnection(
'redis:?host[localhost]&host[localhost:6379]&host[/var/run/redis.sock:]&auth=my-password&redis_cluster=1'
);

`Redis Sentinel`_, which provides high availability for Redis, is also supported
when using the Predis library. Use the ``redis_sentinel`` parameter to set the
name of your service group::
when using the PHP Redis Extension v5.2+ or the Predis library. Use the ``redis_sentinel``
parameter to set the name of your service group::

RedisAdapter::createConnection(
'redis:?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster'
);

// providing credentials
RedisAdapter::createConnection(
'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster'
);

// providing credentials and selecting database index "3"
RedisAdapter::createConnection(
'redis:default:verysecurepassword@?host[redis1:26379]&host[redis2:26379]&host[redis3:26379]&redis_sentinel=mymaster&dbindex=3'
);

.. versionadded:: 4.2

The option to define multiple servers in a single DSN was introduced in Symfony 4.2.
Expand Down Expand Up @@ -132,29 +153,31 @@ array of ``key => value`` pairs representing option names and their respective v

// associative array of configuration options
[
'lazy' => false,
'class' => null,
'persistent' => 0,
'persistent_id' => null,
'tcp_keepalive' => 0,
'timeout' => 30,
'read_timeout' => 0,
'retry_interval' => 0,
'tcp_keepalive' => 0,
'lazy' => null,
'redis_cluster' => false,
'redis_sentinel' => null,
'dbindex' => 0,
'failover' => 'none',
'ssl' => null,
]

);

Available Options
~~~~~~~~~~~~~~~~~

``class`` (type: ``string``)
``class`` (type: ``string``, default: ``null``)
Specifies the connection library to return, either ``\Redis`` or ``\Predis\Client``.
If none is specified, it will return ``\Redis`` if the ``redis`` extension is
available, and ``\Predis\Client`` otherwise.

``lazy`` (type: ``bool``, default: ``false``)
Enables or disables lazy connections to the backend. It's ``false`` by
default when using this as a stand-alone component and ``true`` by default
when using it inside a Symfony application.
available, and ``\Predis\Client`` otherwise. Explicitly set this to ``\Predis\Client`` for Sentinel if you are
running into issues when retrieving master information.

``persistent`` (type: ``int``, default: ``0``)
Enables or disables use of persistent connections. A value of ``0`` disables persistent
Expand All @@ -163,6 +186,10 @@ Available Options
``persistent_id`` (type: ``string|null``, default: ``null``)
Specifies the persistent id string to use for a persistent connection.

``timeout`` (type: ``int``, default: ``30``)
Specifies the time (in seconds) used to connect to a Redis server before the
connection attempt times out.

``read_timeout`` (type: ``int``, default: ``0``)
Specifies the time (in seconds) used when performing read operations on the underlying
network resource before the operation times out.
Expand All @@ -175,9 +202,28 @@ Available Options
Specifies the `TCP-keepalive`_ timeout (in seconds) of the connection. This
requires phpredis v4 or higher and a TCP-keepalive enabled server.

``timeout`` (type: ``int``, default: ``30``)
Specifies the time (in seconds) used to connect to a Redis server before the
connection attempt times out.
``lazy`` (type: ``bool``, default: ``null``)
Enables or disables lazy connections to the backend. It's ``false`` by
default when using this as a stand-alone component and ``true`` by default
when using it inside a Symfony application.

``redis_cluster`` (type: ``bool``, default: ``false``)
Enables or disables redis cluster. The actual value passed is irrelevant as long as it passes loose comparison
checks: `redis_cluster=1` will suffice.

``redis_sentinel`` (type: ``string``, default: ``null``)
Specifies the master name connected to the sentinels.

``dbindex`` (type: ``int``, default: ``0``)
Specifies the database index to select.

``failover`` (type: ``string``, default: ``none``)
Specifies failover for cluster implementations. For ``\RedisCluster`` valid options are ``none`` (default),
``error``, ``distribute`` or ``slaves``. For ``\Predis\ClientInterface`` valid options are ``slaves``
or ``distribute``.

``ssl`` (type: ``bool``, default: ``null``)
SSL context options. See `php.net/context.ssl`_ for more information.

.. note::

Expand Down Expand Up @@ -225,3 +271,4 @@ Read more about this topic in the offical `Redis LRU Cache Documentation`_.
.. _`TCP-keepalive`: https://redis.io/topics/clients#tcp-keepalive
.. _`Redis Sentinel`: https://redis.io/topics/sentinel
.. _`Redis LRU Cache Documentation`: https://redis.io/topics/lru-cache
.. _`php.net/context.ssl`: https://php.net/context.ssl