1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
//! Contains the `Cursor` trait. use futures_core::future::BoxFuture; use crate::database::Database; use crate::executor::Execute; use crate::pool::Pool; use crate::row::HasRow; /// Represents a result set, which is generated by executing a query against the database. /// /// 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 + Unpin + private::Sealed, { /// The `Database` this `Cursor` is implemented for. type Database: Database; #[doc(hidden)] fn from_pool<E>(pool: &Pool<<Self::Database as Database>::Connection>, query: E) -> Self where Self: Sized, E: Execute<'q, Self::Database>; #[doc(hidden)] fn from_connection<E>( connection: &'c mut <Self::Database as Database>::Connection, query: E, ) -> Self where Self: Sized, E: Execute<'q, Self::Database>; /// Creates a future that attempts to resolve the next row in the cursor. fn next<'cur>( &'cur mut self, ) -> BoxFuture<'cur, crate::Result<Option<<Self::Database as HasRow<'cur>>::Row>>>; } // Prevent users from implementing the `Row` trait. pub(crate) mod private { pub trait Sealed {} } /// Associate [`Database`] with a [`Cursor`] of a generic lifetime. /// /// --- /// /// The upcoming Rust feature, [Generic Associated Types], should obviate /// the need for this trait. /// /// [Generic Associated Types]: https://www.google.com/search?q=generic+associated+types+rust&oq=generic+associated+types+rust&aqs=chrome..69i57j0l5.3327j0j7&sourceid=chrome&ie=UTF-8 pub trait HasCursor<'c, 'q> { type Database: Database; /// The concrete `Cursor` implementation for this database. type Cursor: Cursor<'c, 'q, Database = Self::Database>; }