ResultCursor reports command complete status immediately with a zero-result query. Column metadata is now held on ResultCursor if requested. SqlStatementTest passes.

Author: willtemperley

Package.swift

@@ -6,7 +6,7 @@ import PackageDescription
 let package = Package(
     name: "SwiftPostgresClient",
     platforms: [
-        .macOS(.v10_15), .iOS(.v14), .tvOS(.v13)
+        .macOS(.v11), .iOS(.v14), .tvOS(.v14)
     ],
     products: [
         // Products define the executables and libraries a package produces, making them visible to other packages.

README.md

@@ -30,11 +30,9 @@ This project has been adapted from PostgresClientKit, with the following changes
 
 - **Channel binding support.** A security feature for SCRAM-SHA-256 authentication over TLS, channel binding links the TLS session to the authentication exchange, protecting against man-in-the-middle (MitM) attacks.
 
-Sounds good?  Let's look at an example.
-
 ## Example
 
-This is a basic, but complete, example of how to connect to Postgres, perform a SQL `SELECT` command, and process the resulting rows.  It uses the `weather` table in the [Postgres tutorial](https://www.postgresql.org/docs/11/tutorial-table.html).
+This is a basic, but complete, example of how to connect to a PostgresSQL server, perform a SQL `SELECT` command, and process the resulting rows.  It uses the `weather` table in the [Postgres tutorial](https://www.postgresql.org/docs/current/tutorial-table.html).
 
 ```swift
 import SwiftPostgresClient

Sources/SwiftPostgresClient/Codable/PostgresError.swift

@@ -20,6 +20,7 @@
 /// Errors thrown by PostgresClientKit.
 public enum PostgresError: Error {
 
+    
     case awaitingAuthentication
 
     case invalidState(String)

Sources/SwiftPostgresClient/Connection+portal.swift

@@ -35,16 +35,13 @@ extension Connection {
 
         try await receiveResponse(type: BindCompleteResponse.self)
 
-        var rowDecoder: RowDecoder?
+        var metadata: [ColumnMetadata]?
         if columnMetadata {
-            let metadata = try await retrieveColumnMetadata(portalName: portalName)
-            if let metadata {
-                rowDecoder = RowDecoder(columns: metadata)
-            }
+            metadata = try await retrieveColumnMetadata(portalName: portalName)
         }
         portalStatus[portalName] = .open
 
-        return Portal(name: portalName, rowDecoder: rowDecoder, statement: statement, connection: self)
+        return Portal(name: portalName, metadata: metadata, statement: statement, connection: self)
     }
 
     func cleanupPortal(name: String) async throws {

Sources/SwiftPostgresClient/Connection+query.swift

@@ -45,7 +45,7 @@ extension Connection {
     func query(
         portalName: String,
         statement: Statement,
-        rowDecoder: RowDecoder?
+        metadata: [ColumnMetadata]?
     ) async throws -> ResultCursor {
 
         state = .querySent
@@ -56,7 +56,14 @@ extension Connection {
         let flushRequest = FlushRequest()
         try await sendRequest(flushRequest)
 
-        return ResultCursor(connection: self, portalName: portalName, rowDecoder: rowDecoder)
+        // The first response of the query is evaluated eagerly to check its
+        // type.
+        // An zero-result query could immediately give a CommandCompleteResponse
+        // This also prevents some issues with undrained message queues.
+        // TODO: check error response
+        let response = await receiveResponse()
+
+        return ResultCursor(connection: self, portalName: portalName, metadata: metadata, initialResponse: response)
     }
 
     public func closeStatement(name: String) async throws {

Sources/SwiftPostgresClient/Connection+transaction.swift

@@ -36,11 +36,11 @@ extension Connection {
         }
     }
 
-    func beginTransaction() async throws {
+    public func beginTransaction() async throws {
         try await executeSimpleQuery("BEGIN;")
     }
 
-    func commitTransaction() async throws {
+    public func commitTransaction() async throws {
         try await executeSimpleQuery("COMMIT;")
     }
 

Sources/SwiftPostgresClient/Connection.swift

@@ -22,7 +22,7 @@ import Network
 import CryptoKit
 
 /// A Connection actor provides asynchronous access to a PostgreSQL server.
-actor Connection {
+public actor Connection {
 
     enum ConnectionState {
         case awaitingAuthentication
@@ -50,6 +50,7 @@ actor Connection {
     var transactionStatus: TransactionStatus = .idle
 
     var commandStatus: CommandStatus?
+    var peekedResponse: Response?
 
     private init(socket: NetworkConnection, certificateHash: Data) {
         self.socket = socket
@@ -122,7 +123,6 @@ actor Connection {
     }
 
     func updateState(for response: Response) {
-        print("updating state for \(response)")
         switch response {
         case is DataRowResponse, is RowDescriptionResponse:
             state = .awaitingQueryResult
@@ -143,7 +143,6 @@ actor Connection {
         }
     }
 
-    
     @discardableResult
     func receiveResponse<T: Response>(type: T.Type) async throws -> T {
         while true {
@@ -232,6 +231,7 @@ actor Connection {
             return
 
         case .querySent, .awaitingQueryResult, .needsDrain:
+            logWarning("State is \(state), emptying message queue and sending sync request.")
             // Cleanup all open portals
             for name in self.portalStatus.keys {
                 try await sendRequest(ClosePortalRequest(name: name))

Sources/SwiftPostgresClient/Logger.swift

@@ -0,0 +1,32 @@
+// Logger.swift
+// SwiftPostgresClient
+//
+// Created by Will Temperley on 18/07/2025. All rights reserved.
+// Copyright 2025 Will Temperley.
+// 
+// Copying or reproduction of this file via any medium requires prior express
+// written permission from the copyright holder.
+// -----------------------------------------------------------------------------
+///
+/// Implementation notes, links and internal documentation go here.
+///
+// -----------------------------------------------------------------------------
+
+
+#if DEBUG
+#if canImport(os)
+import os
+private let logger = Logger(subsystem: "com.geolocalised.swiftpostgresclient", category: "debug")
+#endif
+#endif
+
+public func logWarning(_ message: String) {
+    #if DEBUG
+    #if canImport(os)
+    logger.warning("\(message, privacy: .public)")
+    #else
+    print("Warning: \(message)")
+    #endif
+    #endif
+}
+

Sources/SwiftPostgresClient/Portal.swift

@@ -28,20 +28,20 @@ import Foundation
 public struct Portal {
 
     let name: String
-    let rowDecoder: RowDecoder?
+    let metadata: [ColumnMetadata]?
     let statement: Statement
     unowned let connection: Connection
 
     /// Executes the associated prepared statement with already bound parameters.
     ///
     /// - Returns: an `AsyncSequence` of rows. This is a single use iterator.
-    func query() async throws -> ResultCursor {
+    public func query() async throws -> ResultCursor {
 
-        return try await connection.query(portalName: name, statement: statement, rowDecoder: rowDecoder)
+        return try await connection.query(portalName: name, statement: statement, metadata: metadata)
     }
 
     @discardableResult
-    func execute() async throws -> CommandStatus {
+    public func execute() async throws -> CommandStatus {
 
         let executeRequest = ExecuteRequest(portalName: name, statement: statement)
         try await connection.sendRequest(executeRequest)
@@ -52,5 +52,21 @@ public struct Portal {
         try await connection.cleanupPortal(name: name)
         return response.status
     }
-}
+    
+    /// Executes a query that returns a single value (e.g. COUNT, SUM, etc.).
+    public func singleValue() async throws -> PostgresValue? {
+        
+        let cursor = try await query()
+        var iterator = cursor.makeAsyncIterator()
+        let row = try await iterator.next()
+        if let row {
+            let next = try await iterator.next()
+            if next != nil {
+                try await connection.recoverIfNeeded()
+            }
+            return row.columns.first?.postgresValue
+        }
+        return nil
+    }
 
+}

Sources/SwiftPostgresClient/ResultCursor.swift

@@ -22,20 +22,50 @@ public struct ResultCursor: AsyncSequence, Sendable {
 
     let connection: Connection
     let portalName: String
+    let metatdata: [ColumnMetadata]?
     let rowDecoder: RowDecoder?
+    let initialResponse: Response?
+    let commandStatus: CommandStatus?
 
     /// Either the number of rows returned or the number of rows affected by the associated statement.
     /// This will not be available until after the result set has been consumed.
+    /// 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`).
     var rowCount: Int? {
         get async {
-            await connection.commandStatus?.rowCount
+            if let commandStatus {
+                return commandStatus.rowCount
+            } else {
+                return await connection.commandStatus?.rowCount
+            }
         }
     }
 
-    init(connection: Connection, portalName: String, rowDecoder: RowDecoder? = nil) {
+    init(connection: Connection, portalName: String, metadata: [ColumnMetadata]? = nil, initialResponse: Response?) {
         self.connection = connection
         self.portalName = portalName
-        self.rowDecoder = rowDecoder
+        self.metatdata = metadata
+        if let metadata = metadata {
+            self.rowDecoder = RowDecoder(columns: metadata)
+        } else {
+            self.rowDecoder = nil
+        }
+        self.initialResponse = initialResponse
+        if case let response as CommandCompleteResponse = initialResponse {
+            self.commandStatus = response.status
+        } else {
+            self.commandStatus = nil
+        }
     }
 
     /// Creates the asynchronous iterator that produces elements of this
@@ -44,7 +74,7 @@ public struct ResultCursor: AsyncSequence, Sendable {
     /// - Returns: An instance of the `AsyncIterator` type used to produce
     /// messages in the asynchronous sequence.
     public func makeAsyncIterator() -> AsyncIterator {
-        return AsyncIterator(connection: connection, portalName: portalName, rowDecoder: rowDecoder)
+        return AsyncIterator(connection: connection, portalName: portalName, rowDecoder: rowDecoder, initialResponse: initialResponse)
     }
 
     /// An asynchronous iterator that produces the rows of this asynchronous sequence.
@@ -54,26 +84,34 @@ public struct ResultCursor: AsyncSequence, Sendable {
         var connection: Connection
         var portalName: String
         var rowDecoder: RowDecoder?
+        var initialResponse: Response?
 
+        mutating func nextResponse() async throws -> Response {
+            if let nextResponse =  initialResponse {
+                self.initialResponse = nil
+                return nextResponse
+            } else {
+                return await connection.receiveResponse()
+            }
+        }
+
         mutating public func next() async throws -> Row? {
 
             guard await connection.connected else {
                 throw PostgresError.connectionClosed
             }
 
             while true {
-                let response = await connection.receiveResponse()
+                let response = try await nextResponse()
 
                 switch response {
                 case let dataRow as DataRowResponse:
-                    do {
-                        let row = Row(columns: dataRow.columns, columnNameRowDecoder: rowDecoder)
-                        return row
-                    } catch {
-                        throw error
-                    }
+                    
+                    let row = Row(columns: dataRow.columns, columnNameRowDecoder: rowDecoder)
+                    return row
 
                 case is EmptyQueryResponse:
+                    
                     try await connection.setCommandStatus(to: .empty)
                     try await connection.cleanupPortal(name: portalName)
                     return nil