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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
//! The EXECUTION lane: a [`Database`] handle in, records out — and records in, documents stored —
//! with no glue in between.
//!
//! # The handle is the `Acquire` analog, and there is nothing to acquire
//!
//! A SQL lane takes an [`Acquire`](sqlx::Acquire) and opens ONE connection per call, because
//! connection-level consistency is what a several-statement call needs. This lane takes a
//! [`Database`] and opens nothing: the driver owns a pool behind the handle, a package is ONE
//! command, and a caller who needs several commands to see one state passes a
//! [`ClientSession`] — which is the driver's own type and is passed through rather than wrapped.
//!
//! # …and it is why the WRITE verbs open no transaction either
//!
//! The SQL write lane brackets its statements because a record spanning several tables is several
//! statements, and [`BeginWrite`](crate::query::sql::BeginWrite) is where the passthrough rule lives.
//! A record is ONE DOCUMENT here, so every verb is one command and one command is atomic by the
//! server's own law — see [`write`](super::write)'s note for the three sections of the SQL register
//! that fact deletes. What is left is exactly the read half's answer: the bracket is a session the
//! CALLER already has, and the `_in` twins take one.
//!
//! # There is no `MongoOptions` on a write, and the absence is the same discipline
//!
//! That type holds the READ CONCERN and nothing else, derived from what a package reads — a question
//! a write does not ask, having no result set to be consistent about. Its write-side counterpart is
//! the write concern, which this lane deliberately says nothing about: *[`None`] is not no concern —
//! it is say nothing*, so the concern a deployment configured on its own `Client` or `Database`
//! handle stands. A lane that wrote one there would silently override a deployment's own durability
//! setting, which is the decision [`MongoOptions::concern`](super::MongoOptions) already refuses to
//! make on a caller's behalf. The SQL write lane takes no options either, for the same reason read
//! one way round: nothing about how a write runs is the framework's to choose.
//!
//! That is why there is no `find_mongo_snapshot` twin of the SQL family's. A snapshot there is a
//! transaction the framework begins on the caller's behalf, because sqlx has no other seam; here
//! the seam is a session the caller already has, and a framework-begun transaction would be a
//! second one nobody asked for. The consistency the framework DOES supply on its own is the read
//! concern — see [`MongoOptions`], where the policy is derived from what the package reads.
//!
//! # The SERVER FLOOR is 5.0
//!
//! Two things put it there, and only one of them is this lane's choice:
//!
//! - **`snapshot` outside a transaction**, which is what a multi-collection package runs at, is a
//! 5.0 feature. Below it the server refuses the command.
//! - **`$alwaysFalse`**, which is what a page whose cursor nothing follows renders, is 5.0 as well.
//!
//! A deployment below that floor can still use the whole lower layer — building a package needs no
//! server at all — and can run one by overriding the concern. What it cannot get is the empty page,
//! which is a predicate rather than a policy. Recorded here because a floor discovered by a
//! deployment is a floor nobody documented.
//!
//! # What is measured here, and what is not
//!
//! Nothing in this file is measured against a live server by this repository's own test matrix,
//! and that is a MEASUREMENT rather than an omission: `ci/test-matrix.sh` runs `cargo` lanes and
//! provisions no service — the SQL family's own engine walks were run by hand and their results
//! recorded in prose, and there is no live SQLite, Postgres, MySQL or mongod in the matrix either.
//! So the lane's unit surface is tested against the PACKAGE — which is a value, and the whole of
//! what this file turns into a command — and the walk this lane inherits is
//! [`MongoKeyset`](super::MongoKeyset)'s.
//!
//! The write half is the same posture and the same reason: what each verb DECIDES is the document it
//! sends, so [`write`](super::write)'s own tests assert on those documents and this file adds no
//! second reading of them. The two rows a live walk owes there are the server's rather than this
//! lane's — a second `insert` at a stored `_id` refused with duplicate-key `11000`, and a
//! `replace_one` with `upsert: true` at that same address not refused.
//!
//! The two facts a live walk still owes on the read side, both named at that module: MongoDB's
//! comparison operators do not cross BSON types, and a missing field reads as `null` to both `$sort`
//! and `$eq`. Every other row of the page's table is the SQL family's, already walked against four
//! engines.
use Document;
use ;
use ;
use crate::;
/// The options one package runs under: the concern the policy chose, and nothing else.
///
/// Built per call rather than held, because the only field it carries is derived from the package —
/// a value held across calls would be the policy of whichever package built it.
/// Every document `package` returns, extracted into the row type but not yet crossed back into
/// records.
///
/// # It is the PRIMITIVE, and the two verbs below are one line each on top of it
///
/// A page mints its cursors from the ROW — [`MongoOrdering::value`](super::MongoOrdering::value)
/// reads the document's own field — so the row is what a page assembler needs and the record is
/// what a caller wants. Handing back the row here is what keeps the page lane, when it lands, from
/// having to re-run the extraction or to reach past this function.
///
/// # Errors
///
/// The driver's own refusal, or a document that is not a row — named by field.
pub async
/// [`documents`], inside `session` — so several calls see one state of the database.
///
/// The session is the DRIVER's type and is passed through untouched: this lane begins nothing,
/// commits nothing and holds nothing, so a caller's transaction, causal-consistency settings and
/// cluster time are theirs throughout. A wrapper would be a second vocabulary for a thing the
/// driver already names, and would have to be unwrapped by every caller who wanted the rest of the
/// driver's session API.
///
/// # Errors
///
/// As [`documents`].
pub async
/// Every record `package` returns.
///
/// # Errors
///
/// As [`documents`], plus a row that will not cross back into its record.
pub async
/// [`find`], inside `session`.
///
/// # Errors
///
/// As [`find`].
pub async
/// The record at `id`, or [`None`] where no document lives there.
///
/// # The miss is UNIFORM
///
/// An absent document is `Ok(None)` on every path, always — the rule
/// [`query::sql::get`](crate::query::sql::get) states and the wound it is the scar of: a codebase
/// that answers null on one path, an error on another and a logged error on a third makes *not
/// found* a fact about the resolver rather than about the data.
///
/// # It builds its own package
///
/// The other verbs take one because a filter, an order and a page are the caller's; an address is
/// not — it is `{_id: …}` and nothing else — so a caller handing one in could only get it wrong.
///
/// # Errors
///
/// As [`find`], plus an id that will not cross into this database's stored value.
pub async
/// [`get`], inside `session`.
///
/// # Errors
///
/// As [`get`].
pub async
/// The predicate a `delete_where` over `Row` takes, read off the RECORD's own vocabulary binding.
///
/// The same projection the read lane's `.filter(…)` takes — so a caller checks a predicate with
/// [`find`] and removes with the same value, rather than writing a second one that agrees today.
type RowComparison<Row> = Comparison;
/// Store `record` as a NEW document.
///
/// # The refusal is the SERVER's, surfaced rather than read
///
/// An `_id` that already holds a document is a duplicate-key error — code `11000` — and it arrives as
/// [`MongoWriteError::Driver`] carrying whatever the server said. It is not translated into a *this
/// already exists* of the framework's own, for [`query::sql::insert`](crate::query::sql::insert)'s
/// reason: a collection may carry unique indexes the address does not name, so a lane that reported
/// all of them as one thing would tell a caller the wrong story about most of them. A caller that
/// means *store this whatever was there* has [`upsert`] and does not have to read an error to get it.
///
/// # It opens no transaction, and there is nothing for one to hold
///
/// One record is one document is one command, which is atomic by the server's own law — see
/// [`write`](super::write)'s note for the three sections of the SQL register that fact deletes. A
/// caller who wants several writes to see one state uses [`insert_in`].
///
/// # Errors
///
/// A record that will not cross into this database's document, or the driver's own refusal.
pub async
/// [`insert`], inside `session`.
///
/// The session is the DRIVER's type and is passed through untouched, exactly as
/// [`documents_in`]'s is: this lane begins nothing, commits nothing and holds nothing, so a caller's
/// transaction is theirs throughout. It is also the ONLY way several writes are bracketed together
/// here — the framework opens no transaction of its own, there being one command per verb.
///
/// # Errors
///
/// As [`insert`].
pub async
/// Store `record` at its address, REPLACING whatever was there.
///
/// # The replacement is TOTAL, and that is the cascade on this backend
///
/// `replaceOne` with `upsert: true` replaces the whole document, and a document's embedded arrays are
/// part of it — so every collection this record holds is replaced as a SET by the same command that
/// writes the scalars, with no second statement and no bracket. The SQL lane needs both because a
/// collection is a second TABLE there; here there is nothing between the two halves for a failure to
/// land in.
///
/// # What it does NOT do is merge
///
/// A collection that arrives shorter comes back shorter, and a field the crossed document does not
/// carry is a field the stored document no longer has. That is what *replace* means and it is the
/// honest reading of a record: the value handed over is the whole of it.
///
/// # Errors
///
/// As [`insert`], plus an id that will not cross into this database's stored value.
pub async
/// [`upsert`], inside `session`.
///
/// # Errors
///
/// As [`upsert`].
pub async
/// Remove the record at `id` — `true` where a document was there.
///
/// The id is the whole address, exactly as it is for [`get`]: `_id` is unique by the server's own
/// construction, so it names at most one document and the answer is a yes-or-no rather than a count.
/// That is the same narrowing `get` makes when it answers with an [`Option`] where [`find`] answers
/// with a [`Vec`] — one law, read on the write side.
///
/// # Everything stored FOR the record goes with it, and no statement says so
///
/// A record is one document here, embedded arrays included, so *the collections go with the row* is
/// what removing the document already means. The SQL lane spends a statement per collection and per
/// provenance table for the same effect, and its note says why it does not leave the work to
/// `ON DELETE CASCADE`; there is nothing here to leave to anybody.
///
/// # A miss is `Ok(false)` and never an error
///
/// [`get`]'s uniform-miss rule, one verb over: an address that holds nothing is a fact about the
/// database rather than a failure of the call.
///
/// # Errors
///
/// An id that will not cross into this database's stored type, or the driver's own refusal.
pub async
/// [`delete`], inside `session`.
///
/// # Errors
///
/// As [`delete`].
pub async
/// Remove every record `filter` names — answering with how many went.
///
/// This is the RE-INDEX road, and it is the reason the write half could not be spelled with the other
/// three verbs: a source that produced fourteen documents and now produces nine leaves five behind,
/// and *what the source used to produce* is not a set anybody holds. What a caller has is the
/// predicate those documents are under, so the verb takes the predicate.
///
/// The comparison is the RECORD's own, read off the vocabulary binding exactly as the read lane's
/// `.filter(…)` reads it — so a caller checks a predicate with [`find`] and removes with the same
/// value.
///
/// # There is no filterless form, and the empty one is refused TWICE
///
/// The filter is a required parameter, and one that lowers to `{}` is refused with
/// [`MongoWriteError::Unscoped`] before anything runs. Both tiers are
/// [`removal_where`](super::removal_where)'s; the second exists because the first cannot close it.
///
/// # Errors
///
/// [`MongoWriteError::Unscoped`] for a filter naming no document, [`MongoWriteError::Joined`] for one
/// that needs a `$lookup`, a lowering refusal carried verbatim, or the driver's own refusal.
pub async
/// [`delete_where`], inside `session`.
///
/// # Errors
///
/// As [`delete_where`].
pub async
/// The driver's handle on the collection an address names.
///
/// One function, so the eight write verbs above name a collection exactly the way the read verbs
/// name one — `database.collection::<Document>(…)` off the address's own table — and a second
/// spelling cannot send one verb somewhere else.
/// Every row of `cursor`, extracted.
///
/// The cursor is walked with [`advance`](Cursor::advance) and read through
/// [`deserialize_current`](Cursor::deserialize_current) rather than as a `Stream`, which is what
/// keeps `futures` out of this crate's graph: the driver's own iteration is enough for a bounded
/// result set, and every result set here is bounded by the package's `$limit`.
async
/// [`extract`], for the cursor a session's aggregation returns — which needs the session at every
/// step, since the batches it fetches ride it.
async
/// Every row back into its record — the crossing, which is the declaration's own conversions.