Cursor

public class Cursor : Sequence, IteratorProtocol

The result of successfully executing a Statement.

Note

Do not confuse this Cursor class with the SQL cursors created by the SQL DECLARE command. The Cursor class exposes the result of executing a single SQL command. A SQL cursor, on other other hand, exposes a query’s result by repeated execution of the SQL FETCH command.

When a Cursor is no longer required, call Cursor.close() to release its Postgres server resources. A Cursor is implicitly closed as a side effect of certain operations on a connection; refer to the Connection documentation for a full list. A Cursor is also automatically closed by its deinitializer.

A Cursor in PostgresClientKit corresponds to the unnamed portal of the connection on the Postgres server.

See also

Postgres: Message Flow - Extended Query
  • id

    Uniquely identifies this Cursor.

    Used in logging and to formulate the description.

    Declaration

    Swift

    public let id: String

  • Metadata about the columns in the results, or nil if column metadata is not available.

    For column metadata to be available, set retrieveColumnMetadata to true in calling Statement.execute(parameterValues:retrieveColumnMetadata:).

    Each element in the returned value describes the corresponding element in the columns of each Row of the results.

    Declaration

    Swift

    public let columns: [ColumnMetadata]?

  • The Statement to which this Cursor belongs.

    Declaration

    Swift

    public let statement: Statement

  • The number of rows affected by the Statement.

    The specific interpretation of this value depends on the SQL command performed:

    • INSERT: the number of rows inserted
    • UPDATE: the number of rows updated
    • DELETE: the number of rows deleted
    • SELECT or CREATE TABLE AS: the number of rows retrieved
    • MOVE: the number of rows by which the SQL cursor’s position changed
    • FETCH: the number of rows retrieved from the SQL cursor
    • COPY: the number of rows copied

    If this Cursor has one or more rows, this property is nil until the final row has been retrieved (in other words, until next() returns nil).

    Declaration

    Swift

    public internal(set) var rowCount: Int? { get }

  • Whether this Cursor is closed.

    To close a Cursor, call close().

    Declaration

    Swift

    public var isClosed: Bool { get }

  • Closes this Cursor.

    Has no effect if this Cursor is already closed.

    Declaration

    Swift

    public func close()

IteratorProtocol

  • Gets the next Row of this Cursor.

    Example of use:

    let cursor: Cursor = ...
for row in cursor {
    let columns = try row.get().columns // throws upon an error
    ...
}

    Declaration

    Swift

    public func next() -> Result<Row, Error>?

    Return Value

    a value that represents success (with an associated Row) or failure (with an associated Error); or nil if there are no more rows

CustomStringConvertible

  • A short string that identifies this Cursor.

    Declaration

    Swift

    public var description: String { get }