Detach materialized SQL rows from transaction lifetime

lyngio/stdlib/lyng/io/db.lyng

@@ -44,11 +44,11 @@ extern class SqlRow {
     - iteration to the end or canceled iteration should close the underlying
       resources automatically
     - using the result set after its transaction ends is invalid
-    - rows obtained from the result set are also invalid after the owning
-      transaction ends, even if the implementation had already buffered them
+    - rows obtained from the result set stay usable after the owning
+      transaction ends once they have been materialized
 
-    If user code wants row data to survive independently, it should copy the
-    values it needs into ordinary Lyng objects while the transaction is active.
+    Calling `toList()` while the transaction is active is the normal way to
+    detach rows for use after the transaction block returns.
 */
 extern class ResultSet : Iterable<SqlRow> {
     /*
@@ -84,7 +84,8 @@ extern class ExecutionResult {
         other result set.
 
         If the statement produced no generated values, the returned result set
-        is empty.
+        is empty. Call `toList()` if generated-key rows must outlive the
+        transaction.
     */
     fun getGeneratedKeys(): ResultSet
 }