Instance Method

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

Run a query on the Postgres server the connection is connected to and return the query’s metadata alongside the body closure’s result.

func query<Result>(_ query: PostgresQuery, logger: Logger, file: String = #fileID, line: Int = #line, _ body: (PostgresRowSequence) async throws -> Result) async throws -> (result: Result, metadata: PostgresQueryMetadata)

Parameters

query: The PostgresQuery to run
logger: The Logger to log into for the query
file: The file the query was started in. Used for better error reporting.
line: The line the query was started in. Used for better error reporting.
body: The closure that’s used to consume the query result. Must consume the sequence to its end.

Return Value

The result of the body closure and the query metadata.

Discussion

The result of the query can only be consumed inside of the body closure and attempting to consume the stream outside of the closure will throw PSQLError.rowSequenceUsedOutsideScope. Rows that were already buffered when body returned are still delivered before the error is thrown.

The metadata is derived from the command tag the server sends after the last row, so body must iterate the sequence to its end. If it returns early the query is cancelled and the method throws PSQLError.rowSequenceNotFullyConsumed.