Skip to main content

tank_core/
executor.rs

1use crate::{
2    AsEntity, AsQuery, Driver, Entity, MAX_BATCH_SIZE, Query, QueryResult, RawQuery, Result, Row,
3    RowsAffected, Sql,
4    stream::{Stream, StreamExt},
5};
6use anyhow::anyhow;
7use convert_case::{Case, Casing};
8use std::{
9    cmp::max,
10    future::{self, Future},
11    mem,
12    pin::{Pin, pin},
13    task::{self, Poll},
14};
15
16/// Stream adapter returned by [`Executor::fetch`], filtering [`Executor::run`] to rows.
17struct Fetched<S>(S);
18
19impl<S, R> Stream for Fetched<S>
20where
21    S: Stream<Item = Result<QueryResult<R>>>,
22{
23    type Item = Result<R>;
24
25    #[inline(always)]
26    fn poll_next(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Option<Self::Item>> {
27        let mut inner = unsafe { self.map_unchecked_mut(|s| &mut s.0) };
28        loop {
29            match inner.as_mut().poll_next(cx) {
30                Poll::Ready(Some(Ok(QueryResult::Row(row)))) => return Poll::Ready(Some(Ok(row))),
31                Poll::Ready(Some(Ok(QueryResult::Affected(_)))) => {}
32                Poll::Ready(Some(Err(e))) => return Poll::Ready(Some(Err(e))),
33                Poll::Ready(None) => return Poll::Ready(None),
34                Poll::Pending => return Poll::Pending,
35            }
36        }
37    }
38
39    #[inline(always)]
40    fn size_hint(&self) -> (usize, Option<usize>) {
41        self.0.size_hint()
42    }
43}
44
45/// Async query execution. Implemented by connections.
46pub trait Executor: Send {
47    /// Associated driver.
48    type Driver: Driver;
49
50    /// Checks if the driver supports multiple SQL statements in a single request.
51    fn accepts_multiple_statements(&self) -> bool {
52        true
53    }
54
55    /// Optimal size in bytes of a single request.
56    fn batch_size(&self) -> usize {
57        MAX_BATCH_SIZE
58    }
59
60    /// Returns the driver instance associated with this executor.
61    fn driver(&self) -> Self::Driver {
62        Default::default()
63    }
64
65    /// Prepares a query for execution, returning a handle to the prepared statement.
66    ///
67    /// A raw query is borrowed so the caller can keep it.
68    /// A prepared query is taken and returned back as it is.
69    fn prepare<'s>(
70        &'s mut self,
71        query: impl AsQuery<Self::Driver> + 's,
72    ) -> impl Future<Output = Result<Query<Self::Driver>>> + Send {
73        let mut query = query.as_query(&self.driver());
74        async move {
75            match query.as_mut() {
76                Query::Raw(RawQuery(sql)) => self.do_prepare(sql).await.map(Query::Prepared),
77                query => Ok(mem::take(query)),
78            }
79        }
80    }
81
82    /// Internal hook for implementing prepared statement support.
83    fn do_prepare(
84        &mut self,
85        _sql: &str,
86    ) -> impl Future<Output = Result<<Self::Driver as Driver>::Prepared>> + Send {
87        future::ready(Err(anyhow!(
88            "{} does not support prepare",
89            self.driver().name().to_case(Case::Pascal)
90        )))
91    }
92
93    /// Executes a query and streams the results (rows or affected counts).
94    fn run<'s>(
95        &'s mut self,
96        query: impl AsQuery<Self::Driver> + 's,
97    ) -> impl Stream<Item = Result<QueryResult<impl Row + 's>>> + Send;
98
99    /// Executes a query and streams the resulting rows, ignoring affected counts.
100    fn fetch<'s>(
101        &'s mut self,
102        query: impl AsQuery<Self::Driver> + 's,
103    ) -> impl Stream<Item = Result<impl Row + 's>> + Send {
104        Fetched(self.run(query))
105    }
106
107    /// Executes a query and returns the total number of affected rows.
108    fn execute<'s>(
109        &'s mut self,
110        query: impl AsQuery<Self::Driver> + 's,
111    ) -> impl Future<Output = Result<RowsAffected>> + Send {
112        let stream = self.run(query);
113        async move {
114            let mut stream = pin!(stream);
115            let mut affected = RowsAffected::default();
116            while let Some(item) = stream.next().await {
117                if let QueryResult::Affected(a) = item? {
118                    affected.extend([a]);
119                }
120            }
121            Ok(affected)
122        }
123    }
124
125    /// Efficiently inserts a collection of entities bypassing regular SQL execution when supported by the driver.
126    fn append<It>(&mut self, entities: It) -> impl Future<Output = Result<RowsAffected>> + Send
127    where
128        It: IntoIterator + Send,
129        It::IntoIter: Send,
130        It::Item: AsEntity,
131    {
132        self.append_default(entities)
133    }
134}
135
136/// Generic batch insert through regular SQL, for drivers that don't support actual append.
137#[doc(hidden)]
138pub trait AppendDefault: Executor {
139    fn append_default<It>(
140        &mut self,
141        entities: It,
142    ) -> impl Future<Output = Result<RowsAffected>> + Send
143    where
144        It: IntoIterator + Send,
145        It::IntoIter: Send,
146        It::Item: AsEntity,
147    {
148        const DEFAULT_ROWS: usize = 1024;
149        let mut entities = entities.into_iter();
150        async move {
151            // Reuses the allocated SQL buffer across batches.
152            let mut query = Query::<Self::Driver>::default();
153            let mut rows = 0;
154            let mut affected = RowsAffected::default();
155            let batch_size = self.batch_size();
156            let driver = self.driver();
157            let table = <It::Item as AsEntity>::Entity::table();
158            loop {
159                // Scoped so `Peekable` and `batch` never live across `.await`, keeping the future `Send`.
160                {
161                    let mut batch = entities.by_ref().peekable();
162                    let Some(first) = batch.peek() else {
163                        break;
164                    };
165                    let mut out = mem::take(&mut query).into_any(); // Take the buffer
166                    out.clear(); // Clear the content, keep the allocated memory
167                    if rows == 0 {
168                        // Probe the first entity to get the actual SQL size.
169                        Sql()
170                            .insert_into(table)
171                            .values([first.as_entity()])
172                            .write_into(&driver.sql_writer(), &mut out);
173                        rows = max(batch_size.checked_div(out.len()).unwrap_or(DEFAULT_ROWS), 1);
174                    }
175                    let batch = batch.take(rows).collect::<Vec<_>>();
176                    if out.is_empty() || batch.len() > 1 {
177                        out.clear();
178                        Sql()
179                            .insert_into(table)
180                            .values(batch.iter().map(AsEntity::as_entity))
181                            .write_into(&driver.sql_writer(), &mut out);
182                    }
183                    rows = max(
184                        batch_size
185                            .saturating_mul(batch.len())
186                            .checked_div(out.len())
187                            .unwrap_or(DEFAULT_ROWS),
188                        1,
189                    );
190                    query = out.into(); // Give the buffer back
191                }
192                affected.extend([self.execute(&mut query).await?]);
193            }
194            Ok(affected)
195        }
196    }
197}
198
199impl<E: Executor + ?Sized> AppendDefault for E {}
200
201impl<S: Executor + ?Sized> Executor for &mut S {
202    type Driver = S::Driver;
203
204    fn accepts_multiple_statements(&self) -> bool {
205        (**self).accepts_multiple_statements()
206    }
207
208    fn batch_size(&self) -> usize {
209        (**self).batch_size()
210    }
211
212    fn driver(&self) -> Self::Driver {
213        (**self).driver()
214    }
215
216    fn prepare<'s>(
217        &'s mut self,
218        query: impl AsQuery<Self::Driver> + 's,
219    ) -> impl Future<Output = Result<Query<Self::Driver>>> + Send {
220        (**self).prepare(query)
221    }
222
223    fn do_prepare(
224        &mut self,
225        sql: &str,
226    ) -> impl Future<Output = Result<<Self::Driver as Driver>::Prepared>> + Send {
227        (**self).do_prepare(sql)
228    }
229
230    fn run<'s>(
231        &'s mut self,
232        query: impl AsQuery<Self::Driver> + 's,
233    ) -> impl Stream<Item = Result<QueryResult<impl Row + 's>>> + Send {
234        (**self).run(query)
235    }
236
237    fn fetch<'s>(
238        &'s mut self,
239        query: impl AsQuery<Self::Driver> + 's,
240    ) -> impl Stream<Item = Result<impl Row + 's>> + Send {
241        (**self).fetch(query)
242    }
243
244    fn execute<'s>(
245        &'s mut self,
246        query: impl AsQuery<Self::Driver> + 's,
247    ) -> impl Future<Output = Result<RowsAffected>> + Send {
248        (**self).execute(query)
249    }
250
251    fn append<It>(&mut self, entities: It) -> impl Future<Output = Result<RowsAffected>> + Send
252    where
253        It: IntoIterator + Send,
254        It::IntoIter: Send,
255        It::Item: AsEntity,
256    {
257        (**self).append(entities)
258    }
259}