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
  • 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 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 }
  • 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 }
  • 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 more

    Declaration

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

  • 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.

  • 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.

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

    Declaration

    Swift

    @available(*, deprecated, message: "Use 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 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.