Skip to main content

sqlive/
connection.rs

1//! A connection to a database, the host's SQL capability. `HostSql` never
2//! returns or lends out SQLite's connection.
3
4#[path = "app_statements.rs"]
5mod app_statements;
6#[path = "bulk_write.rs"]
7mod bulk_write;
8#[path = "database_file.rs"]
9mod database_file;
10#[path = "event_capture.rs"]
11mod event_capture;
12#[path = "live_judging.rs"]
13mod live_judging;
14#[path = "page_cache.rs"]
15mod page_cache;
16#[path = "pre_update_changes.rs"]
17mod pre_update_changes;
18#[path = "rolled_back.rs"]
19mod rolled_back;
20#[path = "schema_cookie.rs"]
21mod schema_cookie;
22#[cfg(any(test, feature = "profiles"))]
23#[path = "statement_profiles.rs"]
24mod statement_profiles;
25#[path = "stream_capture.rs"]
26mod stream_capture;
27#[path = "table_shapes.rs"]
28pub(crate) mod table_shapes;
29#[path = "transaction_capture.rs"]
30mod transaction_capture;
31#[path = "write_transaction.rs"]
32mod write_transaction;
33#[path = "write_with.rs"]
34mod write_with;
35#[cfg(any(test, feature = "profiles"))]
36pub use statement_profiles::ProfiledStatement;
37#[cfg(any(test, feature = "test-utils"))]
38#[path = "test_hooks.rs"]
39mod test_hooks;
40use app_statements::StepsOf;
41pub use event_capture::Operation;
42pub use schema_cookie::CookieScope;
43use transaction_capture::ChangeCapture;
44use write_transaction::WriteTransaction;
45
46use std::collections::BTreeSet;
47use std::path::Path;
48use std::sync::Arc;
49
50use rusqlite::{fallible_iterator::FallibleIterator, Batch, Connection, OpenFlags, Params, Row};
51
52use crate::authorization::PolicyError;
53use crate::authorization::SqlAuthorization;
54use crate::authorization::{Policy, Refresh};
55use crate::connection_setup::Setup;
56
57/// Statements kept prepared per connection, the host's and the app's: a
58/// local write in coven runs about a hundred distinct ones of its own, which
59/// a smaller cache would evict before reuse, beside the app's.
60const STATEMENT_CACHE: usize = 512;
61
62/// Whether a statement run through `app_query` belongs to a read, whose
63/// statements a test can record, rather than a write or a migration.
64#[derive(Clone, Copy, PartialEq, Eq)]
65pub enum Recorded {
66    /// A read's statement, which a test's statement log records.
67    Yes,
68    /// A write's or a migration's statement.
69    No,
70}
71
72/// A connection to a database, as its host runs SQL on it: the host's own
73/// statements and the app's, each judged by the authorizer and the host's
74/// policy `P`.
75pub struct HostSql<P: Policy> {
76    #[cfg(any(test, feature = "test-utils"))]
77    work: std::cell::RefCell<Option<crate::test_records::ConnectionWorkCounter>>,
78    /// Where this connection's reads push the statements they run.
79    #[cfg(any(test, feature = "test-utils"))]
80    statement_log: std::cell::RefCell<Option<crate::test_records::StatementLog>>,
81    connection: Connection,
82    authorization: SqlAuthorization<P>,
83    /// What the host adds to the authorizer's rules, shared with the
84    /// authorizer.
85    policy: Arc<P>,
86    /// Stops a lookup that runs too long (`live_judging.rs`).
87    lookups: live_judging::LookupLimit,
88    app_statements: app_statements::AppStatements,
89    /// The schema cookie while a transaction that runs no DDL holds it.
90    cookie: schema_cookie::SchemaCookie,
91    /// The open handle this connection serves: it receives the commits and
92    /// failures after which the handle refuses calls. None while opening, when
93    /// a failure fails the open and drops the connection instead.
94    handle: Option<crate::Handle<P::Failure>>,
95    observation: Option<WriterObservation>,
96    /// The main schema's tables as last read, with the schema they were
97    /// read in (table_shapes.rs).
98    shapes: std::cell::RefCell<Option<(i64, Arc<table_shapes::TableShapes>)>>,
99    /// The writer's checkpointer, woken after each commit (§4).
100    checkpoints: Option<crate::upkeep::Wake>,
101    /// The database's watch of its main file's size, to which this connection
102    /// sends the size after each checkpoint it runs through `wal_checkpoint`.
103    /// The writer and the checkpointer hold it; a reader holds none.
104    checkpointed_sizes: Option<tokio::sync::watch::Sender<u64>>,
105    /// The writer's keeper of the planner's statistics, woken as its
106    /// commits change rows (§4).
107    statistics: Option<crate::planner_statistics::ChangeWake>,
108    streaming: std::cell::Cell<bool>,
109    /// The host's values that this connection's functions read as each
110    /// transaction's snapshot saw them (`snapshot_values.rs`).
111    snapshot_values: crate::snapshot_values::SnapshotValues,
112    /// Orders this connection's commits against the snapshots of the reads
113    /// beside it: the database's connections share it.
114    commit_order: Arc<crate::snapshot_values::CommitOrder>,
115    #[cfg(any(test, feature = "test-utils"))]
116    commit_points: std::cell::RefCell<Option<crate::test_records::CommitPointObserver>>,
117    #[cfg(any(test, feature = "profiles"))]
118    scans: Arc<std::sync::Mutex<Vec<ProfiledStatement>>>,
119    /// How many profiles are open: a profile inside another, as a
120    /// migration's inside the open's, leaves the outer one tracing.
121    #[cfg(any(test, feature = "profiles"))]
122    profiles: std::cell::Cell<usize>,
123    /// Panic in the next call of a write transaction's hook, as a bug in
124    /// what it captures would.
125    #[cfg(any(test, feature = "test-utils"))]
126    hook_panics: Arc<std::sync::atomic::AtomicBool>,
127}
128
129struct WriterObservation {
130    /// The tables whose operations a write keeps whole, lowercase.
131    recorded: Arc<BTreeSet<String>>,
132}
133
134impl<P: Policy> HostSql<P> {
135    #[cfg(any(test, feature = "test-utils"))]
136    /// Count this connection's work into `counter` from now on.
137    pub fn test_track_work(&self, counter: crate::test_records::ConnectionWorkCounter) {
138        *self.work.borrow_mut() = Some(counter);
139    }
140
141    #[cfg(any(test, feature = "test-utils"))]
142    /// Record the statements this connection's reads run into `log` from
143    /// now on.
144    pub fn test_record_statements(&self, log: crate::test_records::StatementLog) {
145        *self.statement_log.borrow_mut() = Some(log);
146    }
147
148    #[cfg(any(test, feature = "test-utils"))]
149    pub(crate) fn record_work(
150        &self,
151        update: impl FnOnce(&mut crate::test_records::ConnectionWork),
152    ) {
153        if let Some(counter) = self.work.borrow().as_ref() {
154            counter.record(update);
155        }
156    }
157
158    /// A connection to the database at `path`, for reading only when
159    /// `read_only`, whose authorizer asks `policy` after its own rules and
160    /// treats `whole_views` as a live query's whole reads. `setup` registers
161    /// what the connection needs, given its policy, before any SQL runs.
162    pub fn open(
163        path: &Path,
164        read_only: bool,
165        policy: P,
166        whole_views: Arc<crate::WholeViews>,
167        settings: &crate::SqliteSettings,
168        setup: &dyn Fn(&Setup<'_, P>, &P) -> rusqlite::Result<()>,
169    ) -> Result<Self, PolicyError<P>> {
170        let policy = Arc::new(policy);
171        let authorization = SqlAuthorization::new(whole_views, Arc::clone(&policy));
172        let flags = if read_only {
173            OpenFlags::SQLITE_OPEN_READ_ONLY
174        } else {
175            OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::SQLITE_OPEN_CREATE
176        };
177        // The flags leave out SQLite's URI reading: the path names a file in
178        // the host's directory, never a SQLite URI or an in-memory database
179        // that a caller picked.
180        crate::sqlite_temporary::opening()?;
181        let path = crate::sqlite_path::sqlite_path(path)?;
182        let mut connection =
183            Connection::open_with_flags(&path, flags | OpenFlags::SQLITE_OPEN_NO_MUTEX)?;
184        connection.set_prepared_statement_cache_capacity(STATEMENT_CACHE);
185        connection.set_db_config(rusqlite::config::DbConfig::SQLITE_DBCONFIG_DQS_DML, false)?;
186        connection.set_db_config(rusqlite::config::DbConfig::SQLITE_DBCONFIG_DQS_DDL, false)?;
187        // SQL that could damage the database file fails: writing a virtual
188        // table's shadow tables directly, `PRAGMA writable_schema` and
189        // `PRAGMA schema_version = N`, and turning the journal off (§4).
190        connection.set_db_config(rusqlite::config::DbConfig::SQLITE_DBCONFIG_DEFENSIVE, true)?;
191        // A statement's plan never reads the values bound to it. Otherwise
192        // SQLite marks a statement whose plan looked at a bound value, and
193        // the statement cache clearing its bindings as each use ends makes
194        // SQLite parse and plan it again on its next use, once per row of a
195        // commit's lookups.
196        connection.set_db_config(rusqlite::config::DbConfig::SQLITE_DBCONFIG_ENABLE_QPSG, true)?;
197        let registered = Setup::new(&connection, &authorization);
198        setup(&registered, &policy)?;
199        let snapshot_values = registered.into_snapshot_values();
200        connection.authorizer(Some(authorization.callback()))?;
201        let lookups = live_judging::LookupLimit::install(&mut connection)?;
202        let db = Self {
203            #[cfg(any(test, feature = "test-utils"))]
204            work: std::cell::RefCell::new(None),
205            #[cfg(any(test, feature = "test-utils"))]
206            statement_log: std::cell::RefCell::new(None),
207            connection,
208            authorization,
209            policy,
210            lookups,
211            app_statements: app_statements::AppStatements::default(),
212            cookie: schema_cookie::SchemaCookie::default(),
213            handle: None,
214            observation: None,
215            shapes: std::cell::RefCell::new(None),
216            checkpoints: None,
217            checkpointed_sizes: None,
218            statistics: None,
219            streaming: std::cell::Cell::new(false),
220            snapshot_values,
221            commit_order: Arc::new(crate::snapshot_values::CommitOrder::new()),
222            #[cfg(any(test, feature = "test-utils"))]
223            commit_points: std::cell::RefCell::new(None),
224            #[cfg(any(test, feature = "profiles"))]
225            scans: Arc::new(std::sync::Mutex::new(Vec::new())),
226            #[cfg(any(test, feature = "profiles"))]
227            profiles: std::cell::Cell::new(0),
228            #[cfg(any(test, feature = "test-utils"))]
229            hook_panics: Arc::default(),
230        };
231        db.configure(settings, read_only)?;
232        db.refresh_policy(Refresh::Whole)?;
233        Ok(db)
234    }
235
236    /// The most arguments an SQL function call can pass on this connection.
237    #[cfg(any(test, feature = "test-utils"))]
238    pub fn function_argument_limit(&self) -> Result<usize, PolicyError<P>> {
239        Ok(self.connection.limit(rusqlite::limits::Limit::SQLITE_LIMIT_FUNCTION_ARG)? as usize)
240    }
241
242    /// The most bytes a string or BLOB can hold on this connection.
243    pub fn length_limit(&self) -> rusqlite::Result<i32> {
244        self.connection.limit(rusqlite::limits::Limit::SQLITE_LIMIT_LENGTH)
245    }
246
247    /// Open the BLOB in `column` of the row `rowid` of the main schema's
248    /// `table`, for reading only when `read_only`.
249    pub fn open_blob(
250        &self,
251        table: &str,
252        column: &str,
253        rowid: i64,
254        read_only: bool,
255    ) -> rusqlite::Result<rusqlite::blob::Blob<'_>> {
256        let _scope = self.authorization.internal();
257        self.connection.blob_open(rusqlite::MAIN_DB, table, column, rowid, read_only)
258    }
259
260    /// Fail the handle this connection serves with `failure`, so every later
261    /// call and live query reports it. A connection that serves no handle
262    /// yet fails nothing.
263    pub fn fail_handle(&self, failure: P::Failure) {
264        if let Some(handle) = &self.handle {
265            handle.fail(failure);
266        }
267    }
268
269    /// Run `run` with this connection's policy in `scope`, leaving the scope
270    /// on every path out of `run`, a panic's included.
271    pub fn within<T>(&self, scope: P::Scope, run: impl FnOnce() -> T) -> T {
272        self.policy.enter(&scope);
273        let _entered = EnteredScope { policy: &*self.policy, scope };
274        run()
275    }
276
277    /// Have this connection's policy read the schema again (`Policy::refresh`).
278    pub fn refresh_policy(&self, extent: Refresh) -> rusqlite::Result<()> {
279        self.policy.refresh(self, extent)
280    }
281
282    /// Whether SQLite opened the main database for reading only.
283    pub fn read_only(&self) -> rusqlite::Result<bool> {
284        self.connection.is_readonly(rusqlite::MAIN_DB)
285    }
286
287    /// Whether this connection is a writer that observes its commits.
288    pub fn observes_commits(&self) -> bool {
289        self.observation.is_some()
290    }
291
292    /// Run `run` on this connection. Tests trace its statements, ending the
293    /// profile on every path out of `run`, a panic's included, so a profile
294    /// is never left open; one inside another nests (sqlite_tests.rs).
295    pub fn with_profile<T>(&mut self, run: impl FnOnce(&mut Self) -> T) -> T {
296        #[cfg(not(any(test, feature = "profiles")))]
297        return run(self);
298        #[cfg(any(test, feature = "profiles"))]
299        {
300            struct Profiled<'a, P: Policy>(&'a mut HostSql<P>);
301            impl<P: Policy> Drop for Profiled<'_, P> {
302                fn drop(&mut self) {
303                    self.0.end_profile();
304                }
305            }
306            self.start_profile();
307            let profiled = Profiled(self);
308            run(&mut *profiled.0)
309        }
310    }
311
312    /// Fail the handle when removing a transaction's `hook` failed: what the
313    /// connection would call next is unknown. Removal never panics, since it
314    /// runs as a transaction drops, perhaps during an unwind.
315    pub(crate) fn removed_hook(&self, hook: &'static str, removed: rusqlite::Result<()>) {
316        if let Err(error) = removed {
317            tracing::error!(hook, %error, "removing a transaction's hook failed");
318            self.fail_handle(P::Failure::from(crate::EngineFailure::Hook(error.into())));
319        }
320    }
321
322    /// Run the host's own statements in `sql`, one after another.
323    pub fn batch(&self, sql: &str) -> Result<(), PolicyError<P>> {
324        let _scope = self.authorization.internal();
325        self.connection.execute_batch(sql).map_err(Into::into)
326    }
327
328    /// The collation a column declares, BINARY when it names none.
329    pub fn column_collation(&self, table: &str, column: &str) -> Result<String, PolicyError<P>> {
330        let _scope = self.authorization.internal();
331        let (_, collation, _, _, _) =
332            self.connection.column_metadata(Some("main"), table, column)?;
333        Ok(collation.map_or_else(|| "BINARY".into(), |c| c.to_string_lossy().into_owned()))
334    }
335
336    /// The columns `sql` reads and the functions it calls, as SQLite
337    /// resolves them while preparing it; it never runs.
338    pub fn reads(&self, sql: &str) -> Result<crate::authorization::StatementReads, PolicyError<P>> {
339        let _scope = self.authorization.internal();
340        let reads = self.authorization.observe_reads();
341        self.connection.prepare(sql)?;
342        Ok(reads.reads())
343    }
344
345    /// Run the host's own statement `sql` with `params`, returning the rows
346    /// it changed.
347    pub fn execute<Q: Params>(&self, sql: &str, params: Q) -> Result<usize, PolicyError<P>> {
348        let _scope = self.authorization.internal();
349        let changed = self.with_statement(sql, |statement| {
350            statement.execute(params).map_err(crate::Error::from)
351        })?;
352        self.bound_stream_cache()?;
353        Ok(changed)
354    }
355
356    /// The first row of the host's own query `sql` with `params`, through
357    /// `map`.
358    pub fn query_row<T, Q: Params>(
359        &self,
360        sql: &str,
361        params: Q,
362        map: impl FnOnce(&Row<'_>) -> rusqlite::Result<T>,
363    ) -> Result<T, PolicyError<P>> {
364        let _scope = self.authorization.internal();
365        self.authorization.begin_read_statement();
366        let result = self.with_statement(sql, |statement| {
367            statement.query_row(params, map).map_err(crate::Error::from)
368        });
369        self.authorization.record_statement(&crate::Scopes::default());
370        result
371    }
372
373    /// Every row of the host's own query `sql` with `params`, through `map`.
374    pub fn query<T, Q: Params>(
375        &self,
376        sql: &str,
377        params: Q,
378        mut map: impl FnMut(&Row<'_>) -> rusqlite::Result<T>,
379    ) -> Result<Vec<T>, PolicyError<P>> {
380        let mut values = Vec::new();
381        self.for_each::<_, PolicyError<P>>(sql, params, |row| {
382            values.push(map(row)?);
383            Ok(())
384        })?;
385        Ok(values)
386    }
387
388    /// Stream rows to a consumer with its own error type.
389    pub fn for_each<Q: Params, E: From<PolicyError<P>>>(
390        &self,
391        sql: &str,
392        params: Q,
393        mut visit: impl FnMut(&Row<'_>) -> Result<(), E>,
394    ) -> Result<(), E> {
395        let _scope = self.authorization.internal();
396        self.authorization.begin_read_statement();
397        let result = self.with_statement(sql, |statement| {
398            let mut rows = statement.query(params).map_err(crate::Error::from)?;
399            while let Some(row) = rows.next().map_err(crate::Error::from)? {
400                visit(row)?;
401            }
402            Ok(())
403        });
404        self.authorization.record_statement(&crate::Scopes::default());
405        result
406    }
407
408    /// `prepared`, or the error the authorizer refused it with.
409    fn judged<T>(&self, prepared: rusqlite::Result<T>) -> Result<T, PolicyError<P>> {
410        Ok(self.authorization.app_result(prepared)?)
411    }
412
413    /// Run the host's own SQL on the connection's cached statement, which
414    /// SQLite parses once per connection. The authorizer records reads only
415    /// while SQLite prepares a statement, so while it records, this function
416    /// prepares the statement again instead of taking the cached one.
417    fn with_statement<T, E: From<PolicyError<P>>>(
418        &self,
419        sql: &str,
420        run: impl FnOnce(&mut rusqlite::Statement<'_>) -> Result<T, E>,
421    ) -> Result<T, E> {
422        if self.authorization.recording() {
423            run(&mut self.judged(self.connection.prepare(sql))?)
424        } else {
425            let mut statement = self.judged(self.connection.prepare_cached(sql))?;
426            // The statement profile reports each execution's own full scans.
427            #[cfg(any(test, feature = "profiles"))]
428            statement.reset_status(rusqlite::StatementStatus::FullscanStep);
429            run(&mut statement)
430        }
431    }
432
433    /// Prepare `sql` as the host's own statement, compiling every trigger
434    /// it would fire and those they fire in turn, and drop it unrun. What
435    /// the authorizer refused in an app trigger it compiles is the error.
436    pub fn prepare_host(&self, sql: &str) -> Result<(), PolicyError<P>> {
437        let prepared = {
438            let _scope = self.authorization.internal();
439            self.connection.prepare(sql).map(drop)
440        };
441        self.judged(prepared)
442    }
443
444    /// Prepare the app statement `sql`, judged as an app statement is, and
445    /// drop it unrun: what preparing it tells the policy is the result.
446    pub fn prepare_app(&self, sql: &str) -> rusqlite::Result<()> {
447        self.authorization.check_sql(sql)?;
448        self.begin_app_statement()?;
449        self.authorization.app_result(self.connection.prepare(sql)).map(drop)
450    }
451
452    /// Run the app's statement `sql` with `params`, judged as the app's,
453    /// returning the rows it changed.
454    pub fn app_execute<Q: Params>(&self, sql: &str, params: Q) -> rusqlite::Result<usize> {
455        self.authorization.check_sql(sql)?;
456        self.begin_app_statement()?;
457        let mut statement = self.authorization.app_result(self.app_statement(sql))?;
458        let _scope = self.authorization.step();
459        let changed = self.authorization.app_result(self.counting_steps(
460            &mut statement,
461            StepsOf::AppWrite,
462            |statement| statement.execute(params),
463        ))?;
464        drop(statement);
465        self.bound_stream_cache()?;
466        Ok(changed)
467    }
468
469    /// Run the app's statements in `sql`, one after another, each judged as
470    /// the app's.
471    pub fn app_batch(&self, sql: &str) -> rusqlite::Result<()> {
472        self.app_batch_each(sql, |_, step| step())
473    }
474
475    /// Run the app's statements in `sql` one at a time, handing `each` the
476    /// text of each as SQLite expanded it and a call that steps it through
477    /// its rows. `each` runs that call once, between whatever it does before
478    /// and after the statement.
479    pub fn app_batch_each(
480        &self,
481        sql: &str,
482        mut each: impl FnMut(&str, &mut dyn FnMut() -> rusqlite::Result<()>) -> rusqlite::Result<()>,
483    ) -> rusqlite::Result<()> {
484        self.authorization.check_sql(sql)?;
485        let mut batch = Batch::new(&self.connection, sql);
486        loop {
487            self.begin_app_statement()?;
488            let Some(mut statement) = self.authorization.app_result(batch.next())? else {
489                return Ok(());
490            };
491            let text = statement.expanded_sql().expect("prepared SQL");
492            let mut step = || {
493                // Step every row, so SQLite reports an error that a later
494                // row raises.
495                let result = self.counting_steps(&mut statement, StepsOf::AppWrite, |statement| {
496                    let mut rows = statement.raw_query();
497                    let _scope = self.authorization.step();
498                    while rows.next()?.is_some() {}
499                    Ok(())
500                });
501                self.authorization.app_result(result)
502            };
503            each(&text, &mut step)?;
504        }
505    }
506
507    /// SQLite's count of changes to the main schema, read afresh.
508    pub fn schema_cookie(&self) -> rusqlite::Result<i64> {
509        let _scope = self.authorization.internal();
510        self.connection.prepare_cached("PRAGMA main.schema_version")?.query_row([], |r| r.get(0))
511    }
512
513    /// Run one migration step inside the open migration transaction. The
514    /// policy records which tables its statements write as SQLite prepares
515    /// them (§18.1).
516    pub fn migrating<T, E: From<PolicyError<P>>>(
517        &self,
518        run: impl FnOnce() -> Result<T, E>,
519    ) -> Result<T, E> {
520        assert!(self.observation.is_none(), "migrations precede commit observation");
521        let result = run()?;
522        self.require_transaction()?;
523        Ok(result)
524    }
525
526    /// The first row of the app's query `sql` with `params`, through `map`;
527    /// a read's statement when `recorded` says so.
528    pub fn app_query_row<T, Q: Params>(
529        &self,
530        recorded: Recorded,
531        sql: &str,
532        params: Q,
533        map: impl FnOnce(&Row<'_>) -> rusqlite::Result<T>,
534    ) -> rusqlite::Result<T> {
535        let mut map = Some(map);
536        let mut value = None;
537        self.app_rows(recorded, sql, params, |row| {
538            let map = map.take().expect("the first row ends the read");
539            value = Some(map(row)?);
540            Ok(false)
541        })?;
542        value.ok_or(rusqlite::Error::QueryReturnedNoRows)
543    }
544
545    /// Every row of the app's query `sql` with `params`, through `map`; a
546    /// read's statement when `recorded` says so.
547    pub fn app_query<T, Q: Params>(
548        &self,
549        recorded: Recorded,
550        sql: &str,
551        params: Q,
552        mut map: impl FnMut(&Row<'_>) -> rusqlite::Result<T>,
553    ) -> rusqlite::Result<Vec<T>> {
554        let mut values = Vec::new();
555        self.app_rows(recorded, sql, params, |row| {
556            values.push(map(row)?);
557            Ok(true)
558        })?;
559        Ok(values)
560    }
561
562    /// Run an app statement and hand `each` its rows in order, under the
563    /// authorizer's read and step scopes, until the rows end or `each`
564    /// answers false.
565    fn app_rows<Q: Params>(
566        &self,
567        recorded: Recorded,
568        sql: &str,
569        params: Q,
570        mut each: impl FnMut(&Row<'_>) -> rusqlite::Result<bool>,
571    ) -> rusqlite::Result<()> {
572        self.authorization.check_sql(sql)?;
573        self.begin_app_statement()?;
574        self.authorization.begin_read_statement();
575        let result = (|| {
576            let mut statement = self.app_statement(sql)?;
577            let parameters = crate::parameters(&self.connection, &statement, params)?;
578            let plan = self.live_scope_plan(sql, &statement)?;
579            // A run that returns as many rows as its LIMIT depends only on the
580            // rows up to its last one (§4).
581            let last_row = plan.as_ref().and_then(|plan| plan.last_row(&parameters));
582            let mut last = None;
583            let result = self.counting_steps(&mut statement, StepsOf::AppRead, |statement| {
584                let mut rows = statement.query(rusqlite::params_from_iter(&parameters))?;
585                let mut returned = 0;
586                loop {
587                    let row = {
588                        let _scope = self.authorization.step();
589                        self.authorization.app_result(rows.next())?
590                    };
591                    let Some(row) = row else { return Ok(()) };
592                    returned += 1;
593                    if let Some(last_row) =
594                        last_row.as_ref().filter(|found| found.limit == returned)
595                    {
596                        last = Some(last_row.values(row)?);
597                    }
598                    if !each(row)? {
599                        return Ok(());
600                    }
601                }
602            });
603            self.record_app_statement(plan.as_deref(), &parameters, last.as_deref());
604            #[cfg(any(test, feature = "test-utils"))]
605            if recorded == Recorded::Yes {
606                if let Some(log) = self.statement_log.borrow().as_ref() {
607                    log.push(statement.expanded_sql().expect("prepared SQL"));
608                }
609            }
610            #[cfg(not(any(test, feature = "test-utils")))]
611            let _ = recorded;
612            result
613        })();
614        self.authorization.app_result(result)
615    }
616
617    /// Wake `checkpoints` after each commit this writer makes (§4).
618    pub(crate) fn signal_commits(&mut self, checkpoints: crate::upkeep::Wake) {
619        self.checkpoints = Some(checkpoints);
620    }
621
622    /// Send the main database file's size to `sizes` after each checkpoint
623    /// run through `wal_checkpoint`.
624    pub(crate) fn send_checkpointed_sizes(&mut self, sizes: tokio::sync::watch::Sender<u64>) {
625        self.checkpointed_sizes = Some(sizes);
626    }
627
628    /// Tell `statistics` of the rows each commit this writer makes changed
629    /// (§4).
630    pub(crate) fn signal_changes(&mut self, statistics: crate::planner_statistics::ChangeWake) {
631        self.statistics = Some(statistics);
632    }
633
634    /// The rows this connection's statements have changed since it opened,
635    /// their triggers' included, as SQLite counts them.
636    pub fn changed_rows(&self) -> u64 {
637        self.connection.total_changes()
638    }
639
640    /// Order this connection's commits and snapshots with `order`, which the
641    /// other connections to its database share.
642    pub(crate) fn share_commit_order(&mut self, order: Arc<crate::snapshot_values::CommitOrder>) {
643        self.commit_order = order;
644    }
645
646    /// Serve an open handle once opening succeeds (§4).
647    pub(crate) fn serve(&mut self, handle: crate::Handle<P::Failure>) {
648        assert!(self.handle.is_none(), "a connection serves one handle");
649        self.authorization.serve(handle.clone());
650        self.handle = Some(handle);
651    }
652
653    /// Serve the handle as its writer, capturing each commit's row changes and
654    /// keeping a write's operations on the `recorded` tables whole.
655    pub(crate) fn observe_commits(
656        &mut self,
657        handle: crate::Handle<P::Failure>,
658        recorded: BTreeSet<String>,
659    ) {
660        assert!(self.observation.is_none(), "a writer starts observing its commits only once");
661        self.serve(handle);
662        self.observation = Some(WriterObservation { recorded: Arc::new(recorded) });
663    }
664
665    /// The scope in which the app's write SQL runs.
666    pub fn write_scope(&self) -> crate::authorization::WriteSql<'_, P> {
667        self.authorization.write()
668    }
669
670    /// The scope in which app SQL the host runs inside a transaction of its
671    /// own writes: the policy judges each statement as in the local scope
672    /// (`StatementScope::local`), and SQLite prepares each afresh. Inside a
673    /// bulk write, the tables it changes count among the bulk write's.
674    pub fn local_scope(&self) -> crate::authorization::LocalSql<'_, P> {
675        self.authorization.local()
676    }
677
678    /// Refuse with `TransactionEnded` unless a transaction is open: a
679    /// statement may have committed or rolled back the one its caller began.
680    pub fn require_transaction(&self) -> Result<(), PolicyError<P>> {
681        if self.connection.is_autocommit() {
682            Err(crate::Error::TransactionEnded)
683        } else {
684            Ok(())
685        }
686    }
687
688    fn begin_app_statement(&self) -> rusqlite::Result<()> {
689        self.require_transaction()
690            .map_err(|error| rusqlite::Error::UserFunctionError(Box::new(error)))?;
691        // Migrations may create, rename or rebuild tables between app statements.
692        // Ordinary writes reuse what the policy read without querying SQLite's
693        // schema.
694        self.refresh_policy(Refresh::Changed)?;
695        self.authorization.begin_app_call();
696        Ok(())
697    }
698
699    /// Run `run` in a write transaction, whose failures are `E`: a failed
700    /// rollback joins the run's own error.
701    pub fn transaction<T, E: crate::RollbackJoin<P::Failure, P::Refusal>>(
702        &mut self,
703        run: impl FnOnce(&Self) -> Result<T, E>,
704    ) -> Result<T, E> {
705        self.transaction_captured(false, run)
706    }
707
708    /// Streaming transfers publish table invalidations without a session's
709    /// retained before/after BLOB values growing with the transferred object.
710    pub fn stream_transaction<T, E: crate::RollbackJoin<P::Failure, P::Refusal>>(
711        &mut self,
712        run: impl FnOnce(&Self) -> Result<T, E>,
713    ) -> Result<T, E> {
714        self.transaction_captured(true, run)
715    }
716
717    fn transaction_captured<T, E: crate::RollbackJoin<P::Failure, P::Refusal>>(
718        &mut self,
719        streaming: bool,
720        run: impl FnOnce(&Self) -> Result<T, E>,
721    ) -> Result<T, E> {
722        let mut transaction = WriteTransaction::begin(self, streaming)?;
723        // StreamCapture records a streamed transaction's operations; on a
724        // serving writer, a session records any other transaction's changes.
725        // The write-record session ends before materialization, but this
726        // session covers app SQL, merge metadata, materialization and local
727        // tables.
728        let observing = if streaming {
729            stream_capture::StreamCapture::begin(&mut transaction).map(Observing::Stream)
730        } else if transaction.within(|database| database.observation.is_some()) {
731            transaction_capture::SupplementalChanges::observe(&mut transaction)
732                .map(Observing::Session)
733        } else {
734            Ok(Observing::Nothing)
735        };
736        let outcome = observing.map_err(E::from).and_then(|observing| {
737            transaction.within(|database| {
738                let (stream, mut session) = match observing {
739                    Observing::Stream(stream) => (Some(stream), None),
740                    Observing::Session(supplemental) => {
741                        (None, Some(ChangeCapture::begin(database, supplemental)?))
742                    }
743                    Observing::Nothing => (None, None),
744                };
745                let result = run(database)?;
746                database.require_transaction()?;
747                let changes = match (&mut session, &stream) {
748                    (Some(session), _) => session.take_changes()?,
749                    (None, Some(stream)) => match stream.changes() {
750                        stream_capture::StreamChanges::Rows(rows) => rows,
751                        stream_capture::StreamChanges::Tables(tables) => {
752                            crate::change_capture::table_changes(database, tables)?
753                        }
754                    },
755                    (None, None) => crate::net_changes::Captured::default(),
756                };
757                Ok((result, changes))
758            })
759        });
760        transaction.commit(outcome)
761    }
762
763    /// Close the connection, failing if SQLite still holds a statement of
764    /// it.
765    pub fn close(self) -> Result<(), PolicyError<P>> {
766        self.connection.close().map_err(|(_connection, error)| error.into())
767    }
768
769    /// Prepare a statement and never finalize it, so SQLite refuses to close
770    /// this connection, as it does with `SQLITE_BUSY`.
771    #[cfg(any(test, feature = "test-utils"))]
772    pub fn leave_statement_open(&self) {
773        let mut statement = std::ptr::null_mut();
774        // SAFETY: the handle is this live connection's and the text is a
775        // NUL-terminated literal. This function never uses or finalizes the
776        // statement.
777        let prepared = unsafe {
778            rusqlite::ffi::sqlite3_prepare_v2(
779                self.connection.handle(),
780                c"SELECT 1".as_ptr(),
781                -1,
782                &mut statement,
783                std::ptr::null_mut(),
784            )
785        };
786        assert_eq!(prepared, rusqlite::ffi::SQLITE_OK);
787    }
788
789    /// Call `callback` at each point this connection's write transactions
790    /// pass as they commit, from now on.
791    #[cfg(any(test, feature = "test-utils"))]
792    pub fn on_commit_point(
793        &self,
794        callback: impl Fn(crate::test_records::CommitPoint) + Send + 'static,
795    ) {
796        *self.commit_points.borrow_mut() = Some(Box::new(callback));
797    }
798
799    #[cfg(any(test, feature = "test-utils"))]
800    pub(crate) fn commit_point(&self, point: crate::test_records::CommitPoint) {
801        if let Some(callback) = self.commit_points.borrow().as_ref() {
802            callback(point);
803        }
804    }
805}
806
807/// What records a write transaction's changes for live queries: the
808/// stream's capture, a session, or nothing.
809enum Observing {
810    Stream(stream_capture::StreamCapture),
811    Session(transaction_capture::SupplementalChanges),
812    Nothing,
813}
814
815/// A connection's policy inside one scope (`Connection::within`), which it
816/// leaves when dropped.
817struct EnteredScope<'a, P: Policy> {
818    policy: &'a P,
819    scope: P::Scope,
820}
821
822impl<P: Policy> Drop for EnteredScope<'_, P> {
823    fn drop(&mut self) {
824        self.policy.leave(&self.scope);
825    }
826}
827
828#[cfg(test)]
829#[path = "connection_tests.rs"]
830mod tests;