dray 0.0.0__tar.gz → 0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- dray-0.1/LICENSE +21 -0
- dray-0.1/PKG-INFO +438 -0
- dray-0.1/README.md +410 -0
- dray-0.1/pyproject.toml +54 -0
- dray-0.1/pyproject.toml.orig +83 -0
- dray-0.1/src/dray/__init__.py +107 -0
- dray-0.1/src/dray/caching.py +421 -0
- dray-0.1/src/dray/child.py +930 -0
- dray-0.1/src/dray/collection.py +3444 -0
- dray-0.1/src/dray/handlers.py +76 -0
- dray-0.1/src/dray/hooks.py +530 -0
- dray-0.1/src/dray/model.py +2699 -0
- dray-0.1/src/dray/py.typed +0 -0
- dray-0.1/src/dray/schema.py +462 -0
- dray-0.1/src/dray/store.py +1880 -0
- dray-0.1/src/dray/watching.py +505 -0
- dray-0.0.0/PKG-INFO +0 -12
- dray-0.0.0/README.md +0 -3
- dray-0.0.0/pyproject.toml +0 -16
- dray-0.0.0/pyproject.toml.orig +0 -14
- dray-0.0.0/src/dray/__init__.py +0 -1
dray-0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rodney Haywood
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
dray-0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dray
|
|
3
|
+
Version: 0.1
|
|
4
|
+
Summary: A Python record layer for Amazon Aurora DSQL
|
|
5
|
+
Author: Rodos
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
13
|
+
Classifier: Topic :: Database
|
|
14
|
+
Classifier: Topic :: Database :: Front-Ends
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Dist: psycopg>=3.3.4
|
|
18
|
+
Requires-Dist: cachetools>=5.3
|
|
19
|
+
Requires-Dist: aurora-dsql-python-connector[psycopg]>=0.2.7,<0.3 ; extra == 'dsql'
|
|
20
|
+
Requires-Dist: psycopg-pool>=3.3.1 ; extra == 'dsql'
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Project-URL: Homepage, https://github.com/draylabs/dray
|
|
23
|
+
Project-URL: Documentation, https://github.com/draylabs/dray/blob/main/docs/manual.md
|
|
24
|
+
Project-URL: Source, https://github.com/draylabs/dray
|
|
25
|
+
Project-URL: Issues, https://github.com/draylabs/dray/issues
|
|
26
|
+
Provides-Extra: dsql
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# dray
|
|
30
|
+
|
|
31
|
+
**A Python record layer for Amazon Aurora DSQL.**
|
|
32
|
+
|
|
33
|
+
dray is built out of what DSQL doesn't have. No foreign keys, no savepoints, no
|
|
34
|
+
locking, three thousand rows to a transaction. The limits are the design rather
|
|
35
|
+
than obstacles to route around.
|
|
36
|
+
|
|
37
|
+
You can already run SQLAlchemy or Django against DSQL — AWS ships adapters for
|
|
38
|
+
both — but you spend the time talking them out of foreign keys, pessimistic
|
|
39
|
+
locking and heap storage. dray assumes none of those to begin with.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
uv add dray # or: pip install dray
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Python 3.12 or newer. `Store.connect` authenticates against a cluster and so
|
|
48
|
+
needs AWS's own connector, which is an extra:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
uv add "dray[dsql]"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A store handed a connection you already have needs none of that — psycopg is
|
|
55
|
+
the driver underneath either way, and the connector installs no driver of its
|
|
56
|
+
own.
|
|
57
|
+
|
|
58
|
+
**dray is not at 1.0.** 0.1 is the first release meant to be depended on, and
|
|
59
|
+
a version before 1.0 may still change what a call does. [The manual][manual] is
|
|
60
|
+
the promise; anything not on that page is not one yet.
|
|
61
|
+
|
|
62
|
+
The smallest thing that works:
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from dray import Store, record
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@record(table="person", collection="people")
|
|
69
|
+
class Person:
|
|
70
|
+
family_name: str
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
store = Store.connect(host="ab12cd.dsql.ap-southeast-2.on.aws")
|
|
74
|
+
store.create(Person) # the table it implies, once
|
|
75
|
+
|
|
76
|
+
person = store.people.add(Person(family_name="Hemingway"))
|
|
77
|
+
print(store.people.by_id(person.id).family_name)
|
|
78
|
+
# Hemingway
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
With dray you get:
|
|
82
|
+
|
|
83
|
+
- **DSQL's limits handled for you.** A transaction there holds 3,000 rows, so a
|
|
84
|
+
big write is split to fit; a commit it refuses under contention is replayed
|
|
85
|
+
rather than raised at you; and a delete reaches the records underneath.
|
|
86
|
+
- **Records that are plain dataclasses**, declared with a decorator. No base
|
|
87
|
+
class, no metaclass, and no connection — you can build one, hand it to a
|
|
88
|
+
function and test it with the database nowhere in sight.
|
|
89
|
+
- **A column or a JSON document, decided per field.** Give a field its own
|
|
90
|
+
column, or keep it in a `jsonb` document beside the others — adding one of
|
|
91
|
+
those is a write rather than a migration, and a filter is written the same
|
|
92
|
+
way either side.
|
|
93
|
+
- **Somewhere for your queries to live.** A collection is a class you own, with
|
|
94
|
+
`find` for matching on values and SQL you wrote for everything else. Both
|
|
95
|
+
hand back records rather than rows.
|
|
96
|
+
- **A read cache, per record, off until you ask for it.** Put `cached_for=10`
|
|
97
|
+
on a record and reading the same one again comes out of memory instead of
|
|
98
|
+
the database. Other reads fill that cache too, a write drops what it
|
|
99
|
+
changed, and nothing lives long enough to go far wrong.
|
|
100
|
+
- **Made to be used from many threads.** A store each out of a pool and
|
|
101
|
+
one cache between them, so a page wanting six answers asks for all six at
|
|
102
|
+
once and costs the longest rather than the sum — then reads on sequentially,
|
|
103
|
+
out of the cache they filled.
|
|
104
|
+
- **Sub-records that travel with their parent.** Notes on a person, lines in an
|
|
105
|
+
order: queued up, written in the same transaction as the change they explain,
|
|
106
|
+
and deleted when it is. As DSQL does not have foreign keys, dray does it for
|
|
107
|
+
you.
|
|
108
|
+
- **Business rules that live on the field, not at the call site.** What a value
|
|
109
|
+
will accept, what it tidies on the way in, what to fill in on a write, and
|
|
110
|
+
what to run when it changes. Said once on the class and applied at every door
|
|
111
|
+
a value arrives through — a constructor, a form, an importer, a filter — so
|
|
112
|
+
there is no route into your data that quietly goes around them, and nobody
|
|
113
|
+
has to remember to call anything.
|
|
114
|
+
- **Optimistic concurrency, already wired up.** Two people open the same record
|
|
115
|
+
and both save it: the first one lands, and the second is told rather than
|
|
116
|
+
quietly painting over it. Every record carries an `etag` dray mints and
|
|
117
|
+
checks on the way back in, so you get a `RecordHasChanged` to handle rather
|
|
118
|
+
than a mystery change to account for weeks later.
|
|
119
|
+
- **The `create table` your classes imply**, as statements to paste into a
|
|
120
|
+
migration — and a way to ask a live database where it has drifted from
|
|
121
|
+
them.
|
|
122
|
+
- **Somewhere to look when it is slow.** Every trip dray made to DSQL and every
|
|
123
|
+
one the cache saved you — the connection, the transaction, the statement, the
|
|
124
|
+
hit — with what asked for it and what it cost, as a tree you can print or
|
|
125
|
+
assert on. A test can pin *this page makes one read and not six*, and against
|
|
126
|
+
a cluster you can hang DSQL's own query plan under each read.
|
|
127
|
+
|
|
128
|
+
## Documentation
|
|
129
|
+
|
|
130
|
+
**[The manual][manual]** is the whole of it, and is meant to be read from
|
|
131
|
+
the top rather than searched: a record, a store to reach it through, a collection
|
|
132
|
+
to ask, children hanging off it, and — throughout — what the database is doing
|
|
133
|
+
underneath and why the shape above it is what it is.
|
|
134
|
+
|
|
135
|
+
It is one page on purpose. The story builds, so it is read in order the first
|
|
136
|
+
time, and after that a browser's own search reaches every word of it at once.
|
|
137
|
+
|
|
138
|
+
**[The reference][reference]** is the other half of that, and is
|
|
139
|
+
meant to be looked at rather than read: what the pieces are and how you reach
|
|
140
|
+
one from another, what each of them offers, which door runs which rule, and
|
|
141
|
+
where the transaction is. All of it in one screen, which is the one thing a
|
|
142
|
+
page read from the top cannot do. Open it in a browser — it is generated by
|
|
143
|
+
`scripts/reference.py`, half of it read out of the library itself.
|
|
144
|
+
|
|
145
|
+
**Building with an agent?** Hand it [the manual][manual]. The page is one page
|
|
146
|
+
for this reason as much as for reading: the whole promise fits in a single
|
|
147
|
+
fetch, in order, with the reasoning attached — so an agent is not guessing at
|
|
148
|
+
what a call takes, or reaching for a foreign key, a savepoint or a lock that is
|
|
149
|
+
not there. Pointing at it from whatever file your agent reads for project
|
|
150
|
+
context is enough, and [the reference][reference] is worth adding where the
|
|
151
|
+
work is mostly about which door runs which rule.
|
|
152
|
+
|
|
153
|
+
The page is also written *against* agents building blind — handed a domain to
|
|
154
|
+
build and this page, with dray's source barred — and a good many of its
|
|
155
|
+
sentences are there because one of those builds got something wrong. The
|
|
156
|
+
nuance is on the page rather than waiting to be discovered, and yours will not
|
|
157
|
+
be the first agent to meet it.
|
|
158
|
+
|
|
159
|
+
## A fuller example
|
|
160
|
+
|
|
161
|
+
The manual is where all of this is actually taught, in order and with the
|
|
162
|
+
reasoning. What follows is only a feel for it — the same register with the
|
|
163
|
+
rules it needs, the history it keeps and the questions it gets asked:
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
from datetime import datetime
|
|
167
|
+
|
|
168
|
+
import dray
|
|
169
|
+
from dray import (
|
|
170
|
+
Store, child, clock, collection, field, index, record, records_change
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
STATUSES = ("enquiry", "volunteer", "lapsed")
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def enqueue(what, who): # yours — a queue, a mail, a webhook
|
|
177
|
+
...
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def tidied(email):
|
|
181
|
+
return email.strip().lower() if email else None
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def whoever(write):
|
|
185
|
+
"""Whoever the save was told about, in `save(given={"whom": ...})`."""
|
|
186
|
+
return write.given.get("whom")
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
# Define it
|
|
190
|
+
|
|
191
|
+
@record(
|
|
192
|
+
table="person", # where the rows live
|
|
193
|
+
collection="people", # what the store calls them
|
|
194
|
+
order_by="family_name", # the order a read gets if nobody asks
|
|
195
|
+
indexes=[index("status", "family_name")],
|
|
196
|
+
cached_for=10, # seconds a row may be served from memory
|
|
197
|
+
)
|
|
198
|
+
class Person:
|
|
199
|
+
family_name: str # a plain annotation is a text column
|
|
200
|
+
given_names: str = ""
|
|
201
|
+
|
|
202
|
+
status: str = field(
|
|
203
|
+
default="enquiry",
|
|
204
|
+
# Limit what this will accept, no matter how it is assigned.
|
|
205
|
+
choices=STATUSES,
|
|
206
|
+
# React when the value moves, wherever the edit came from, with any
|
|
207
|
+
# function of yours. `records_change` is one dray ships: it queues a
|
|
208
|
+
# line into the child named, filling that child's first field.
|
|
209
|
+
on_change=records_change(into="logs"),
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
email: str | None = field(
|
|
213
|
+
# Runs wherever a value reaches the field: the constructor, an
|
|
214
|
+
# assignment, `parse`, and the value a filter is asked to match. So a
|
|
215
|
+
# row stored tidied is found by any spelling of it.
|
|
216
|
+
converter=tidied,
|
|
217
|
+
)
|
|
218
|
+
|
|
219
|
+
suburb: str | None = field(
|
|
220
|
+
stored_in="blob", # jsonb — no migration, no column spent
|
|
221
|
+
)
|
|
222
|
+
|
|
223
|
+
added_on: datetime | None = field(
|
|
224
|
+
# Fill this on the insert, with any function of yours. `clock` is one
|
|
225
|
+
# dray ships, and asks the database for the time rather than Python.
|
|
226
|
+
on_add=clock,
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
changed_on: datetime | None = field(
|
|
230
|
+
# Fill it again on every write after that, so a null here means
|
|
231
|
+
# nobody has edited this record yet.
|
|
232
|
+
on_save=clock,
|
|
233
|
+
)
|
|
234
|
+
|
|
235
|
+
# Ordinary Python. A record is your class, and dray has no opinion about
|
|
236
|
+
# anything it did not put there — this is not a field, not stored, and
|
|
237
|
+
# not in `as_dict()`.
|
|
238
|
+
@property
|
|
239
|
+
def full_name(self) -> str:
|
|
240
|
+
return f"{self.given_names} {self.family_name}".strip()
|
|
241
|
+
|
|
242
|
+
# Refuse a record that does not hang together. Where a rule needs the
|
|
243
|
+
# whole record rather than one value, and it runs at every door one comes
|
|
244
|
+
# in by, before any transaction is open.
|
|
245
|
+
@dray.check
|
|
246
|
+
def a_volunteer_is_somewhere(self):
|
|
247
|
+
if self.status == "volunteer" and not self.suburb:
|
|
248
|
+
raise ValueError("a volunteer is rostered out of a suburb")
|
|
249
|
+
|
|
250
|
+
# Act inside the write's own transaction. For a rule that has to write, or
|
|
251
|
+
# to read another record with it already open. `write.adding` is true only
|
|
252
|
+
# on the write that creates the record, `write.was` is what it held before
|
|
253
|
+
# this one, and `write.given` is who is asking.
|
|
254
|
+
@dray.before_save
|
|
255
|
+
def log_the_arrival(self, write):
|
|
256
|
+
if write.adding:
|
|
257
|
+
self.logs.add("enquiry received")
|
|
258
|
+
|
|
259
|
+
# Act once the rows are durable, and not at all if they never are. Where
|
|
260
|
+
# the work leaves the database — a job, a mail, a webhook.
|
|
261
|
+
@dray.after_commit
|
|
262
|
+
def tell_the_roster(self):
|
|
263
|
+
enqueue("person-changed", self.id)
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
@child(of=Person, name="notes", table="note", order_by="at")
|
|
267
|
+
class Note:
|
|
268
|
+
body: str # what `notes.add("...")` fills
|
|
269
|
+
at: datetime | None = field(on_add=clock)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
@child(of=Person, name="logs", table="person_log", order_by="at")
|
|
273
|
+
class Log:
|
|
274
|
+
message: str # what `records_change` writes into
|
|
275
|
+
at: datetime | None = field(on_add=clock)
|
|
276
|
+
whom: str | None = field(on_add=whoever)
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
@collection(of=Person)
|
|
280
|
+
class People:
|
|
281
|
+
"""Questions of your own, in SQL, answered in records."""
|
|
282
|
+
|
|
283
|
+
def changed_since(self, when: datetime) -> list[Person]:
|
|
284
|
+
# `sql_for` is how a field is named in SQL: the column where it has
|
|
285
|
+
# one, the expression that reads it out of the blob where it does
|
|
286
|
+
# not. So this keeps working if the field ever moves, and a name the
|
|
287
|
+
# class never declared is refused here rather than by the database.
|
|
288
|
+
changed = self.sql_for("changed_on")
|
|
289
|
+
return self.select_many(
|
|
290
|
+
f"select {self.columns} from {self.table}"
|
|
291
|
+
f" where {changed} >= %s order by {changed} desc",
|
|
292
|
+
[when],
|
|
293
|
+
)
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
# Use it
|
|
297
|
+
|
|
298
|
+
store = Store.connect(host="ab12cd.dsql.ap-southeast-2.on.aws")
|
|
299
|
+
store.create(Person, Note, Log) # the three tables these imply
|
|
300
|
+
|
|
301
|
+
# An enquiry, typed in.
|
|
302
|
+
person = store.people.add( # inserted, and handed back filled in
|
|
303
|
+
Person(family_name="Hemingway", given_names="Ernest", suburb="Leura",
|
|
304
|
+
email=" Ernest@Example.COM "),
|
|
305
|
+
given={"whom": "rod"}, # who is asking, for the rules to use
|
|
306
|
+
)
|
|
307
|
+
|
|
308
|
+
# And one from outside — a form, a spreadsheet, an API. `parse` runs the
|
|
309
|
+
# converters and the rules, so what it accepts is what a write will take.
|
|
310
|
+
other = store.people.add(
|
|
311
|
+
Person.parse({"family_name": "Stein", "given_names": "Gertrude",
|
|
312
|
+
"suburb": "Katoomba", "email": "GStein@Example.com"}),
|
|
313
|
+
given={"whom": "rod"},
|
|
314
|
+
)
|
|
315
|
+
|
|
316
|
+
# Both of them signed up at the same open day. One transaction, so the
|
|
317
|
+
# register cannot end up holding half of it — and `after_commit` waits for
|
|
318
|
+
# the outermost block, so the roster hears once rather than twice.
|
|
319
|
+
with store.transaction():
|
|
320
|
+
for one in (person, other):
|
|
321
|
+
one.status = "volunteer" # queues a line for `logs`
|
|
322
|
+
one.notes.add("Signed up at the Katoomba open day.")
|
|
323
|
+
one.save(given={"whom": "rod"})
|
|
324
|
+
|
|
325
|
+
# A name of your own in the tree, so a watcher can say what the whole page
|
|
326
|
+
# cost as well as what each read in it cost. Free when nobody is watching.
|
|
327
|
+
with store.span("the roster page"):
|
|
328
|
+
store.people.find() # both, by family_name — the class said
|
|
329
|
+
store.people.find(equals={"status": "volunteer", "suburb": "Leura"})
|
|
330
|
+
store.people.find(equals={"email": "ERNEST@example.com"}) # stored tidied
|
|
331
|
+
store.people.changed_since(datetime(2026, 1, 1))
|
|
332
|
+
store.people.by_id(person.id) # seeded by the find — no round trip
|
|
333
|
+
|
|
334
|
+
person.full_name # 'Ernest Hemingway' — yours, not dray's
|
|
335
|
+
|
|
336
|
+
person.as_dict() # every field the class declares
|
|
337
|
+
# {'family_name': 'Hemingway', 'given_names': 'Ernest', 'status': 'volunteer',
|
|
338
|
+
# 'email': 'ernest@example.com', 'suburb': 'Leura', 'added_on': datetime(…),
|
|
339
|
+
# 'changed_on': datetime(…), 'id': UUID(…), 'etag': '…'}
|
|
340
|
+
|
|
341
|
+
# Two kinds of child, put in one order here rather than by the database.
|
|
342
|
+
# They are ordinary objects once they have arrived, so this is a `sorted`.
|
|
343
|
+
for one in sorted([*person.notes, *person.logs], key=lambda one: one.at):
|
|
344
|
+
print(f"{one.at:%H:%M}", getattr(one, "message", None) or one.body)
|
|
345
|
+
# 15:25 enquiry received
|
|
346
|
+
# 15:25 status changed from 'enquiry' to 'volunteer'.
|
|
347
|
+
# 15:25 Signed up at the Katoomba open day.
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Six of those fields get columns of their own and `suburb` lives in a jsonb
|
|
351
|
+
document, and the filter at the end reads the same across both. `status` takes
|
|
352
|
+
no word outside `STATUSES` and writes a line into `logs` every time it moves,
|
|
353
|
+
whether it was moved by your code, by a form or by an importer. The check runs
|
|
354
|
+
at every door a record comes in by, so a volunteer with nowhere to be rostered
|
|
355
|
+
is refused before a statement is written.
|
|
356
|
+
|
|
357
|
+
Each person and their notes and logs go in one transaction, and the block puts
|
|
358
|
+
both people in one more: all of it lands or none of it does, and
|
|
359
|
+
`tell_the_roster` waits for the outermost block rather than firing per save.
|
|
360
|
+
`changed_since` is the shape `find` will not do — equality is the whole of what
|
|
361
|
+
it takes, so a range is SQL you wrote, handed back as records rather than rows.
|
|
362
|
+
And the last read in the page costs nothing: the `find` above it left its rows
|
|
363
|
+
where `by_id` looks, for the ten seconds the class asked for.
|
|
364
|
+
|
|
365
|
+
And because every trip to DSQL is a span, that run draws itself. This is the
|
|
366
|
+
page above, against a real cluster:
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
├─ caller the roster page··············· 191.74ms █████████████████████▉
|
|
370
|
+
│ ├─ statement Person·················· 61.38ms 2 rows ███████
|
|
371
|
+
│ │ ├─ execute Person················· 60.58ms ██████▉
|
|
372
|
+
│ │ ╰─ hydrate Person················· 0.13ms 2 rows ▏
|
|
373
|
+
│ ├─ statement Person·················· 33.90ms 1 rows ███▉
|
|
374
|
+
│ │ ├─ execute Person················· 33.35ms ███▊
|
|
375
|
+
│ │ ╰─ hydrate Person················· 0.08ms 1 rows ▏
|
|
376
|
+
│ ├─ statement Person·················· 35.36ms 1 rows ████
|
|
377
|
+
│ │ ├─ execute Person················· 34.92ms ████
|
|
378
|
+
│ │ ╰─ hydrate Person················· 0.05ms 1 rows ▏
|
|
379
|
+
│ ├─ statement Person·················· 60.02ms 2 rows ██████▉
|
|
380
|
+
│ │ ├─ execute Person················· 59.17ms ██████▊
|
|
381
|
+
│ │ ╰─ hydrate Person················· 0.14ms 2 rows ▏
|
|
382
|
+
│ ╰─ cache Person······················ 0.19ms 1 rows ▏
|
|
383
|
+
│ ╰─ hydrate Person················· 0.04ms 1 rows ▏
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
Four reads at thirty to sixty milliseconds each, and the fifth — the `by_id`
|
|
387
|
+
the `find` had already filled — at **0.19ms**. `just flow` hangs DSQL's own
|
|
388
|
+
query plan under each read as well, which is where you find out that the slow
|
|
389
|
+
one was a scan.
|
|
390
|
+
|
|
391
|
+
## Contributing
|
|
392
|
+
|
|
393
|
+
**Everything is in issues.** A finding becomes an issue, a decision becomes a
|
|
394
|
+
comment on one, and what a change did is in its pull request — there is no
|
|
395
|
+
design document and no notes file anywhere. Which means an obvious-sounding
|
|
396
|
+
proposal may be one that has already been argued down, so search the closed
|
|
397
|
+
issues before writing a new one.
|
|
398
|
+
|
|
399
|
+
The suite needs no configuration — `pytest-postgresql` starts a PostgreSQL and
|
|
400
|
+
throws it away — but it does want [`just`](https://just.systems) and
|
|
401
|
+
[`uv`](https://docs.astral.sh/uv/) on your machine:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
just test
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Run it that way rather than by hand. Both `--group test` and `--extra dsql`
|
|
408
|
+
have to be named, and a shorter command does not fail — `uv run pytest`
|
|
409
|
+
resolves a pytest that has never heard of dray and passes having run nothing.
|
|
410
|
+
`just --list` has the others: `just fresh` builds the environment from scratch
|
|
411
|
+
when a pass needs to be provably honest, and `just cluster` runs the half local
|
|
412
|
+
PostgreSQL cannot answer.
|
|
413
|
+
|
|
414
|
+
**Open an issue first, and wait for the decision in it to be settled.** Not as
|
|
415
|
+
a formality: `docs/manual.md` is written first, so a change to what a caller
|
|
416
|
+
can call is a change to that page and usually a decision as well. A pull
|
|
417
|
+
request that arrives without one is often work somebody has to turn down for a
|
|
418
|
+
reason that would have been two lines in a comment. An issue is welcome on its
|
|
419
|
+
own and obliges you to write nothing — a finding, reproduced, is worth as much
|
|
420
|
+
as a fix.
|
|
421
|
+
|
|
422
|
+
A pull request branches from `main` and is named for the change. Commit
|
|
423
|
+
subjects are a short declarative sentence in the present tense, and carry no
|
|
424
|
+
trailers — no `Co-Authored-By`, no tool or session links. The author field
|
|
425
|
+
already says, and this history will outlive every tool that touched it. Put
|
|
426
|
+
`Closes #N` in the body where the change finishes the issue.
|
|
427
|
+
|
|
428
|
+
The body carries the thinking, because the diff carries the change: before and
|
|
429
|
+
after as a handful of lines of real code, first and before any argument, then
|
|
430
|
+
what was wrong, the decisions you made that the issue did not settle, and what
|
|
431
|
+
you tested and deliberately did not. Tests come with the change rather than
|
|
432
|
+
after it, and are named for the behaviour rather than the function.
|
|
433
|
+
|
|
434
|
+
`docs/manual.md` is written first and the API follows it. If a change makes a
|
|
435
|
+
sentence on that page untrue, the sentence is part of the change.
|
|
436
|
+
|
|
437
|
+
[manual]: https://github.com/draylabs/dray/blob/main/docs/manual.md
|
|
438
|
+
[reference]: https://github.com/draylabs/dray/blob/main/docs/reference.html
|