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
//! The storage backend a comparison renders for: [`Backend`], the three sqlx dialects that
//! implement it, and `Mongo` beside them.
//!
//! # What the three SQL rows say
//!
//! Each names the same accumulator — this crate's AND accumulator over its own dialect. A comparison
//! is one or more conjuncts joined by ` AND `, and the accumulator holds the one bit no conjunct's
//! writer holds alone: whether this conjunct is the first. A nested sub-comparison is handed exactly
//! the accumulator its parent held, which is what makes recursion legal by construction.
//!
//! # Why not the clause machine
//!
//! [`QueryBuilder`](super::sql::QueryBuilder) is a `SELECT` under construction, and naming it here
//! would pin its HOLDER to the default — a `sqlx::QueryBuilder` the statement owns. But a statement
//! inside a [`sub_select`](super::sql::QueryBuilder::sub_select) is held by the statement that
//! opened it, so the holder is a different type at every nesting depth, and a comparison could not
//! be applied inside a subquery at all. That is the relation shape: `field IN ( SELECT … )`.
//!
//! The deeper reason it was the wrong parameter is that **a comparison only ever goes `WhereClause`
//! → `WhereClause`. It never transitions.** The typestate polices clause SEQUENCE, which is the
//! statement's concern rather than a conjunct's, and the accumulator holds
//! `&'q mut sqlx::QueryBuilder<Db>` — one type at every depth.
//!
//! The clause machine stays reachable from a comparison and is not the thing threaded through it: a
//! layer that needs a subquery opens a conjunct, takes the `&mut` the accumulator yields, and wraps
//! it with [`select_into`](super::sql::QueryBuilder::select_into).
//!
//! # What the three rows refuse with
//!
//! The same refusal, and it names TWO things: a key set past the dialect's bind ceiling, and a
//! correlated comparison applied at an address naming no field. Every OTHER failure a SQL comparison
//! can have happens at the CROSSING — an operand that will not convert into the type this dialect
//! stores, a width that does not fit — and by the time a comparison exists it holds storage values
//! that binding cannot reject.
//!
//! That is why this row said [`Infallible`](core::convert::Infallible) while every kind lowered one
//! column, and why [`SqlKeyIn`](super::sql::SqlKeyIn) is what ended it: a compound key's membership
//! costs one bound parameter PER COLUMN per key, so the count that meets a sixteen-bit ceiling is
//! not one the caller passed. The `Result` on this path was already being carried for the backends
//! and the nested layers that have a no to give; the SQL family now has noes of its own.
//!
//! The second of them is what [`write_column`](Backend::write_column)'s empty-path answer does not
//! reach: a correlated predicate names a table derived from the column's path rather than the column
//! itself, so writing nothing leaves it well-formed. See
//! [`SqlLoweringError::EdgeWithoutField`](super::sql::SqlLoweringError::EdgeWithoutField).
//!
//! Three rows saying one thing is not an argument for one blanket over `Db: sqlx::Database`. What a
//! backend renders into and what it refuses with are exactly what a dialect might come to disagree
//! about, and a blanket is the shape that cannot express the disagreement. The three rows already
//! disagree about the NUMBER — see [`BindCeiling`](super::sql::BindCeiling) — and agree only about
//! the kind of no.
//!
//! # What the FOURTH row says, and it is not a fourth dialect
//!
//! `Mongo` answers every question differently, which is the point of it being here: the builder is
//! an owned BSON accumulator rather than a borrow into a `sqlx::QueryBuilder`, the refusal is
//! [`Infallible`](core::convert::Infallible), the buffer is a `String` because a rendered path
//! becomes a `bson::Document` key, and the column is a dotted PATH with nothing bracketed rather
//! than one identifier with everything bracketed. None of that needed a change to this trait, and
//! the reason is that each answer is an associated item rather than a shape the trait spells for
//! its implementors.
//!
//! The `Builder` GAT's lifetime is the one place the fit is loose. It was kept for a backend whose
//! builder holds references into the operands, and a document builder was the case named; measured,
//! a document builder holds none, because every BSON value owns its bytes. So the row below
//! resolves the slot to a type with no lifetime at all. The slot costs nothing and stays open — but
//! nothing yet has needed it.
// The rows are per dialect, so the names they use carry the dialects' gate rather than the family
// root's: a build with `sqlx` alone implements this trait for nothing and must not import a type it
// then does not name.
use At;
use ;
use ;
use Utf8BytesMut;
/// One storage backend's rendering surface: the builder its comparisons thread, the buffer a column
/// name is rendered into, and the refusal they can return.
///
/// # Why the builder type is the BACKEND's
///
/// Every comparison rendering for one backend must agree about the builder, because they hand it to
/// each other: a walk leaves one comparison and enters the next, and a nested comparison receives
/// the one its parent held. An associated type on [`ComplexComparison`](crate::ComplexComparison)
/// instead would let two comparisons for one dialect name two different builders, and nothing would
/// compose.
///
/// So the three SQL dialects share one builder — this crate's AND accumulator, parameterised by the
/// dialect — while a backend outside the SQL family brings its own.
/// The SQL rows all three name [`Utf8BytesMut`], and a bracketed identifier is why: `INLINE_CAP` is
/// 62 bytes, more than a column path spends in any declaration this crate has seen, so the whole
/// rendering sits inline where a `String` allocates for the first character written. The correlated
/// kinds take the other half of it, splitting several finished names out of one buffer.
/// The one row that is not a dialect, and the three answers it gives are each different from the
/// three above.
///
/// # The builder is OWNED, and `'q` goes unused
///
/// Every SQL row resolves the GAT to a borrow into the statement's buffer, because a statement is a
/// larger thing a conjunct writes part of. A `find` filter is not part of anything — the document
/// IS the deliverable — and every value in it owns its bytes, so the accumulator owns the whole
/// filter and has nothing to borrow from the operands. `'q` is therefore unmentioned on the right,
/// which is legal and is the measurement the seam was waiting for.
///
/// # The refusal is the ELEMENT SCOPE's, and it arrived exactly as this row said it would
///
/// This said [`Infallible`](core::convert::Infallible) while every kind rendered a field's own
/// operators: a comparison already holds storage values, chosen by the declaration and converted
/// once at the crossing, so nothing being rendered could be looked at and declined. BSON's ceilings
/// are real — sixteen megabytes to a document, a hundred levels of nesting — and they are the
/// analogue of [`BindCeiling`](super::sql::BindCeiling) rather than something a scalar's `$in` list
/// reaches: the SQL family deliberately puts no ceiling on single-column membership either, and
/// refuses only where a COMPOUND key multiplies a count the caller did not choose.
///
/// [`MongoLoweringError`](super::mongo::MongoLoweringError) is what ended it, and the shape is the
/// SQL family's own: `$elemMatch` holds a RESTRICTED sub-language, and what a nested comparison
/// writes into one is knowable only when it writes it. So the refusal belongs to the lowering for
/// the reason
/// [`SqlLoweringError::JsonElementScope`](super::sql::SqlLoweringError::JsonElementScope) does,
/// and this row names it rather than a second uninhabited type.
///
/// # The buffer is a [`String`], where the SQL rows take an inline one
///
/// A rendered path here does not go into a statement's text — it becomes a KEY, and
/// [`bson::Document`]'s keys are `String`. Any other buffer would be converted at the one place its
/// contents are used, so the inline storage the SQL rows gain would be spent again on the copy out
/// of it. The seam is what makes that statable rather than a compromise: the two families disagree
/// about the buffer for the same reason they disagree about `.` and `_`.