PostgresNIO Documentation

Class Postgres​Connection 

public final class PostgresConnection

A Postgres connection. Use it to run queries against a Postgres server.

%261 PostgresConnection PostgresConnection PSQLChannelHandlerNotificationDelegate PSQLChannelHandlerNotificationDelegate PostgresConnection->PSQLChannelHandlerNotificationDelegate PostgresDatabase PostgresDatabase PostgresConnection->PostgresDatabase

Nested Types

PostgresConnection.Configuration

A configuration object for a connection

Conforms To

PostgresDatabase

Nested Type Aliases

ID 

public typealias ID = Int

A Postgres connection ID

Properties

event​Loop 

public var eventLoop: EventLoop

The underlying EventLoop of both the connection and its channel.

close​Future 

public var closeFuture: EventLoopFuture<Void>

logger 

public var logger: Logger

A logger to use in case

is​Closed 

public var isClosed: Bool

Methods

connect(on:​configuration:​id:​logger:​) 

public static func connect(
        on eventLoop: EventLoop,
        configuration: PostgresConnection.Configuration,
        id connectionID: ID,
        logger: Logger
    ) -> EventLoopFuture<PostgresConnection>

Create a new connection to a Postgres server

Parameters

event​Loop Event​Loop

The EventLoop the request shall be created on
configuration Postgres​Connection.​Configuration

A Configuration that shall be used for the connection
connection​ID ID

An Int id, used for metadata logging
logger Logger

A logger to log background events into

Returns

A SwiftNIO EventLoopFuture that will provide a PostgresConnection at a later point in time.

close() 

public func close() -> EventLoopFuture<Void>

Closes the connection to the server.

Returns

An EventLoopFuture that is succeeded once the connection is closed.

connect(to:​tls​Configuration:​server​Hostname:​logger:​on:​) 

@available(*, deprecated,
        message: "Use the new connect method that allows you to connect and authenticate in a single step",
        renamed: "connect(on:configuration:id:logger:)"
    )
    public static func connect(
        to socketAddress: SocketAddress,
        tlsConfiguration: TLSConfiguration? = nil,
        serverHostname: String? = nil,
        logger: Logger = .init(label: "codes.vapor.postgres"),
        on eventLoop: EventLoop
    ) -> EventLoopFuture<PostgresConnection>

authenticate(username:​database:​password:​logger:​) 

@available(*, deprecated,
        message: "Use the new connect method that allows you to connect and authenticate in a single step",
        renamed: "connect(on:configuration:id:logger:)"
    )
    public func authenticate(
        username: String,
        database: String? = nil,
        password: String? = nil,
        logger: Logger = .init(label: "codes.vapor.postgres")
    ) -> EventLoopFuture<Void>

connect(on:​configuration:​id:​logger:​) 

public static func connect(
        on eventLoop: EventLoop,
        configuration: PostgresConnection.Configuration,
        id connectionID: ID,
        logger: Logger
    ) async throws -> PostgresConnection

Creates a new connection to a Postgres server.

Parameters

event​Loop Event​Loop

The EventLoop the request shall be created on
configuration Postgres​Connection.​Configuration

A Configuration that shall be used for the connection
connection​ID ID

An Int id, used for metadata logging
logger Logger

A logger to log background events into

Returns

An established PostgresConnection asynchronously that can be used to run queries.

close() 

public func close() async throws

Closes the connection to the server.

query(_:​logger:​file:​line:​) 

@discardableResult
    public func query(
        _ query: PostgresQuery,
        logger: Logger,
        file: String = #file,
        line: Int = #line
    ) async throws -> PostgresRowSequence

Run a query on the Postgres server the connection is connected to.

Parameters

query Postgres​Query

The PostgresQuery to run
logger Logger

The Logger to log into for the query
file String

The file, the query was started in. Used for better error reporting.
line Int

The line, the query was started in. Used for better error reporting.

Returns

A PostgresRowSequence containing the rows the server sent as the query result. The sequence be discarded.

query(_:​logger:​file:​line:​) 

public func query(
        _ query: PostgresQuery,
        logger: Logger,
        file: String = #file,
        line: Int = #line
    ) -> EventLoopFuture<PostgresQueryResult>

Run a query on the Postgres server the connection is connected to and collect all rows.

Parameters

query Postgres​Query

The PostgresQuery to run
logger Logger

The Logger to log into for the query
file String

The file, the query was started in. Used for better error reporting.
line Int

The line, the query was started in. Used for better error reporting.

Returns

An EventLoopFuture, that allows access to the future PostgresQueryResult.

query(_:​logger:​file:​line:​_:​) 

public func query(
        _ query: PostgresQuery,
        logger: Logger,
        file: String = #file,
        line: Int = #line,
        _ onRow: @escaping (PostgresRow) throws -> ()
    ) -> EventLoopFuture<PostgresQueryMetadata>

Run a query on the Postgres server the connection is connected to and iterate the rows in a callback.

Parameters

query Postgres​Query

The PostgresQuery to run
logger Logger

The Logger to log into for the query
file String

The file, the query was started in. Used for better error reporting.
line Int

The line, the query was started in. Used for better error reporting.
on​Row @escaping (Postgres​Row) throws -> ()

A closure that is invoked for every row.

Returns

An EventLoopFuture, that allows access to the future PostgresQueryMetadata.

send(_:​logger:​) 

public func send(
        _ request: PostgresRequest,
        logger: Logger
    ) -> EventLoopFuture<Void>

with​Connection(_:​) 

public func withConnection<T>(_ closure: (PostgresConnection) -> EventLoopFuture<T>) -> EventLoopFuture<T>

add​Listener(channel:​handler:​) 

@discardableResult
    public func addListener(channel: String, handler notificationHandler: @escaping (PostgresListenContext, PostgresMessage.NotificationResponse) -> Void) -> PostgresListenContext

Add a handler for NotificationResponse messages on a certain channel. This is used in conjunction with PostgreSQL's LISTEN/NOTIFY support: to listen on a channel, you add a listener using this method to handle the NotificationResponse messages, then issue a LISTEN query to instruct PostgreSQL to begin sending NotificationResponse messages.