[syoung-smallwisdom]

Iterating the sequence that Connection.prepare(_:) returns goes through FailableIterator.next(), which is try! failableNext(). So if sqlite3_step fails partway through the results (SQLITE_BUSY once the busy timeout runs out, SQLITE_LOCKED, an I/O error, a corrupt page), the app crashes. It isn't a thrown error that a do/catch can handle.

The docs don't make this clear:

• The README's first example iterates prepare(_:) with no warning. That's the API most people copy.
• Documentation/Index.md says the iterator "can throw undeclared database errors". It doesn't throw; it aborts execution.
• The "Plucking Rows" and "Retrieving Codable Types" examples still use prepare(_:), even though the "Failable iteration" section just above them recommends RowIterator.

This PR changes documentation only:

• README: a warning after the first example that points to prepareRowIterator(_:) and the Failable iteration section.
• Index.md: says the error aborts execution and can't be caught, and switches the Plucking Rows (try Array(db.prepareRowIterator(users))) and Codable (try db.prepareRowIterator(users).map { … }) examples to RowIterator.

I compiled and ran the updated examples against current master.

Context: changing next() to try? was tried in #1030 and reverted in #1075, and #1273 tried again but was closed. A non-throwing Sequence can't report an error partway through, so pointing people to RowIterator seems like the practical fix.

🤖 Generated with Claude Code

[syoung-smallwisdom]

Related: #1383 proposes also deprecating prepare(_ query:) -> AnySequence<Row> so callers get a compiler warning. Kept separate so this docs change can merge on its own.