better docs + a test

Author: MahdiBM

Sources/PostgresNIO/New/PostgresRowSequence.swift

@@ -85,6 +85,14 @@ extension PostgresRowSequence {
     }
 
     /// Consumes all rows and returns the query metadata.
+    ///
+    /// If you don't need the query metadata, just use the for-try-await-loop syntax:
+    /// ```swift
+    /// for try await row in myPostgresSequence {
+    ///     /// Process each row
+    /// }
+    /// ```
+    ///
     /// - Parameter onRow: Processes each row.
     /// - Returns: The query metadata.
     public func consume(

Tests/IntegrationTests/AsyncTests.swift

@@ -1,3 +1,4 @@
+import Atomics
 import Logging
 import XCTest
 import PostgresNIO
@@ -46,6 +47,32 @@ final class AsyncPostgresConnectionTests: XCTestCase {
         }
     }
 
+    func testSelect10kRowsAndConsume() async throws {
+        let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer { XCTAssertNoThrow(try eventLoopGroup.syncShutdownGracefully()) }
+        let eventLoop = eventLoopGroup.next()
+
+        let start = 1
+        let end = 10000
+
+        try await withTestConnection(on: eventLoop) { connection in
+            let rows = try await connection.query("SELECT generate_series(\(start), \(end));", logger: .psqlTest)
+
+            let counter = ManagedAtomic(0)
+            let metadata = try await rows.consume { row in
+                let element = try row.decode(Int.self)
+                let newCounter = counter.wrappingIncrementThenLoad(ordering: .relaxed)
+                XCTAssertEqual(element, newCounter)
+            }
+
+            XCTAssertEqual(metadata.command, "SELECT")
+            XCTAssertEqual(metadata.oid, nil)
+            XCTAssertEqual(metadata.rows, 10000)
+
+            XCTAssertEqual(counter.load(ordering: .relaxed), end)
+        }
+    }
+
     func testSelect10kRowsAndCollect() async throws {
         let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
         defer { XCTAssertNoThrow(try eventLoopGroup.syncShutdownGracefully()) }
@@ -63,6 +90,7 @@ final class AsyncPostgresConnectionTests: XCTestCase {
                 XCTAssertEqual(element, counter + 1)
                 counter += 1
             }
+
             XCTAssertEqual(metadata.command, "SELECT")
             XCTAssertEqual(metadata.oid, nil)
             XCTAssertEqual(metadata.rows, 10000)