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
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
//! What the dialects genuinely SHARE: the leaf vocabularies more than one of them is written in,
//! and the one builder two of them render with.
//!
//! # This module stopped varying the SQL and started sharing it
//!
//! It held a [`Dialect`] trait whose methods every comparison kind dispatched through, and that
//! shape could vary the TEXT a dialect emits and nothing else — the bounds were the trait's, so they
//! were every dialect's. A capability one engine has and another does not could not be expressed at
//! all, which is how the collection kind came to lower through JSON on Postgres, a dialect with
//! native arrays: `V: PgHasArrayType` is a bound only Postgres can carry, and a trait method
//! declared once for all three had no way to ask for it.
//!
//! A lowering that differs per dialect is now a CONCRETE impl per dialect — see
//! [`SqlTextComparison`](super::SqlTextComparison), [`SqlBytesComparison`](super::SqlBytesComparison),
//! [`SqlListComparison`](super::SqlListComparison),
//! [`SqlSetComparison`](super::SqlSetComparison) and
//! [`SqlDurationComparison`](super::SqlDurationComparison) — and what stays here is what two or more
//! of those impls read from one place rather than spelling twice:
//!
//! - [`CollectionOp`] — the collection vocabulary the two dialects that store a collection as JSON
//! share.
//! - [`like_pattern`] — the escaped `LIKE` pattern Postgres and MySQL both bind, under the affix
//! [`TextMatch`] names. ONE builder for the two dialects that match with `LIKE`, rather than one
//! each: the escaping is the part that has to be right.
//! - [`QuoteIdent`], [`quote_ident`], [`quote_qualified`] and [`quote_column`] — the identifier
//! bracketing, which every dialect does and each does with its own character. Same split as the
//! pattern above: the dialect states the character, and the escaping is written once.
//! - [`ALIAS_PREFIX`] and [`quote_alias`] — the reserved namespace, and the one place a minted
//! alias becomes SQL text. The MINT itself is `ingraph-codegen`'s: an alias is a pure function of
//! a table name and a nesting depth, both known at expansion, so what reaches this crate is a
//! `&'static str` and what is left here is the bracketing every identifier goes through.
//! - [`BindCeiling`] — how many bound parameters one statement may carry, which every dialect
//! limits and each limits to its own number. The same split again, one step further out: the
//! dialect states the number, and the party that has to refuse past it is written once.
//! - [`NullOrder`] — how this dialect reaches the framework's pinned position for SQL `NULL` in an
//! ordering, which the three do in two different ways and a fourth might not do at all. The same
//! split once more: the dialect states which of the three answers it gives, and
//! [`SqlOrder`](super::SqlOrder) is the one party that renders or refuses.
//!
//! # Soundness
//!
//! One thing here becomes SQL TEXT and everything else becomes a value: [`quote_ident`] renders an
//! identifier, [`like_pattern`] builds a pattern its callers bind, and [`CollectionOp`] is a
//! vocabulary. That asymmetry is the identifier's own — a column name is not a value and no
//! placeholder stands for one — which is why the escaping in `quote_ident` is the thing that keeps a
//! name from becoming syntax. Every OPERAND still reaches the statement through a bind, exactly as
//! [`ComplexComparison::apply`](crate::ComplexComparison::apply) says.
//!
//! That split is also the one the BUFFER types follow, which is why the two look inconsistent and
//! are not: an identifier renders into [`Utf8BytesMut`] — the buffer this family's dialects name as
//! [`Backend::Buffer`](crate::Backend::Buffer), short enough to stay inline — while
//! [`like_pattern`] builds a `String` because a pattern is an operand and `String` is what binds.
use Utf8BytesMut;
use crate::;
/// The character one SQL dialect brackets an identifier with.
///
/// A CONST rather than a rendering method, because the character is the whole of what the three
/// shipped dialects differ in — `"` on SQLite and Postgres, a backtick on MySQL — while the escape
/// rule is one rule everywhere: the bracket doubles inside the brackets. So a dialect states the
/// character and [`quote_ident`] does the work, which is the same split [`like_pattern`] makes for
/// the two `LIKE` dialects and for the same reason: the escaping is the part that has to be right,
/// and a part that has to be right is written once.
///
/// It is asked for at the point ONE identifier renders, which is what keeps it from becoming the
/// dispatch surface this module's note describes: a trait that rendered whole comparisons could
/// vary only the text they emit, where a lowering that differs per dialect differs in its BOUNDS.
/// `name` bracketed for this dialect, with any bracket character inside it DOUBLED — `"col"` on
/// SQLite and Postgres, `` `col` `` on MySQL, and `a"b` becoming `"a""b"` where the bracket is `"`.
///
/// # The identifier is the one input on this path that is not bound
///
/// An operand reaches the statement through `push_bind`; a column name cannot, because an
/// identifier is not a value and no placeholder stands for one. The name IS SQL text, and the
/// doubling is what keeps it ONE identifier: a name carrying the bracket character would otherwise
/// close its own quoting, and everything after it would be SQL that nobody wrote.
///
/// It takes a [`FieldName`] for exactly that reason, and this is the seam where it matters most:
/// everything else on the path forwards a name, while this one RENDERS it. A `&str` here would
/// accept an operand — the other kind of text on the path — and quote it into the statement as a
/// column, which the doubling would keep syntactically whole and semantically wrong.
///
/// Public for the same reason [`like_pattern`] is: a dialect this crate does not ship gets the
/// escaping rather than rewriting it, and gets it by naming one character.
///
/// # A qualified reference is not a name, and it has its own function
///
/// `t.col` bracketed is `"t.col"` — one identifier that happens to contain a dot, which is what SQL
/// means by those characters. A qualified reference is two identifiers with the dot BETWEEN their
/// brackets, and nothing here can tell the two apart, because a column may legally be named `t.col`.
///
/// So the qualifier arrives as its own argument, at [`quote_qualified`], and every caller of THIS
/// function keeps passing a plain name. Splicing a dotted string at a call site is the shape that
/// would put the convention back inside a `&str`.
///
/// # What quoting does not do
///
/// It makes a name unambiguous, not legal. An identifier the engine itself refuses — one carrying a
/// NUL, one past the engine's length ceiling — is refused after this, at execution, where it is
/// loud. What this closes is the case that was silent.
/// [`quote_ident`] appended to a buffer the caller already holds, for the caller assembling several
/// names into one — every correlated form does, and an owned name per occurrence is the allocation
/// this whole path is arranged to avoid.
pub
/// The column `at` names, bracketed for this dialect and written into `out`: the segments of its
/// [`Path`] run together with `_` INSIDE one pair of brackets, each segment escaped as
/// [`quote_ident`] escapes a name.
///
/// This is what the three shipped dialects answer
/// [`Backend::write_column`](crate::Backend::write_column) with, and it is public for the reason
/// [`quote_ident`] is: a dialect this crate does not ship gets the join and the escaping rather
/// than rewriting them, and gets both by naming one character.
///
/// # The `_` is INSIDE the brackets, and the segments are escaped separately
///
/// `timebase_num` is ONE identifier that happens to hold an underscore, exactly as SQL's flat
/// namespace means it — not two names with a separator between their brackets, which is what
/// [`quote_qualified`] renders and a different reference entirely. Escaping per segment rather than
/// over the joined name is the same answer arrived at earlier: `_` is not a bracket in any dialect,
/// so it needs none, and doing it per segment is what removes the joined `String` that a name had
/// to exist in before it could be quoted.
///
/// # The EMPTY path writes NOTHING
///
/// The top level names no column, so a comparison over a COLUMN applied there has none to render.
/// Writing an empty bracketed name would be an identifier — one an engine may resolve, or may read
/// as a literal — where writing nothing leaves a predicate the engine cannot parse. A caller error
/// is better refused than resolved.
/// Every COLUMN `shapes` names, in order, each bracketed for this dialect and handed to `each`.
///
/// This is the ROW half of [`quote_column`]. That one renders the column a PREDICATE is applied at,
/// descending through the frames a comparison pushed; this one renders the columns a row's FIELDS
/// occupy, descending through the shapes their types answered with. Both reach [`push_segments`],
/// so a filter over `tb.num` and a `SELECT` of `tb_num` are one string by construction rather than
/// two rules that agree today.
///
/// The buffer is REUSED across columns rather than minted per name — a `SELECT` list over a wide row
/// is the path this family is arranged to keep allocation off, and a name per column per statement
/// is the allocation the cons list already removes one layer down.
/// # A FOLD rather than a `for_each`, and the SELECT list is why
///
/// [`QueryBuilder`](super::QueryBuilder) is a typestate that each push CONSUMES, so a caller
/// building one cannot hand a closure a borrow of it. Threading the value through is what lets the
/// same walk serve that caller and the ones that do hold a `&mut` — those pass a counter, or `()`.
pub
/// The same walk with the RENDERING left to the caller: every column `shapes` names, in order, as
/// the [`Path`] its segments make.
///
/// # It is the descent, and the two renderings of a column are what sit on top
///
/// A column is spelled two ways — BRACKETED into a statement, which is [`fold_columns`], and PLAIN
/// for a driver that answers a column by its real name, which is [`column_name`] — and the SCHEMA
/// lane needs both: a `CREATE TABLE` writes the bracketed one and a drift audit compares the plain
/// one against a catalogue. Handing the path over is what lets all of them descend ONCE. A second
/// walk beside this one would be the place a shaped blueprint's `CREATE TABLE` could name a column
/// the `SELECT` over the same row does not.
pub
/// The same walk with the LEAF'S OWN SHAPE handed over beside its path — what a caller asking a
/// question of the leaf rather than of the name needs.
///
/// There is exactly one such question today and it is the one
/// [`ColumnShape::self_nullable`] answers: a `CREATE TABLE` decides `NOT NULL` per column, and a
/// leaf's own `NULL` is the leaf's fact rather than its field's — which is why the two derived words
/// give different answers here while every structural reader sees them alike. Handing the shape over
/// is what lets that decision be made in the SAME descent every other spelling of the column is made
/// in — a second walk beside this one would be the place a declared nullability and a rendered one
/// could differ.
///
/// [`fold_paths`] is this with the shape dropped, so the two cannot descend differently.
///
/// [`ColumnShape::self_nullable`]: crate::ColumnShape::self_nullable
pub
/// The same walk started BENEATH a path already descended — what a party holding ONE field's
/// segments and that field's own path needs.
///
/// [`fold_shapes`] is this with nothing above it. A row's whole column list starts at the top and a
/// single field's starts where [`assembled`](crate::assembled) put it, and both are this one
/// descent — so a `SELECT` of `at_timebase_num` and a question asked ABOUT `at_timebase_num` cannot
/// spell it two ways.
pub
/// [`fold_shapes`]'s recursion. `under` is what has been descended through so far, and a FLATTENED
/// composite passes it along UNCHANGED — that is the whole of what dropping a field's name means
/// here, and the reason `flatten` needs no second walk.
/// The column `path` names, bracketed for this dialect, as a VALUE — [`quote_column`]'s answer for
/// a caller assembling a [`String`] of its own rather than this family's buffer.
///
/// The SCHEMA lane is that caller: it builds one `CREATE TABLE` per table as a `String` and already
/// bridges [`quote_ident`] the same way, so the alternative was a second bracketing rule beside the
/// one every statement in this family goes through.
pub
/// The segments from the ROOT down, `_` between them, each escaped — the inside of the brackets
/// [`quote_column`] pushes.
///
/// Recursive because [`Path`] is a cons list built innermost-last: reversing it into an iterator
/// would need the allocation the cons list exists to avoid, and the recursion is as deep as a
/// declaration nests.
/// The same join with NO brackets and no escaping — the name a DECODE asks the driver for.
///
/// A statement's column list is SQL text, so every name in it is bracketed and every bracket
/// character inside a segment is doubled; a decode's is an ARGUMENT, and a driver hands back the
/// column's real name. So the two are the same segments run together the same way and differ in
/// exactly the quoting, which is why they sit together: the join is one rule, and `tb_num` in a
/// `SELECT` and `tb_num` in a `try_get` cannot be spelled apart. Their agreement is pinned by
/// `crate::column::tests`.
///
/// [`Cow`], because the common case allocates NOTHING: a plain field is one segment and the name is
/// already in the [`FieldName`] the path holds. A composite's leaf is the case that has no name
/// anywhere to borrow — which is the whole point of the nested list — and it is the one that builds.
pub
/// [`column_name`]'s recursion, once the first segment has proved there is more than one.
/// `name`'s characters with this dialect's bracket DOUBLED — the part that has to be right, so it is
/// written once and every bracketing here goes through it.
/// `qualifier` and `name`, each bracketed for this dialect, with the dot BETWEEN the brackets —
/// `"t"."col"` on SQLite and Postgres, `` `t`.`col` `` on MySQL.
///
/// # Two arguments, because the two roles are not recoverable from one string
///
/// [`quote_ident`] renders ONE identifier, so `t.col` through it is `"t.col"` — a single name that
/// happens to contain a dot, which is what SQL means by those characters and which a column may
/// legally be called. The two spellings are different references and nothing about the text says
/// which was meant. Taking the qualifier separately is what records it, and it is the argument
/// [`FieldName`] makes one level down applied once more: only where a piece of text came FROM says
/// what role it is in. Each half goes through [`quote_ident`], so a qualifier carrying the bracket
/// character is doubled exactly as a bare name is.
///
/// # Who asks, and why an unqualified name there is worse than ambiguous
///
/// [`SqlEdgeComparison`](super::SqlEdgeComparison). A collection kept in an edge table is compared
/// through a correlated `EXISTS`, and the parent and the edge table carry the SAME key column names
/// — an edge row's leading columns ARE the parent's key, which is the whole of what makes it an
/// edge. SQL resolves an unqualified name to the innermost scope, so an unqualified correlation
/// compares the edge table's key to itself: well-formed, unrefused, true for every row of it, and
/// every operator quietly becomes a question about the whole table rather than about one parent's
/// collection.
///
/// Public for the reason [`quote_ident`] is: a dialect this crate does not ship gets the escaping
/// and the join rather than rewriting them.
/// [`quote_qualified`] appended to a buffer the caller already holds, for the reason
/// [`push_quoted_ident`] exists: a correlation is one of these per key column with ` AND ` between
/// them, and it is assembled rather than concatenated from owned halves.
pub
/// The framework's reserved identifier namespace: the four characters every alias this crate mints
/// begins with, and the prefix a declaration may not begin a table or column name with.
///
/// # It is short on purpose, and the shortness is arithmetic rather than taste
///
/// An alias competes for the SAME sixty-three bytes an engine keeps of an identifier as the table
/// name inside it does, so every character spent on the prefix is a character the name it stands for
/// loses before the mint's clamp starts cutting. `__ingraph` would have cost five more and
/// bought no separation this does not already have: what makes the namespace safe is that it is
/// RESERVED — `ingraph-derive` refuses a declared name beginning with it — and a reservation is not
/// made safer by being longer.
///
/// Held here as well as in `ingraph-codegen`, which is what MINTS under it, and in
/// `ingraph-derive`, which refuses declarations inside it. Three copies because the dependency edges
/// do not let one crate hold it for the others; each pair that can see both is a test.
///
/// # Why a reservation at all, rather than a name chosen to be unlikely
///
/// An alias and a real table share one namespace inside a statement, and SQL resolves a name to the
/// innermost scope that has one. A collision there does not fail: it RESOLVES, to the wrong row
/// source, and the statement runs and answers. Unlikely is not a property a query planner checks;
/// reserved is one the derive can.
pub const ALIAS_PREFIX: &str = "__ig";
/// The one place a MINTED alias becomes SQL text: `alias` bracketed for this dialect.
///
/// It takes the `&'static str` an expansion minted — see
/// [`SqlQuery::ALIASES`](crate::query::sql::SqlQuery::ALIASES) — rather than building one, which is
/// the whole of what moved when the mint went to compile time. What is left here is the part that
/// was always this module's: an alias is an identifier, so it brackets and escapes exactly as a
/// column name does.
///
/// A `&str` rather than a [`FieldName`] because that is what the array holds, and because the
/// distinction [`FieldName`] draws — a name, not an operand — is already settled for a string this
/// crate minted itself.
/// `<scope>."name"` appended to `out`, where the scope is whatever the enclosing `FROM` called the
/// row — [`At::qualifier`].
///
/// [`push_quoted_qualified`]'s twin over a qualifier that may be an ALIAS. The two are separate
/// because their left halves have different types and different provenance: one is a
/// `&'static FieldName` a schema declared, the other a `&'static str` an expansion minted, and
/// collapsing them would mean either accepting a bare `&str` where a declared name belongs — the one
/// thing [`FieldName`] exists to prevent — or viewing every minted alias as a declared name at each
/// of these call sites.
pub
/// `index` in decimal, most significant digit first.
///
/// A digit at a time because [`Utf8BytesMut`] implements no [`core::fmt::Write`], so the only other
/// way to render a number into one is through the `String` a `format!` returns — which is the
/// allocation this whole path is arranged to avoid. Recursive because the digit to be written FIRST
/// is the one reached LAST, which is the shape a path walk here already takes.
///
/// ONE rendering of a number into an alias, shared by all three families that build one — the table
/// aliases above, [`hydrate`](crate::query::sql)'s aggregated collections and `find`'s sort values —
/// so no two of them can spell one index two ways.
pub
/// How many bound parameters one SQL dialect takes in a single statement.
///
/// A CONST rather than a rendering method, for the reason [`QuoteIdent::QUOTE`] is one: the number
/// is the whole of what the dialects differ in here, while what to do at it — refuse, and say by
/// how much — is one rule everywhere. So a dialect states the number and its caller does the work.
///
/// # It is a hard edge, not a budget
///
/// All three count parameters in sixteen bits, so past the number the statement cannot be expressed
/// at all rather than merely running slowly. What sits BELOW it varies by deployment — Postgres's
/// `max_stack_depth` refuses a long row-value list well before the parameter count runs out, and
/// SQLite's own number is raisable at compile time — and a deployment's own limits belong to its
/// configuration rather than to a constant here.
///
/// # Who asks
///
/// [`SqlKeyIn`](super::SqlKeyIn), because a compound key's membership costs one bind PER COLUMN per
/// key and the caller's own count is therefore not the number that reaches the ceiling. The
/// single-column kinds deliberately do not — see [`push_in`](super::push_in).
/// Where an ordering term puts SQL `NULL`.
///
/// The two members are the whole of what SQL's `NULLS FIRST` / `NULLS LAST` says, and they are a
/// position in the RENDERED order rather than a rule: which one the framework's pinned rule needs
/// depends on which way the term runs, and [`pinned_nulls`] is where that is decided.
/// Where the framework puts SQL `NULL`, whichever dialect answers: **below every value**.
///
/// # It is a total order on the domain, not a per-direction convention
///
/// One rule — `NULL` is smaller than everything — with two spellings, `NULLS FIRST` on an ascending
/// term and `NULLS LAST` on a descending one. What that buys is the property a relay connection
/// cannot do without: reversing such a term gives exactly the other spelling of the SAME rule, so
/// the backward walk of a page is an order the same machinery already describes and the keyset
/// comparison inverts along with it.
///
/// A convention pinned per direction — `NULLS LAST` whichever way the term runs, which is what a
/// reader reaching for "nulls at the end" would write — does not survive the inversion: its reverse
/// is `NULLS FIRST`, a different order from the one the forward page used, so the two directions of
/// one connection disagree about where the nulls are and a client walking back across a null
/// boundary skips or repeats exactly the rows on it.
///
/// # It is also the position two of the three dialects already hold
///
/// Measured, on SQLite 3.51.0, PostgreSQL 16.14 and 17.10, and MySQL 8.4.11 — see [`NullOrder`] for
/// the table and for what each dialect has to spell to reach this one.
pub const
/// How one SQL dialect reaches [`pinned_nulls`].
///
/// A CONST rather than a rendering method, for the reason [`QuoteIdent::QUOTE`] and
/// [`BindCeiling::MAX_BIND_PARAMETERS`] are: the answer is the whole of what the dialects differ in,
/// while what to do with it — render nothing, render the clause, or refuse — is one rule everywhere.
///
/// # The measurement
///
/// | dialect | default on `ASC` | default on `DESC` | `NULLS FIRST` / `NULLS LAST` | answer |
/// |---|---|---|---|---|
/// | SQLite 3.51.0 | first | last | yes, since 3.30 | [`Implicit`](NullOrdering::Implicit) |
/// | MySQL 8.4.11 | first | last | **no** — `ERROR 1064`, a syntax error | [`Implicit`](NullOrdering::Implicit) |
/// | PostgreSQL 16.14, 17.10 | last | first | yes | [`Explicit`](NullOrdering::Explicit) |
///
/// # Why the pin is the position two dialects already have, and not Postgres's
///
/// It is the only pinning every shipped dialect can express. Under the other one — `NULL` above
/// every value, which is Postgres's own default — MySQL can express nothing: it has no clause, so
/// the position would have to be reached by an `IS NULL` PREFIX TERM (`ORDER BY (a IS NULL), a`),
/// and that is not a modifier on the term but an EXTRA TERM. It is a column the keyset expansion's
/// own list does not contain, so the ordering and the comparison would be over two different
/// tuples; it is a derived expression, so no index over the column serves the order; and it is
/// invisible in the cursor, so nothing would notice the disagreement. Measured to answer correctly
/// on MySQL 8.4.11 — the SQL works, and it is the wrong shape for this seam.
///
/// The pin chosen instead costs SQLite and MySQL nothing at all: their ordering terms render
/// exactly as they did, and an index over the bare column still serves them. Postgres states the
/// clause, which is a modifier on the term rather than a term of its own — so the tuple the
/// ordering runs over is still the tuple the cursor holds.
/// The three answers a dialect can give about [`pinned_nulls`].
///
/// # The third is not decoration
///
/// A dialect whose default disagrees and which has no clause can express the framework's position
/// only through a derived ordering term, which is the shape [`NullOrder`]'s note refuses. Such a
/// dialect gets a REFUSAL for an order with a nullable column — see
/// [`SqlOrderError`](super::SqlOrderError) — and keeps working for every order without one, which is
/// the honest granularity: what it cannot express is a position for `NULL`, and an order with no
/// nullable column has no `NULL` to position.
///
/// Refusing is what makes the pin mean anything. Falling back to the dialect's own default would
/// serve a page ordered one way against a cursor comparing the other, which skips or repeats exactly
/// the rows at the null boundary and reports nothing.
/// Measured on SQLite 3.51.0: `NULL` leads an ascending term and trails a descending one, which is
/// the framework's own position, so a term states nothing. `NULLS FIRST` / `NULLS LAST` exist since
/// 3.30 and are not needed here.
/// Measured on PostgreSQL 16.14 and 17.10: `NULL` TRAILS an ascending term and leads a descending
/// one — the opposite of the framework's position, and the one dialect of the three that differs. It
/// has the clause, so the position is stated on the term.
///
/// The cost is an INDEX one and belongs to DDL rather than here: a default btree index is built
/// `NULLS LAST` on ascending, so an ordering that asks for `NULLS FIRST` is served by an index
/// declared to match. Nothing in this crate emits DDL, and the alternative — following the dialect
/// rather than the framework — is the disagreement between the ordering and the cursor that
/// [`NullOrdering::Inexpressible`] exists to refuse rather than to hide.
/// Measured on MySQL 8.4.11: `NULL` leads an ascending term and trails a descending one, which is
/// the framework's own position — so a term states nothing, which is fortunate, because
/// `NULLS LAST` there is `ERROR 1064` and not a clause at all.
/// A collection-column operation, in the vocabulary the JSON-storing dialects share.
///
/// The two equalities are separate members rather than one under a flag its caller passes. They ask
/// different questions of the same column — [`SequenceEq`](CollectionOp::SequenceEq) compares the
/// stored collections directly, [`SetEq`](CollectionOp::SetEq) tests mutual containment — and
/// rendering the first for a set is a silent WRONG ANSWER, since a set's stored element order
/// depends on insertion. Which one a lowering asks for is settled by the comparison KIND it is
/// walking, so a `bool` argument here would be a second place for the same fact to be stated and the
/// only place it could be stated wrongly.
///
/// There is no ordering member, and that is the vocabulary being honest about its two dialects:
/// SQLite stores a collection as JSON text and MySQL as a `JSON` value, and neither has the
/// element-wise `<` a collection ordering means. Postgres does, through native arrays, and it does
/// not render through this enum — see
/// [`SqlListComparison`](super::SqlListComparison)'s Postgres impl.
/// The Rust-built `LIKE` pattern: the operand's `\`, `%` and `_` escaped so they match literally
/// under `ESCAPE '\'`, then wrapped with the wildcard the affix needs — `%v%` (contains), `v%`
/// (prefix), `%v` (suffix).
///
/// ONE builder for the two dialects that match with `LIKE`, rather than one each, and the reason it
/// is shared rather than duplicated is that the escaping is the part that has to be right: an
/// unescaped `%` turns `contains: "50%"` into a match on everything beginning `50`, which is a wrong
/// result set reported as a right one.
///
/// Public, so a dialect this crate does not ship gets the escaping rather than rewriting it. It is
/// the one thing a fourth `LIKE` dialect can take from the three shipped here; the twelve slot walks
/// and the impls that bind them are its own to write, which is the trade the concrete-impl split
/// makes.
///
/// The pattern BINDS as a value and never appears in the rendered SQL, so a differential over the
/// text cannot see it going wrong. `dialect::tests` asserts it directly for that reason.