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.

id
A unique identifer to represent this connection.
Declaration
Swift

public let id: UUID
Show on GitLab
eventLoop
Declaration
Swift

public var eventLoop: EventLoop { get }
Show on GitLab
isConnected
Is the connection to Redis still open?
Declaration
Swift

public var isConnected: Bool { get }
Show on GitLab
isSubscribed
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 }
Show on GitLab
sendCommandsImmediately
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 to true, the buffer will be drained as soon as commands are added.

Important
Even when set to true, the host machine may still choose to delay sending commands.

Note
Setting this to true will immediately drain the buffer.
Declaration
Swift

public var sendCommandsImmediately: Bool { get set }
Show on GitLab
allowSubscriptions
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 to false, this connection is not allowed to create subscriptions. Any potentially existing subscriptions will be removed.
Declaration
Swift

public var allowSubscriptions: Bool { get set }
Show on GitLab
onUnexpectedClosure
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)?
Show on GitLab

RedisConnection Config

Configuration
A configuration object for creating a single connection to Redis.
See more
Declaration
Swift

public struct Configuration
Show on GitLab


                    
                    
                    make(configuration:boundEventLoop:configuredTCPClient:)

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 as configuredTCPClient.

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:) and NIO.ClientBootstrap in general before doing so.

Note: Use of wait() in the example is for simplicity. Never call wait() on an event loop.

Important

Call close() on the connection before letting the instance deinit to properly cleanup resources.

Invariant

If a password is provided in the configuration, the connection will send an “AUTH” command to Redis as soon as it has been opened.

Invariant

If a database 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 the configuration object.

Show on GitLab

Sending Commands

send(command:with:)
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 the RedisConnection.sendCommandsImmediately property.
Declaration
Swift

public func send(command: String, with arguments: [RESPValue]) -> EventLoopFuture<RESPValue>
Return Value

A NIO.EventLoopFuture that resolves with the command’s result stored in a RESPValue. If a RedisError is returned, the future will be failed instead.

Show on GitLab

Closing a Connection


                    
                    
                    close(logger:)

Sends a QUIT command to Redis, then closes the NIO.Channel that supports this connection.

See https://redis.io/commands/quit

Important

Regardless if the returned NIO.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.

Show on GitLab

Logging


                    
                    
                    logging(to:)

Declaration

Swift

public func logging(to logger: Logger) -> RedisClient

Show on GitLab

Entering PubSub


                    
                    
                    subscribe(to:messageReceiver:onSubscribe:onUnsubscribe:)

Declaration

Swift

public func subscribe(
    to channels: [RedisChannelName],
    messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver,
    onSubscribe subscribeHandler: RedisSubscriptionChangeHandler?,
    onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler?
) -> EventLoopFuture<Void>

Show on GitLab


                    
                    
                    psubscribe(to:messageReceiver:onSubscribe:onUnsubscribe:)

Declaration

Swift

public func psubscribe(
    to patterns: [String],
    messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver,
    onSubscribe subscribeHandler: RedisSubscriptionChangeHandler? = nil,
    onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler? = nil
) -> EventLoopFuture<Void>

Show on GitLab

Leaving PubSub


                    
                    
                    unsubscribe(from:)

Declaration

Swift

public func unsubscribe(from channels: [RedisChannelName]) -> EventLoopFuture<Void>

Show on GitLab


                    
                    
                    punsubscribe(from:)

Declaration

Swift

public func punsubscribe(from patterns: [String]) -> EventLoopFuture<Void>

Show on GitLab


                    
                    
                    defaultPort

The documented default port that Redis connects through.

See https://redis.io/topics/quickstart

Declaration

Swift

@available(*, deprecated, message: "Use RedisConnection.Configuration.defaultPort")
public static var defaultPort: Int { get }

Show on GitLab


                    
                    
                    connect(to:on:password:logger:tcpClient:)

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 as tcpClient.

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:) and NIO.ClientBootstrap in general before doing so.

Note: Use of wait() in the example is for simplicity. Never call wait() on an event loop.

Important

Call close() 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. A `Foundation.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 the `makeRedisTCPClient` instance.

Return Value

A NIO.EventLoopFuture that resolves with the new connection after it has been opened, and if a password is provided, authenticated.

Show on GitLab