document Cursor

sqlx-core/src/cursor.rs

@@ -1,3 +1,5 @@
+//! Contains the `Cursor` trait.
+
 use futures_core::future::BoxFuture;
 
 use crate::database::{Database, HasRow};
@@ -6,16 +8,41 @@ use crate::pool::Pool;
 
 /// Represents a result set, which is generated by executing a query against the database.
 ///
-/// A `Cursor` can be created by either [`Executor::execute`](trait.Execute.html) or
-/// [`Query::fetch`](struct.Query.html).
+/// A `Cursor` can be created by either [`Executor::fetch`] or [`Query::fetch`].
+///
+/// ```rust,ignore
+/// let mut cursor = sqlx::query("SELECT slug, title, description FROM articles")
+///     .fetch(&mut conn);
+/// ```
 ///
 /// Initially the `Cursor` is positioned before the first row. The `next` method moves the cursor
 /// to the next row, and because it returns `None` when there are no more rows, it can be used
 /// in a `while` loop to iterate through all returned rows.
+///
+/// ```rust,ignore
+/// # #[derive(sqlx::FromRow)]
+/// # struct Article<'a> {
+/// #     slug: &'a str,
+/// #     title: &'a str,
+/// #     description: &'a str,
+/// # }
+/// #
+/// // For each row in the result set ..
+/// while let Some(row) = cursor.next().await? {
+///     // .. decode a domain type from the row
+///     let obj = Article::from_row(row)?;
+/// }
+/// ```
+///
+/// This trait is sealed and cannot be implemented for types outside of SQLx.
+///
+/// [`Executor::fetch`]: crate::executor::Executor::fetch
+/// [`Query::fetch`]: crate::query::Query::fetch
 pub trait Cursor<'c, 'q>
 where
-    Self: Send,
+    Self: Send + Unpin + private::Sealed,
 {
+    /// The `Database` this `Cursor` is implemented for.
     type Database: Database;
 
     #[doc(hidden)]
@@ -33,8 +60,13 @@ where
         Self: Sized,
         E: Execute<'q, Self::Database>;
 
-    /// Creates a future that resolves to the next row in the cursor.
+    /// Creates a future that attempts to resolve the next row in the cursor.
     fn next<'cur>(
         &'cur mut self,
     ) -> BoxFuture<'cur, crate::Result<Self::Database, Option<<Self::Database as HasRow<'cur>>::Row>>>;
 }
+
+// Prevent users from implementing the `Row` trait.
+pub(crate) mod private {
+    pub trait Sealed {}
+}

sqlx-core/src/mysql/cursor.rs

@@ -18,6 +18,8 @@ pub struct MySqlCursor<'c, 'q> {
     binary: bool,
 }
 
+impl crate::cursor::private::Sealed for MySqlCursor<'_, '_> {}
+
 impl<'c, 'q> Cursor<'c, 'q> for MySqlCursor<'c, 'q> {
     type Database = MySql;
 

sqlx-core/src/postgres/cursor.rs

@@ -19,6 +19,8 @@ pub struct PgCursor<'c, 'q> {
     formats: Arc<[TypeFormat]>,
 }
 
+impl crate::cursor::private::Sealed for PgCursor<'_, '_> {}
+
 impl<'c, 'q> Cursor<'c, 'q> for PgCursor<'c, 'q> {
     type Database = Postgres;
 

sqlx-core/src/row.rs

@@ -62,7 +62,7 @@ pub trait Row<'c>
 where
     Self: private_row::Sealed + Unpin + Send,
 {
-    /// The database this `Row` is from.
+    /// The `Database` this `Row` is implemented for.
     type Database: Database;
 
     /// Returns `true` if this row has no columns.

sqlx-core/src/sqlite/cursor.rs

@@ -14,6 +14,8 @@ pub struct SqliteCursor<'c, 'q> {
     pub(super) statement: Option<Option<usize>>,
 }
 
+impl crate::cursor::private::Sealed for SqliteCursor<'_, '_> {}
+
 impl<'c, 'q> Cursor<'c, 'q> for SqliteCursor<'c, 'q> {
     type Database = Sqlite;