Add docs outlining changes we made to PostgresRow/column(name:) (#312)

Co-authored-by: Tim Condon <[email protected]>

Author: fabianfett

Sources/PostgresNIO/Data/PostgresRow.swift

@@ -131,7 +131,7 @@ public struct PostgresRandomAccessRow {
     let cells: [ByteBuffer?]
     let lookupTable: [String: Int]
 
-    init(_ row: PostgresRow) {
+    public init(_ row: PostgresRow) {
         self.cells = [ByteBuffer?](row.data)
         self.columns = row.columns
         self.lookupTable = row.lookupTable

Sources/PostgresNIO/Docs.docc/index.md

@@ -15,6 +15,10 @@ Features:
 
 ## Topics
 
+### Articles
+
+- <doc:migrations>
+
 ### Connections
 
 - ``PostgresConnection``

Sources/PostgresNIO/Docs.docc/migrations.md

@@ -0,0 +1,102 @@
+# Adopting the new PostgresRow cell API
+
+This article describes how to adopt the new ``PostgresRow`` cell APIs in existing Postgres code 
+which use the ``PostgresRow/column(_:)`` API today.  
+
+## TLDR
+
+1. Map your sequence of ``PostgresRow``s to ``PostgresRandomAccessRow``s.
+2. Use the ``PostgresRandomAccessRow/subscript(name:)`` API to receive a ``PostgresCell``
+3. Decode the ``PostgresCell`` into a Swift type using the ``PostgresCell/decode(_:file:line:)`` method.
+
+```swift
+let rows: [PostgresRow] // your existing return value
+for row in rows.map({ PostgresRandomAccessRow($0) }) {
+    let id = try row["id"].decode(UUID.self)
+    let name = try row["name"].decode(String.self)
+    let email = try row["email"].decode(String.self)
+    let age = try row["age"].decode(Int.self)
+}
+```
+
+## Overview
+
+When Postgres [`1.9.0`] was released we changed the default behaviour of ``PostgresRow``s.
+Previously for each row we created an internal lookup table, that allowed you to access the rows'
+cells by name:
+
+```swift
+connection.query("SELECT id, name, email, age FROM users").whenComplete {
+    switch $0 {
+    case .success(let result):
+        for row in result.rows {
+            let id = row.column("id").uuid
+            let name = row.column("name").string
+            let email = row.column("email").string
+            let age = row.column("age").int
+            // do further processing
+        }
+    case .failure(let error):
+        // handle the error
+    }
+}
+```
+
+During the last year we introduced a new API that let's you consume ``PostgresRow`` by iterating 
+its cells. This approach has the performance benefit of not needing to create an internal cell 
+lookup table for each row:
+
+```swift
+connection.query("SELECT id, name, email, age FROM users").whenComplete {
+    switch $0 {
+    case .success(let result):
+        for row in result.rows {
+            let (id, name, email, age) = try row.decode((UUID, String, String, Int).self)
+            // do further processing
+        }
+    case .failure(let error):
+        // handle the error
+    }
+}
+```
+
+However, since we still supported the ``PostgresRow/column(_:)`` API, which requires a precomputed 
+lookup table within the row, users were not seeing any performance benefits. To allow users to 
+benefit of the new fastpath, we changed ``PostgresRow``'s behavior:
+
+By default the ``PostgresRow`` does not create an internal lookup table for its cells on creation 
+anymore. Because of this, when using the ``PostgresRow/column(_:)`` API, a throwaway lookup table 
+needs to be produced on every call. Since this is wasteful we have deprecated this API. Instead we 
+allow users now to explicitly opt-in into the cell lookup API by using the new 
+``PostgresRandomAccessRow``.
+
+```swift
+connection.query("SELECT id, name, email, age FROM users").whenComplete {
+    switch $0 {
+    case .success(let result):
+        for row in result.rows.map { PostgresRandomAccessRow($0) } {
+            let id = try row["id"].decode(UUID.self)
+            let name = try row["name"].decode(String.self)
+            let email = try row["email"].decode(String.self)
+            let age = try row["age"].decode(Int.self)
+            // do further processing
+        }
+    case .failure(let error):
+        // handle the error
+    }
+}
+```
+
+## Topics
+
+### Relevant types
+
+- ``PostgresConnection``
+- ``PostgresQuery``
+- ``PostgresBindings``
+- ``PostgresRow``
+- ``PostgresRandomAccessRow``
+- ``PostgresEncodable``
+- ``PostgresDecodable``
+
+[`1.9.0`]: https://github.com/vapor/postgres-nio/releases/tag/1.9.0

Sources/PostgresNIO/New/PostgresCell.swift

@@ -1,14 +1,26 @@
 import NIOCore
 
+/// A representation of a cell value within a ``PostgresRow`` and ``PostgresRandomAccessRow``.
 public struct PostgresCell: Equatable {
+    /// The cell's value as raw bytes.
     public var bytes: ByteBuffer?
+    /// The cell's data type. This is important metadata when decoding the cell.
     public var dataType: PostgresDataType
+    /// The format in which the cell's bytes are encoded.
     public var format: PostgresFormat
 
+    /// The cell's column name within the row.
     public var columnName: String
+    /// The cell's column index within the row.
     public var columnIndex: Int
 
-    init(bytes: ByteBuffer?, dataType: PostgresDataType, format: PostgresFormat, columnName: String, columnIndex: Int) {
+    public init(
+        bytes: ByteBuffer?,
+        dataType: PostgresDataType,
+        format: PostgresFormat,
+        columnName: String,
+        columnIndex: Int
+    ) {
         self.bytes = bytes
         self.dataType = dataType
         self.format = format
@@ -19,7 +31,14 @@ public struct PostgresCell: Equatable {
 }
 
 extension PostgresCell {
-
+    /// Decode the cell into a Swift type, that conforms to ``PostgresDecodable``
+    ///
+    /// - Parameters:
+    ///   - _: The Swift type, which conforms to ``PostgresDecodable``, to decode from the cell's ``PostgresCell/bytes`` values.
+    ///   - context: A ``PostgresDecodingContext`` to supply a custom ``PostgresJSONDecoder`` for decoding JSON fields.
+    ///   - file: The source file in which this method was called. Used in the error case in ``PostgresDecodingError``.
+    ///   - line: The source file line in which this method was called. Used in the error case in ``PostgresDecodingError``.
+    /// - Returns: A decoded Swift type.
     @inlinable
     public func decode<T: PostgresDecodable, JSONDecoder: PostgresJSONDecoder>(
         _: T.Type,
@@ -49,6 +68,23 @@ extension PostgresCell {
             )
         }
     }
+
+
+    /// Decode the cell into a Swift type, that conforms to ``PostgresDecodable``
+    ///
+    /// - Parameters:
+    ///   - _: The Swift type, which conforms to ``PostgresDecodable``, to decode from the cell's ``PostgresCell/bytes`` values.
+    ///   - file: The source file in which this method was called. Used in the error case in ``PostgresDecodingError``.
+    ///   - line: The source file line in which this method was called. Used in the error case in ``PostgresDecodingError``.
+    /// - Returns: A decoded Swift type.
+    @inlinable
+    public func decode<T: PostgresDecodable>(
+        _: T.Type,
+        file: String = #file,
+        line: Int = #line
+    ) throws -> T {
+        try self.decode(T.self, context: .default, file: file, line: line)
+    }
 }
 
 #if swift(>=5.6)