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
//! THE READ DOOR: where an emitted resolver's engine call gets the connection it runs on.
//!
//! ```text
//! Schema::build(root, …).data(SqlDoor::pooled(pool)) // the application, once
//! │
//! ▼
//! ctx.data::<SqlDoor<Sqlite>>()? → door.pool() → Reel::find_sqlite(pool)… // every resolver
//! ```
//!
//! # It exists because of a MEASUREMENT, and the measurement is `Send`'s rather than async-graphql's
//!
//! `ingraph/tests/wire_trio.rs` put five shapes to the compiler and every one of them that reached a
//! borrowed CONNECTION failed the same way — *implementation of `sqlx::Acquire` is not general
//! enough* — inside a resolver, behind a free `async fn`, with owned arguments, and boxed. The
//! identical calls awaited from an ordinary test compile and run. What refuses is the `Send` bound
//! async-graphql demands of every resolver future: sqlx implements `Acquire<'c>` for
//! `&'c mut Connection`, and a `Send`-bounded future asks for that at two independent lifetimes,
//! which no impl answers.
//!
//! `&Pool<Db>` is the surface that passes — it is `Acquire` and it is `Send` by construction, the
//! pool being `Sync` and shared rather than uniquely borrowed. So the door's whole job is to hand a
//! resolver one of those, and everything else about it follows from that one fact.
//!
//! # The seam is [`SqlSource`] and the KEY is [`SqlDoor`], and the split is what `ctx.data` forces
//!
//! `Context::data::<T>` is keyed on a CONCRETE type — it is a `TypeId` lookup — so an emitted
//! resolver has to name one. A trait cannot be that name, and an emitted unit cannot be generic over
//! the application's own provider either: the unit is what
//! [`Graphql::Query`](crate::Graphql::Query) binds, and a binding is a type rather than a family.
//!
//! So the type a resolver looks up is this crate's, parameterised by the DATABASE — which the
//! emission knows, the record's own `persist(…)` block having named it — and the OPENNESS lives
//! inside it: a `SqlDoor<Db>` holds any [`SqlSource<Db>`] an application wrote. The shipped provider
//! is `sqlx::Pool<Db>` itself, through the blanket impl below, and that is what
//! [`pooled`](SqlDoor::pooled) mints.
//!
//! # ONE DOOR PER STORE TYPE, and the keying is what makes several stores legal
//!
//! `SqlDoor<Sqlite>` and `SqlDoor<Postgres>` are two types, so a schema serving records from two
//! databases installs two doors and every resolver reaches the one its own record is stored in. No
//! registry, no name, and no way for a record to read the wrong store: the parameter IS the routing.
//!
//! # The RUNTIME stays the application's
//!
//! `ingraph` enables no `runtime-*` feature of sqlx — picking a runtime is an application's act —
//! so this module compiles the pool's TYPE and never builds one. An application serving GraphQL
//! already has a runtime and already enables that feature; `Pool::connect` panics without it, which
//! is sqlx's own answer and not this crate's to intercept. This crate's own end-to-end test enables
//! it as a DEV-dependency feature, which is the same posture one tier down.
use Arc;
/// WHERE a read runs — the seam an application answers with its own pool.
///
/// # Object-safe on purpose, and the return type is the measurement
///
/// `&Pool<Db>` rather than an associated `Acquire` surface, and the reason is the module note's
/// measurement rather than a simplification: inside a `Send` resolver future, the pool borrow is the
/// only surface sqlx's `Acquire` answers for. An associated type would have widened the seam to
/// forms that cannot be spent at the one position the seam exists for — and it would have cost the
/// object safety this trait's whole purpose rests on, `ctx.data` being a lookup on a concrete type.
///
/// What the seam DOES open is who owns the pool and how it is reached: an application holding its
/// pool inside a larger handle, behind its own accessor, or beside a tenant's routing table
/// implements this for that type and hands it to [`SqlDoor::new`]. The shipped provider is the pool
/// itself.
/// The SHIPPED provider: a pool is its own source.
///
/// A blanket over the concrete pool rather than a wrapper type, so `SqlDoor::pooled(pool)` stores
/// what the application already holds and no second handle exists to go out of step with it.
/// The DOOR a resolver takes from a request's context — one per database a schema serves.
///
/// Cloneable and cheap: the source is behind an [`Arc`], as `sqlx::Pool` is internally, so
/// installing a door costs a refcount rather than a connection.
/// Written out rather than derived, for the reason every `Db`-parameterised type in this crate
/// writes its own: a derive would bound `Db: Clone`, which a database marker never is and never
/// needs to be — what is cloned is the handle inside.
/// Written out because a trait object carries no [`Debug`](core::fmt::Debug), and the pool behind it
/// is a connection manager rather than a value worth printing. What a reader wants from this line is
/// WHICH door it is, which the database's own name answers.