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
//! The SQL family's two [`AsyncGather`]s — one statement each, and the surface they run it on is the
//! whole difference.
//!
//! [`SqlGather`] borrows a CONNECTION the caller already opened and answers the upstream's RECORDS.
//! [`SqlPooledGather`] takes a POOL and answers the ROWS. Neither is a preference: each of the two
//! differences is forced by a measurement, and both are written on the type that carries them.
use PhantomData;
use AsyncGather;
use crate::;
/// The system of record, as a retrieve reaches it: one connection, one row type, one dialect.
///
/// # What it composes, and why none of it is new
///
/// One call is one statement — `WHERE ("id") IN ((?), …) AND <the client's filter>` — assembled by
/// [`gathered`](crate::query::sql::gathered) out of two pieces the SQL family already had. The keys
/// half is [`SqlQuery::addresses`], the ROW-VALUE membership that
/// [`SqlKeyIn`](crate::comparison::sql::SqlKeyIn) exists to keep away from the per-column `IN`
/// spelling and its cartesian product. The filter half is the record's own comparison, lowered
/// exactly as the list lane lowers it. The rows cross back into records through the declared
/// conversions, which is the same read leg every other query uses.
///
/// So the only thing this type adds is the CORRELATION, and it adds it because a membership names a
/// set: the plan answers in whatever sequence it chose, and the retrieve's order is the engine's.
///
/// # A CONNECTION rather than a pool, and the fill loop is why
///
/// A page may take several batches, and they belong in one read — a pool handing each batch its own
/// connection would let a page span two states of the database. The caller opens whatever bracket
/// the page wants (`BEGIN`, a snapshot, nothing) and lends the connection for the whole loop.
///
/// # `PhantomData<fn() -> (Row, Db)>`
///
/// This crate's convention for every marker parameter: the function pointer contributes no
/// auto-trait obligation and no variance, so the type is `Send`/`Sync` on the borrow alone.
/// # The key becomes an ID through [`Identifiable`], which every emitted key answers
///
/// A retrieve deduped at the KEY grain, and a row is addressed by its ID — one column, `UNIQUE` by
/// the schema's own law. `K: Identifiable` is what crosses between them, and it is not a bound
/// invented here: a derived index's binding already reads its id off the carried key exactly this
/// way, so every key that can be retrieved can be addressed.
///
/// # What this impl asks of the ID, and why each is its own
///
/// `Clone` builds the batch's id list; `PartialEq` lines the answered rows back up against it.
/// Neither is [`Identifiable::Id`]'s business — the member is unbounded there on purpose — so both
/// are named HERE, at the backend that spends them, which is the same discipline every other
/// engine-side impl in this crate follows.
/// The system of record as a RESOLVER reaches it: one pool, one row type, one dialect — and the
/// ROWS themselves, which is the one thing a wire face can cross.
///
/// # `&Pool` rather than a borrowed connection, and `Send` is what decides it
///
/// `ingraph/tests/wire_trio.rs` put five shapes to the compiler, and every one that reached a
/// borrowed `Db::Connection` inside a resolver failed identically — *implementation of
/// `sqlx::Acquire` is not general enough* — while the same call awaited from an ordinary test
/// compiled and ran. So [`SqlGather`] is not mountable on a wire face at all, whatever its body
/// does: async-graphql bounds every resolver future `Send`, and sqlx's
/// `Acquire<'c> for &'c mut Connection` is then asked for at two independent lifetimes, which no
/// impl answers. `&Pool<Db>` is `Acquire` and is `Send` by construction, the pool being `Sync` and
/// shared rather than uniquely borrowed — the same measurement [`SqlDoor`](crate::SqlDoor) is built
/// around, spent one layer down.
///
/// # The connection is ACQUIRED ONCE AND HELD, which is what keeps the sibling's invariant
///
/// A page may take several batches, and a pool handing each of them its own connection would let one
/// page span two states of the database — [`SqlGather`]'s own reason for taking a connection, and it
/// does not stop being true because the construction surface moved. So the pool is what a caller
/// hands over and the connection is still ONE per gather value: the first
/// [`gather`](AsyncGather::gather) acquires, every batch after it spends the same one, and the fill loop
/// runs inside a single read.
///
/// LAZILY, and that is the departure from acquiring in [`new`](Self::new): a page can end without
/// asking anything — `first: 0`, an engine that answered nothing, a floor that cut the stream to
/// empty — and a connection taken for one of those is a connection held out of the pool for a
/// question nobody asked. Constructing therefore costs nothing and the first batch pays.
///
/// # It answers ROWS where [`SqlGather`] answers RECORDS, and the WIRE forces it
///
/// There is no `Record → Output` crossing anywhere in the tree, and that is a measurement rather
/// than an omission: `emit::graphql`'s `row_crossings` writes the wire object's ONLY constructor as
/// `TryFrom<<Record as Record<Db>>::Row>`, off the stored row, and the record resolver's own
/// `wire_crossing` spends exactly that one. A gather answering RECORDS therefore hands a wire face a
/// value it cannot render. The ROW is the fork point both crossings hang off — [`SqlQuery::record`]
/// for the domain entity, `TryFrom<Row>` for the wire object — so answering it is what keeps ONE
/// gather serving both, and the caller spends whichever crossing its own answer needs.
///
/// The two impls cannot be one type: `Row` and `<Row as SqlQuery<Db>>::Record` are not provably
/// distinct, so `AsyncGather<K, Row>` and `AsyncGather<K, Row::Record>` on one type is `E0119`.
///
/// # R2's SWEEP TOUCHES TWO LINES OF WHAT MOUNTS THIS
///
/// The resource re-axis re-keys the resolver's `ctx.data::<SqlDoor<Db>>()` line and the citizen
/// registration that installed it. Nothing in this type moves: it takes a `&Pool<Db>` from whoever
/// holds one, and which citizen that is is the caller's fact.
///
/// # `PhantomData<fn() -> (Row, Db)>`
///
/// This crate's convention for every marker parameter: the function pointer contributes no
/// auto-trait obligation and no variance, so the type's `Send`/`Sync` rest on the pool borrow and
/// the held connection alone — which is the whole point of it.
/// The bounds are [`SqlGather`]'s, unchanged, and its own note carries what each one is for: `K`
/// crosses to an address through [`Identifiable`], and the id's `Clone` and `PartialEq` are named
/// here because they are this backend's to spend rather than [`Identifiable::Id`]'s to promise.
///
/// One `Id` VALUE and not one id COLUMN: a compound address rides
/// [`SqlQuery::addresses`] into the row-value membership, which is the spelling
/// [`SqlKeyIn`](crate::comparison::sql::SqlKeyIn) exists to keep the per-column `IN` — and its
/// cartesian product — away from.