RedisConnection
public final class RedisConnection : RedisClient, RedisClientWithUserContext
A concrete RedisClient
implementation that represents an individual connection to a Redis instance.
For basic setups, you will just need a NIO.EventLoop
and perhaps a password
.
let eventLoop: EventLoop = ...
let connection = RedisConnection.make(
configuration: .init(hostname: "my.redis.url", password: "some_password"),
boundEventLoop: eventLoop
).wait()
let result = try connection.set("my_key", to: "some value")
.flatMap { return connection.get("my_key") }
.wait()
print(result) // Optional("some value")
Note: wait()
is used in the example for simplicity. Never call wait()
on an event loop.
-
A unique identifer to represent this connection.
Declaration
Swift
public let id: UUID
-
Declaration
Swift
public var eventLoop: EventLoop { get }
-
Is the connection to Redis still open?
Declaration
Swift
public var isConnected: Bool { get }
-
Is the connection currently subscribed for PubSub?
Only a narrow list of commands are allowed when in “PubSub mode”.
See PUBSUB.
Declaration
Swift
public var isSubscribed: Bool { get }
-
Controls the behavior of when sending commands over this connection. The default is `true.
When set to
false
, the commands will be placed into a buffer, and the host machine will determine when to drain the buffer. When set totrue
, the buffer will be drained as soon as commands are added.Important
Even when set totrue
, the host machine may still choose to delay sending commands.Note
Setting this totrue
will immediately drain the buffer.Declaration
Swift
public var sendCommandsImmediately: Bool { get set }
-
Controls the permission of the connection to be able to have PubSub subscriptions or not.
When set to
true
, this connection is allowed to create subscriptions. When set tofalse
, this connection is not allowed to create subscriptions. Any potentially existing subscriptions will be removed.Declaration
Swift
public var allowSubscriptions: Bool { get set }
-
A closure to invoke when the connection closes unexpectedly.
An unexpected closure is when the connection is closed by any other method than by calling
close(logger:)
.Declaration
Swift
public var onUnexpectedClosure: (() -> Void)?
-
A configuration object for creating a single connection to Redis.
See moreDeclaration
Swift
public struct Configuration
-
Creates a new connection with provided configuration and sychronization objects.
If you would like to specialize the
NIO.ClientBootstrap
that the connection communicates on, override the default by passing it in asconfiguredTCPClient
.let eventLoopGroup: EventLoopGroup = ... var customTCPClient = ClientBootstrap.makeRedisTCPClient(group: eventLoopGroup) customTCPClient.channelInitializer { channel in // channel customizations } let connection = RedisConnection.make( configuration: ..., boundEventLoop: eventLoopGroup.next(), configuredTCPClient: customTCPClient ).wait()
It is recommended that you be familiar with
ClientBootstrap.makeRedisTCPClient(group:)
andNIO.ClientBootstrap
in general before doing so.Note: Use of
wait()
in the example is for simplicity. Never callwait()
on an event loop.Important
Callclose()
on the connection before letting the instance deinit to properly cleanup resources.Invariant
If apassword
is provided in the configuration, the connection will send an “AUTH” command to Redis as soon as it has been opened.Invariant
If adatabase
index is provided in the configuration, the connection will send a “SELECT” command to Redis after it has been authenticated.Declaration
Swift
public static func make( configuration config: Configuration, boundEventLoop eventLoop: EventLoop, configuredTCPClient client: ClientBootstrap? = nil ) -> EventLoopFuture<RedisConnection>
Parameters
config
The configuration to use for creating the connection.
eventLoop
The
NIO.EventLoop
that the connection will be bound to.client
If you have chosen to configure a
NIO.ClientBootstrap
yourself, this will be used instead of the.makeRedisTCPClient
factory instance.Return Value
A
NIO.EventLoopFuture
that resolves with the new connection after it has been opened, configured, and authenticated per theconfiguration
object.
-
Sends the command with the provided arguments to Redis.
See
RedisClient.send(command:with:)
.Note
The timing of when commands are actually sent to Redis can be controlled with theRedisConnection.sendCommandsImmediately
property.Declaration
Return Value
A
NIO.EventLoopFuture
that resolves with the command’s result stored in aRESPValue
. If aRedisError
is returned, the future will be failed instead.
-
Sends a
QUIT
command to Redis, then closes theNIO.Channel
that supports this connection.See https://redis.io/commands/quit
Important
Regardless if the returnedNIO.EventLoopFuture
fails or succeeds - after calling this method the connection should no longer be used for sending commands to Redis.Declaration
Swift
@discardableResult public func close(logger: Logger? = nil) -> EventLoopFuture<Void>
Parameters
logger
An optional logger instance to use while trying to close the connection. If one is not provided, the pool will use its default logger.
Return Value
A
NIO.EventLoopFuture
that resolves when the connection has been closed.
-
Declaration
Swift
public func logging(to logger: Logger) -> RedisClient
-
Declaration
Swift
public func subscribe( to channels: [RedisChannelName], messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver, onSubscribe subscribeHandler: RedisSubscriptionChangeHandler?, onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler? ) -> EventLoopFuture<Void>
-
Declaration
Swift
public func psubscribe( to patterns: [String], messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver, onSubscribe subscribeHandler: RedisSubscriptionChangeHandler? = nil, onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler? = nil ) -> EventLoopFuture<Void>
-
Declaration
Swift
public func unsubscribe(from channels: [RedisChannelName]) -> EventLoopFuture<Void>
-
Declaration
Swift
public func punsubscribe(from patterns: [String]) -> EventLoopFuture<Void>
-
The documented default port that Redis connects through.
Declaration
Swift
@available(*, deprecated, renamed: "RedisConnection.Configuration.defaultPort") public static var defaultPort: Int { get }
-
Creates a new connection to a Redis instance.
If you would like to specialize the
NIO.ClientBootstrap
that the connection communicates on, override the default by passing it in astcpClient
.let eventLoopGroup: EventLoopGroup = ... var customTCPClient = ClientBootstrap.makeRedisTCPClient(group: eventLoopGroup) customTCPClient.channelInitializer { channel in // channel customizations } let connection = RedisConnection.connect( to: ..., on: eventLoopGroup.next(), password: ..., tcpClient: customTCPClient ).wait()
It is recommended that you be familiar with
ClientBootstrap.makeRedisTCPClient(group:)
andNIO.ClientBootstrap
in general before doing so.Note: Use of
wait()
in the example is for simplicity. Never callwait()
on an event loop.Important
Callclose()
on the connection before letting the instance deinit to properly cleanup resources.Note
If a
password
is provided, the connection will send an “AUTH” command to Redis as soon as it has been opened.Declaration
Swift
@available(*, deprecated, message: "Use make(configuration:boundEventLoop:configuredTCPClient:﹚ instead") public static func connect( to socket: SocketAddress, on eventLoop: EventLoop, password: String? = nil, logger: Logger = .redisBaseConnectionLogger, tcpClient: ClientBootstrap? = nil ) -> EventLoopFuture<RedisConnection>
Parameters
socket
The
NIO.SocketAddress
information of the Redis instance to connect to.eventLoop
The
NIO.EventLoop
that this connection will execute all tasks on.password
The optional password to use for authorizing the connection with Redis.
logger
The
Logging.Logger
instance to use for all client logging purposes. If one is not provided, one will be created. AFoundation.UUID
will be attached to the metadata to uniquely identify this connection instance’s logs.tcpClient
If you have chosen to configure a
NIO.ClientBootstrap
yourself, this will be used instead of themakeRedisTCPClient
instance.Return Value
A
NIO.EventLoopFuture
that resolves with the new connection after it has been opened, and if apassword
is provided, authenticated.