@gallopsystems/agent-skills 1.31.2 → 1.33.0
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.
- package/README.md +24 -0
- package/package.json +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
- package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
- package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
- package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
- package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
- package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
- package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
- package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
- package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
- package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
- package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
- package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
- package/plugins/pr-review/skills/pr-review/judge.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
- package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Output formats
|
|
2
|
+
|
|
3
|
+
The content is the same in every format: one section per answer or feature, each
|
|
4
|
+
with the kind of answer, the why, the steps and the screenshots. What changes is
|
|
5
|
+
how much fits and how it is delivered. Whatever the format, you prepare it and
|
|
6
|
+
the user sends it.
|
|
7
|
+
|
|
8
|
+
## pdf (default)
|
|
9
|
+
|
|
10
|
+
For anything with more than two or three steps, or when the client will print
|
|
11
|
+
it or forward it.
|
|
12
|
+
|
|
13
|
+
- Start from `templates/guide.html`. Page 1 has the title, the date, who it is
|
|
14
|
+
for, a numbered contents list (one line per section, with the outcome), the
|
|
15
|
+
demo-data note and any sign-in or admin note. The first section may start
|
|
16
|
+
under it.
|
|
17
|
+
- One `<section>` per answer or feature. Each section after the first starts a
|
|
18
|
+
new page.
|
|
19
|
+
- Screenshot widths: `w-s` for a chip, a header or a single control; `w-m` for a
|
|
20
|
+
dialog, a card or a panel; `w-l` for a wide table. Before/after goes in a
|
|
21
|
+
`.pair`.
|
|
22
|
+
- Render with `bin/render.mjs` and review the contact sheet. A clean guide has no
|
|
23
|
+
stranded headings, no page holding a single note, and no figure on a different
|
|
24
|
+
page from its step. Eight pages for four answers is normal.
|
|
25
|
+
- File name: `<App> - <what it is> - <reader or date>.pdf`, for example
|
|
26
|
+
`Portal - answers for Dana.pdf` or `Portal - what's new - March 2026.pdf`.
|
|
27
|
+
|
|
28
|
+
## html
|
|
29
|
+
|
|
30
|
+
The same file as the pdf, before rendering, for the web: a link the client can
|
|
31
|
+
open, or a page in the app's own docs.
|
|
32
|
+
|
|
33
|
+
- Keep `shots/` beside the HTML and use relative image paths.
|
|
34
|
+
- If it is going to be published somewhere (an artifact, a docs site), that is the
|
|
35
|
+
user's call. Prepare it, and ask before publishing.
|
|
36
|
+
|
|
37
|
+
## email
|
|
38
|
+
|
|
39
|
+
For one to three short answers, or an announcement of one or two features.
|
|
40
|
+
|
|
41
|
+
- Write a **draft** in the user's voice, never sent by you. Give the subject, the
|
|
42
|
+
body and the list of attachments. If the user has an email tool connected,
|
|
43
|
+
create a draft there only if they ask.
|
|
44
|
+
- Subject: what it's about, in their words ("Your questions about order
|
|
45
|
+
documents", "New: orders now wait for the signed form").
|
|
46
|
+
- Body: a one-line greeting, then one short paragraph per answer: the answer
|
|
47
|
+
first, then the steps as a numbered list with the exact labels in bold. Refer to
|
|
48
|
+
the screenshots by number ("see screenshot 2"). End with one line offering
|
|
49
|
+
help.
|
|
50
|
+
- Attach the screenshots as numbered PNGs (`1-documents-setting.png`, …), in the
|
|
51
|
+
order the body refers to them. For more than about five screenshots, attach
|
|
52
|
+
the pdf instead and keep the body to a summary of each answer.
|
|
53
|
+
|
|
54
|
+
## whatsapp
|
|
55
|
+
|
|
56
|
+
For quick answers to someone who asked in a chat.
|
|
57
|
+
|
|
58
|
+
- **One message per answer**, short enough to read on a phone (about 600
|
|
59
|
+
characters at most). Put a number on each when there are several ("1/3").
|
|
60
|
+
- WhatsApp formatting only: `*bold*` (single asterisks), `_italic_`, plain line
|
|
61
|
+
breaks, and numbered steps as `1.` lines. No headings, tables, links in
|
|
62
|
+
markdown syntax, or nested lists.
|
|
63
|
+
- Bold the exact button and menu names: `Go to *Admin → Documents*`.
|
|
64
|
+
- Screenshots go as separate images, each with a one-line caption, sent after
|
|
65
|
+
the message they belong to. List them in order: message 1, image 1a, image 1b,
|
|
66
|
+
message 2, and so on. Two images per answer at most; crop tight, because they
|
|
67
|
+
are seen on a phone.
|
|
68
|
+
- Give the user the messages as plain text blocks, ready to paste, plus the image
|
|
69
|
+
files in order. You never send them.
|
|
70
|
+
- If an answer needs more than four steps, say so in the message and send the
|
|
71
|
+
pdf for that part.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<!--
|
|
3
|
+
The guide layout for pdf and html output. Copy it next to the shots/ folder,
|
|
4
|
+
replace the example content, and render with bin/render.mjs.
|
|
5
|
+
|
|
6
|
+
Building blocks (all in the <style> below):
|
|
7
|
+
.toc numbered list of every answer, on page 1
|
|
8
|
+
.tag.can/.new/.data/.ask
|
|
9
|
+
what kind of answer this is: "You can do this already",
|
|
10
|
+
"New", "A setting or data fix", "Needs your answer"
|
|
11
|
+
blockquote.ask the client's own words, quoted
|
|
12
|
+
ol.steps numbered steps; each <li> holds its text and its figure
|
|
13
|
+
figure.w-s/.w-m/.w-l
|
|
14
|
+
screenshot widths: small (a chip or a header), medium (a
|
|
15
|
+
dialog, a card), large (a full-width table)
|
|
16
|
+
.pair + .arrow before → after, side by side
|
|
17
|
+
.note / .note.warn
|
|
18
|
+
grey for "good to know", amber for "watch out"
|
|
19
|
+
.keep wrap a heading, its text and its figure so a page break
|
|
20
|
+
cannot separate them
|
|
21
|
+
|
|
22
|
+
Page breaks: each top-level <section> after the first starts a new page. Keep
|
|
23
|
+
sections to one per answer or feature; never split one answer into two
|
|
24
|
+
sections just to start a page.
|
|
25
|
+
-->
|
|
26
|
+
<html lang="en">
|
|
27
|
+
<head>
|
|
28
|
+
<meta charset="utf-8">
|
|
29
|
+
<title>TITLE</title>
|
|
30
|
+
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
31
|
+
<style>
|
|
32
|
+
@page { size: Letter; margin: 0.6in 0.65in 0.7in; }
|
|
33
|
+
:root { --ink: #23201c; --muted: #6b655d; --line: #e6e1d9; --accent: #1f4d3a; --soft: #f4f1ec; --amber: #9a5b00; --amber-soft: #fdf6e3; --blue: #24467a; --blue-soft: #e7eefb; --green-soft: #e5f2ea; }
|
|
34
|
+
* { box-sizing: border-box; }
|
|
35
|
+
body { font-family: "Plus Jakarta Sans", system-ui, sans-serif; color: var(--ink); font-size: 10.5pt; line-height: 1.5; margin: 0; }
|
|
36
|
+
h1 { font-size: 22pt; margin: 0 0 4pt; letter-spacing: -0.01em; }
|
|
37
|
+
.sub { color: var(--muted); margin: 0 0 18pt; }
|
|
38
|
+
h2 { font-size: 15pt; margin: 0 0 4pt; letter-spacing: -0.005em; break-after: avoid; }
|
|
39
|
+
h3 { font-size: 11pt; margin: 14pt 0 4pt; break-after: avoid; }
|
|
40
|
+
h3 + p { break-before: avoid; }
|
|
41
|
+
section + section { break-before: page; }
|
|
42
|
+
blockquote.ask { border-left: 3px solid var(--line); padding: 2pt 0 2pt 10pt; color: var(--muted); font-style: italic; margin: 6pt 0 10pt; }
|
|
43
|
+
.tag { display: inline-block; font-size: 8.5pt; font-weight: 600; padding: 2pt 7pt; border-radius: 99px; margin-bottom: 6pt; }
|
|
44
|
+
.tag.can { background: var(--green-soft); color: var(--accent); }
|
|
45
|
+
.tag.new { background: var(--blue-soft); color: var(--blue); }
|
|
46
|
+
.tag.data, .tag.ask { background: var(--amber-soft); color: var(--amber); }
|
|
47
|
+
ol.steps { padding-left: 0; list-style: none; counter-reset: s; margin: 8pt 0; }
|
|
48
|
+
ol.steps > li { counter-increment: s; position: relative; padding-left: 26pt; margin: 0 0 12pt; break-inside: avoid; }
|
|
49
|
+
ol.steps > li::before { content: counter(s); position: absolute; left: 0; top: 0; width: 18pt; height: 18pt; border-radius: 50%; background: var(--accent); color: #fff; font-size: 9pt; font-weight: 600; display: flex; align-items: center; justify-content: center; }
|
|
50
|
+
figure { margin: 6pt 0 0; break-inside: avoid; }
|
|
51
|
+
figure img { display: block; max-width: 100%; border: 1px solid var(--line); border-radius: 6px; }
|
|
52
|
+
figcaption { font-size: 8.5pt; color: var(--muted); margin-top: 3pt; }
|
|
53
|
+
.w-s img { max-width: 2.4in; } .w-m img { max-width: 4.2in; } .w-l img { max-width: 100%; }
|
|
54
|
+
.pair { display: flex; gap: 14pt; align-items: flex-end; break-inside: avoid; }
|
|
55
|
+
.pair figure { flex: 0 0 auto; }
|
|
56
|
+
.arrow { font-size: 16pt; color: var(--muted); padding-bottom: 18pt; }
|
|
57
|
+
.note { background: var(--soft); border-radius: 6px; padding: 8pt 11pt; margin: 10pt 0; break-inside: avoid; }
|
|
58
|
+
.note.warn { background: var(--amber-soft); }
|
|
59
|
+
.note > strong:first-child { display: block; margin-bottom: 2pt; }
|
|
60
|
+
.keep { break-inside: avoid; }
|
|
61
|
+
ul { margin: 4pt 0 8pt; padding-left: 15pt; } li { margin: 2pt 0; }
|
|
62
|
+
.toc { border: 1px solid var(--line); border-radius: 8px; padding: 10pt 14pt; }
|
|
63
|
+
.toc li { margin: 4pt 0; }
|
|
64
|
+
.small { font-size: 8.5pt; color: var(--muted); }
|
|
65
|
+
b, strong { font-weight: 600; }
|
|
66
|
+
</style>
|
|
67
|
+
</head>
|
|
68
|
+
<body>
|
|
69
|
+
|
|
70
|
+
<section>
|
|
71
|
+
<h1>TITLE</h1>
|
|
72
|
+
<p class="sub">DATE · for READER</p>
|
|
73
|
+
|
|
74
|
+
<div class="toc">
|
|
75
|
+
<ol>
|
|
76
|
+
<li><b>First answer or feature, in the reader's words.</b> One line on the outcome.</li>
|
|
77
|
+
<li><b>Second.</b> One line.</li>
|
|
78
|
+
</ol>
|
|
79
|
+
</div>
|
|
80
|
+
<p class="small" style="margin-top:14pt">The screenshots come from a demo copy of APP filled with made-up records, so you'll see different names, but the screens and buttons are the same.</p>
|
|
81
|
+
|
|
82
|
+
<!-- The first answer may start on page 1, under the contents. -->
|
|
83
|
+
<h2 style="margin-top:22pt">1. Heading in the reader's words</h2>
|
|
84
|
+
<span class="tag can">You can do this already</span>
|
|
85
|
+
<blockquote class="ask">"Their question, quoted."</blockquote>
|
|
86
|
+
<p>Why it behaves the way it does, in one short paragraph.</p>
|
|
87
|
+
<ol class="steps">
|
|
88
|
+
<li>Go to <b>Exact label</b>, then <b>Exact label</b>.
|
|
89
|
+
<figure class="w-l"><img src="shots/example-1.png"></figure></li>
|
|
90
|
+
<li>Click <b>Exact label</b>. It saves straight away.
|
|
91
|
+
<div class="pair">
|
|
92
|
+
<figure class="w-s"><img src="shots/example-2-before.png"><figcaption>Before</figcaption></figure>
|
|
93
|
+
<div class="arrow">→</div>
|
|
94
|
+
<figure class="w-s"><img src="shots/example-2-after.png"><figcaption>After</figcaption></figure>
|
|
95
|
+
</div></li>
|
|
96
|
+
</ol>
|
|
97
|
+
<div class="note"><strong>Good to know</strong>
|
|
98
|
+
<ul><li>What else this changes.</li><li>The alternative for a single record.</li></ul>
|
|
99
|
+
</div>
|
|
100
|
+
</section>
|
|
101
|
+
|
|
102
|
+
<section>
|
|
103
|
+
<h2>2. A new feature</h2>
|
|
104
|
+
<span class="tag new">New in APP</span>
|
|
105
|
+
<p>What you can now do, and why it helps you. You don't need to do anything; it works on its own.</p>
|
|
106
|
+
<div class="keep">
|
|
107
|
+
<h3>Where you'll see it</h3>
|
|
108
|
+
<p>One sentence pointing at the screenshot.</p>
|
|
109
|
+
<figure class="w-m"><img src="shots/feature-1.png"><figcaption>What's circled.</figcaption></figure>
|
|
110
|
+
</div>
|
|
111
|
+
<div class="note"><strong>The rules</strong><ul><li>Rule, in the on-screen words.</li></ul></div>
|
|
112
|
+
<div class="note warn"><strong>What to expect the first day</strong>What changes as soon as this is live.</div>
|
|
113
|
+
</section>
|
|
114
|
+
|
|
115
|
+
</body>
|
|
116
|
+
</html>
|
|
@@ -20,13 +20,14 @@ Use this skill when:
|
|
|
20
20
|
This skill is split into topic guides — read the [Core Principles](#core-principles) below, then open the guide matching what you're doing:
|
|
21
21
|
|
|
22
22
|
- [expression-builder.md](references/expression-builder.md) — the ExpressionBuilder (`eb`) foundation, `eb.val` vs `eb.lit`, standalone `eb`, conditional expression arrays, string concatenation
|
|
23
|
-
- [query-patterns.md](references/query-patterns.md) — SELECT, WHERE clauses, JOINs (incl. callback format), aggregations, ORDER BY, CTEs, JSON aggregation
|
|
23
|
+
- [query-patterns.md](references/query-patterns.md) — SELECT, WHERE clauses, JOINs (incl. callback format), aggregations, ORDER BY, CTEs, JSON aggregation, where LIMIT goes (cap last; count and list from one base query), deterministic ordering
|
|
24
24
|
- [json-jsonb-arrays.md](references/json-jsonb-arrays.md) — JSONB columns, array columns, querying arrays/JSONB, JSONPath, `$if`, relations (jsonArrayFrom/jsonObjectFrom), reusable helpers, splitting build/execute, subqueries, INSERT/UPDATE
|
|
25
25
|
- [window-functions.md](references/window-functions.md) — ROW_NUMBER/RANK, LAG/LEAD, windowed aggregates, frames
|
|
26
26
|
- [set-lateral-locking.md](references/set-lateral-locking.md) — set operations (UNION/INTERSECT/EXCEPT), LATERAL joins, row locking (FOR UPDATE / SKIP LOCKED)
|
|
27
|
+
- [concurrency-and-transactions.md](references/concurrency-and-transactions.md) — read-then-write races: unique constraint + `onConflict`, conditional updates, lock-then-re-read, the same lock on every write path, advisory locks, `forUpdate("table")` with joins, lock order, one transaction for all writes, savepoints (only on `startTransaction()`)
|
|
27
28
|
- [full-text-and-grouping.md](references/full-text-and-grouping.md) — full-text search (tsvector/tsquery), advanced grouping (ROLLUP/CUBE/GROUPING SETS)
|
|
28
|
-
- [migrations-and-codegen.md](references/migrations-and-codegen.md) — migrations (config, commands, file structure, column types, gotchas) and type generation
|
|
29
|
-
- [common-pitfalls.md](references/common-pitfalls.md) —
|
|
29
|
+
- [migrations-and-codegen.md](references/migrations-and-codegen.md) — migrations (config, commands, file structure, column types, gotchas, ordering), migration safety on live data (one transaction per batch, `NOT VALID` + `VALIDATE`, `CONCURRENTLY` and invalid indexes, non-destructive `down`), and type generation
|
|
30
|
+
- [common-pitfalls.md](references/common-pitfalls.md) — raw `sql`, forgetting `.execute()`, `whereRef`, typed function returns, FK indexing, typed `sql` literals, DATE timezones, the `between` operator, string args as column refs, identifier normalization, CHECK vs NULL/NaN, date/time boundaries, LIKE wildcards, large ID lists and numeric inputs
|
|
30
31
|
- [helpers-and-extending.md](references/helpers-and-extending.md) — PostgreSQL helpers summary, `mergeAction`, custom helper functions, custom expression classes
|
|
31
32
|
- [deep-types.md](references/deep-types.md) — fixing the "excessively deep types" error with `$assertType`
|
|
32
33
|
- [seeding-pattern.md](references/seeding-pattern.md) — idempotent preview/dev seeding: factories shared by tests + seeds, monotonic-counter uniqueness, order-independence, scenes built in target state, the validity harness, preview login
|
|
@@ -54,6 +55,19 @@ Runnable, copy-pasteable query examples live alongside as `.ts` files:
|
|
|
54
55
|
3. **Let TypeScript guide you**: If it compiles, it's likely correct SQL
|
|
55
56
|
4. **Document schema in the database, and read it before you touch a table**: Keep table/column/index/constraint notes as Postgres COMMENTs (not just migration source), surface them in the generated `db.d.ts`, and update them in the same migration that changes how something works. Consult that JSDoc to gather context before querying or altering a table — see [migrations-and-codegen.md](references/migrations-and-codegen.md#schema-comments--document-in-the-db-not-just-in-migration-source).
|
|
56
57
|
|
|
58
|
+
## Traps Code Review Keeps Catching
|
|
59
|
+
|
|
60
|
+
These are the bugs reviewers most often find in Kysely code that compiles and passes tests. Check each one before you finish a query or migration:
|
|
61
|
+
|
|
62
|
+
- **Read-then-write is a race.** A `SELECT` takes no lock under READ COMMITTED. Use a unique constraint + `onConflict`, put the guard in the `UPDATE`'s `WHERE` and check `numUpdatedRows`, or lock the parent row (`forUpdate("table")`) and re-read after the lock. Every write path must take the same lock. → [concurrency-and-transactions.md](references/concurrency-and-transactions.md)
|
|
63
|
+
- **Related writes share one `trx`**; helpers take the executor as a parameter. A caught error aborts the transaction, and savepoints exist only on `db.startTransaction()`. → [concurrency-and-transactions.md](references/concurrency-and-transactions.md#5-a-caught-database-error-poisons-the-transaction)
|
|
64
|
+
- **Cap last.** Filter, exclude ineligible rows and aggregate before `limit`; build count and list from one base query; look up exact matches before a limited fuzzy search; `in []` is a syntax error. → [query-patterns.md](references/query-patterns.md#limit-counts-and-filters-cap-last)
|
|
65
|
+
- **`DESC` puts NULLs first**: add `nullsLast()`, a unique tie-breaker, and order *inside* `jsonAgg`. → [query-patterns.md](references/query-patterns.md#deterministic-ordering)
|
|
66
|
+
- **Normalize identifiers once** (trim + lowercase on write, unique index on `lower(...)`, same expression on lookup and join). → [common-pitfalls.md](references/common-pitfalls.md#10-normalize-identifiers-once-and-match-the-same-way-everywhere)
|
|
67
|
+
- **Date ranges:** exclusive upper bound at the next day; "today" in the business time zone, not the session's. → [common-pitfalls.md](references/common-pitfalls.md#12-date-and-time-boundaries)
|
|
68
|
+
- **CHECK passes on NULL and NaN**; **LIKE's `_` is a wildcard**. → [common-pitfalls.md](references/common-pitfalls.md#11-check-constraints-pass-on-null-and-nan)
|
|
69
|
+
- **Migrations on live tables:** `NOT VALID` then `VALIDATE` in a later deploy, non-destructive `down()`, repoint foreign keys before deleting or merging rows. → [migrations-and-codegen.md](references/migrations-and-codegen.md#migration-safety-on-tables-that-already-have-data)
|
|
70
|
+
|
|
57
71
|
## Contributing Back
|
|
58
72
|
|
|
59
73
|
This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the kysely-postgres skill?"**
|
|
@@ -229,3 +229,94 @@ or it infers `unknown` and the operator overload rejects it:
|
|
|
229
229
|
.where("search_vector", "@@", sql<string>`to_tsquery('english', ${q})`)
|
|
230
230
|
```
|
|
231
231
|
|
|
232
|
+
### 10. Normalize Identifiers Once, and Match the Same Way Everywhere
|
|
233
|
+
|
|
234
|
+
Emails, codes and external ids arrive with mixed case and stray whitespace. If
|
|
235
|
+
writes, lookups, joins and the unique index each normalize differently, you get
|
|
236
|
+
missed matches and duplicate accounts. Pick one form, store it, and index it:
|
|
237
|
+
|
|
238
|
+
```typescript
|
|
239
|
+
// write: normalize before insert/update
|
|
240
|
+
const email = input.email.trim().toLowerCase();
|
|
241
|
+
|
|
242
|
+
// enforce: store only the normalized form, so the column itself can be compared.
|
|
243
|
+
// SQL trimming is not JS trimming (`btrim(x)` strips spaces only; `\\s` in a regex
|
|
244
|
+
// is ASCII-only in the C locale, while JS `trim()` also strips U+FEFF and others),
|
|
245
|
+
// so backfill with the SAME function the write path uses, not a SQL lookalike:
|
|
246
|
+
for (const u of await db.selectFrom("user").select(["id", "email"]).execute()) {
|
|
247
|
+
const email = u.email.trim().toLowerCase();
|
|
248
|
+
if (email !== u.email) await db.updateTable("user").set({ email }).where("id", "=", u.id).execute();
|
|
249
|
+
}
|
|
250
|
+
// a backstop for writers that skip the normalizer (catches case and ASCII whitespace)
|
|
251
|
+
await sql`alter table "user" add constraint user_email_normalized
|
|
252
|
+
check (email = lower(email) and email !~ '^\\s|\\s$')`.execute(db);
|
|
253
|
+
await db.schema.createIndex("user_email_uq").on("user").unique().column("email").execute();
|
|
254
|
+
// (resolve rows that collide after the backfill before creating the index)
|
|
255
|
+
|
|
256
|
+
// read: a plain comparison now matches every row
|
|
257
|
+
.where("email", "=", email)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Apply the same normalization to both sides of a join key and to values you test
|
|
261
|
+
for emptiness: a concatenation like `first || ' ' || last` is `' '`, not `''`, when
|
|
262
|
+
both parts are empty, so trim before the check. If later code matches
|
|
263
|
+
case-insensitively, the SQL predicate must too.
|
|
264
|
+
|
|
265
|
+
### 11. CHECK Constraints Pass on NULL (and NaN)
|
|
266
|
+
|
|
267
|
+
A CHECK is satisfied when its expression is true **or NULL**, so a condition that
|
|
268
|
+
touches a NULL column silently allows the row:
|
|
269
|
+
|
|
270
|
+
```typescript
|
|
271
|
+
// WRONG - kind='district' with district_code NULL passes (NULL is not false)
|
|
272
|
+
sql`check (kind <> 'district' or district_code between 1 and 32)`
|
|
273
|
+
// RIGHT - say IS NOT NULL explicitly
|
|
274
|
+
sql`check (kind <> 'district' or (district_code is not null and district_code between 1 and 32))`
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`numeric` also accepts `'NaN'`, and PostgreSQL sorts NaN above every number, so
|
|
278
|
+
`check (amount > 0)` passes for NaN. Reject `!Number.isFinite(x)` before writing.
|
|
279
|
+
When a CHECK couples two columns (`status = 'failed'` requires `error` not null),
|
|
280
|
+
every update of one must set the other in the same statement.
|
|
281
|
+
|
|
282
|
+
### 12. Date and Time Boundaries
|
|
283
|
+
|
|
284
|
+
- **Inclusive end date vs timestamp column:** `where created_at <= '2025-01-31'`
|
|
285
|
+
means midnight at the *start* of the 31st and drops that whole day. Use an
|
|
286
|
+
exclusive upper bound at the next day:
|
|
287
|
+
`.where("created_at", ">=", start).where("created_at", "<", dayAfterEnd)`.
|
|
288
|
+
- **"Today" depends on the session time zone.** `CURRENT_DATE` and
|
|
289
|
+
`now()::date` use the connection's `TimeZone` (often UTC on servers), and
|
|
290
|
+
`CURRENT_DATE AT TIME ZONE 'X'` does not give X's date. Convert the instant
|
|
291
|
+
first, then take the date (or compute the boundary in TypeScript with the zone
|
|
292
|
+
and pass it as a parameter):
|
|
293
|
+
```typescript
|
|
294
|
+
sql<string>`(now() at time zone 'America/New_York')::date`
|
|
295
|
+
```
|
|
296
|
+
Cutoffs such as "before today" belong at that zone's midnight, not UTC midnight.
|
|
297
|
+
- **Casting untrusted text to a date:** PostgreSQL does not evaluate `WHERE`/`AND`
|
|
298
|
+
terms in a defined order, so `col ~ '^\d{4}-\d{2}-\d{2}$' and col::date > ...`
|
|
299
|
+
can still cast the bad value and error. Guard with `CASE` (which does order
|
|
300
|
+
evaluation) or clean the value to NULL first. A regex shape check also accepts
|
|
301
|
+
`2025-02-30`; validate a real calendar date before inserting.
|
|
302
|
+
|
|
303
|
+
### 13. LIKE Treats `_` and `%` as Wildcards
|
|
304
|
+
|
|
305
|
+
`like 'user_%'` also matches `userX…`. Escape user-supplied or literal patterns
|
|
306
|
+
(`value.replace(/[\\%_]/g, "\\$&")`), or compare a literal prefix without LIKE:
|
|
307
|
+
`eb.fn<boolean>("starts_with", [eb.ref("code"), eb.val(prefix)])`. When
|
|
308
|
+
matching an identifier inside text, match a whole token, not a substring, so
|
|
309
|
+
`12` does not match `1234`.
|
|
310
|
+
|
|
311
|
+
### 14. Large ID Lists and Numeric Inputs
|
|
312
|
+
|
|
313
|
+
- The wire protocol caps a statement at 65,535 bind parameters, so
|
|
314
|
+
`.where("id", "in", ids)` with a huge array fails. Send one array parameter
|
|
315
|
+
instead: `.where((eb) => eb("id", "=", eb.fn.any(eb.val(ids))))` emits
|
|
316
|
+
`"id" = any($1)`. (Batch bulk inserts by row count for the same reason.)
|
|
317
|
+
- Text that will be compared to a `bigint`/`integer` column must be range-checked
|
|
318
|
+
first; an out-of-range literal raises an error instead of matching nothing.
|
|
319
|
+
- Casting `numeric` to an integer type rounds (ties away from zero); `Math.trunc`
|
|
320
|
+
or `trunc()` first when you mean truncation toward zero (`floor` rounds
|
|
321
|
+
negatives down: `floor(-1.7)` is `-2`).
|
|
322
|
+
- Sort numeric parts of a code numerically, not as text (`'100' < '99'` as text).
|
package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
## Concurrency and Transactions
|
|
2
|
+
|
|
3
|
+
PostgreSQL's default isolation is READ COMMITTED: every statement sees the rows
|
|
4
|
+
committed before *it* started, and a `SELECT` takes no lock that stops another
|
|
5
|
+
transaction from changing what you just read. So any code shaped "read, decide
|
|
6
|
+
in TypeScript, then write" is a race unless something serializes it. This is the
|
|
7
|
+
single most common bug class in reviewed Kysely code. Pick one of the tools below
|
|
8
|
+
for every read-then-write; "it is inside a transaction" is not one of them.
|
|
9
|
+
|
|
10
|
+
### 1. Check-then-insert: let a unique constraint decide
|
|
11
|
+
|
|
12
|
+
```typescript
|
|
13
|
+
// WRONG - two requests both see "no row" and both insert (or one 500s on 23505)
|
|
14
|
+
const existing = await db.selectFrom("user").select("id")
|
|
15
|
+
.where("email", "=", email).executeTakeFirst();
|
|
16
|
+
if (!existing) await db.insertInto("user").values({ email }).execute();
|
|
17
|
+
|
|
18
|
+
// RIGHT - unique index + ON CONFLICT; the database arbitrates
|
|
19
|
+
const row = await db.insertInto("user").values({ email })
|
|
20
|
+
.onConflict((oc) => oc.column("email").doNothing())
|
|
21
|
+
.returning("id")
|
|
22
|
+
.executeTakeFirst(); // undefined => someone else inserted it first
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
A row that must be unique needs a unique index (partial if it is "one *active*
|
|
26
|
+
row per X": `.where(...)` on `createIndex`). The conflict target must then repeat
|
|
27
|
+
the index predicate, or PostgreSQL finds no matching index and rejects the insert:
|
|
28
|
+
`oc.column("email").where("deleted_at", "is", null).doNothing()`.
|
|
29
|
+
|
|
30
|
+
If the identity can be matched by more than one unique key (an external id *or* an
|
|
31
|
+
email), a conflict target on one key does not catch a collision on the other, and
|
|
32
|
+
a pre-check of both is itself a race. Use an untargeted
|
|
33
|
+
`.onConflict((oc) => oc.doNothing())`, which covers every unique index, then
|
|
34
|
+
select the existing rows by either key when nothing was inserted. If that returns
|
|
35
|
+
two different rows (the external id belongs to one, the email to another), do not
|
|
36
|
+
pick one: report a conflict for a person to resolve.
|
|
37
|
+
|
|
38
|
+
On upsert, `doUpdateSet` overwrites with whatever you send. When the incoming
|
|
39
|
+
source can be missing a value, keep the stored one instead of clearing it:
|
|
40
|
+
`phone: (eb) => eb.fn.coalesce(eb.ref("excluded.phone"), eb.ref("user.phone"))`.
|
|
41
|
+
|
|
42
|
+
### 2. Guard the write itself, not just the earlier read
|
|
43
|
+
|
|
44
|
+
Put the eligibility predicate in the `UPDATE`'s `WHERE` and check how many rows
|
|
45
|
+
changed. The row is re-evaluated under its row lock, so a concurrent change is seen.
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// WRONG - status was 'pending' when we selected it; maybe not any more
|
|
49
|
+
await db.updateTable("invoice").set({ status: "sent" }).where("id", "=", id).execute();
|
|
50
|
+
|
|
51
|
+
// RIGHT - conditional update; 0 rows means we lost the race
|
|
52
|
+
const res = await db.updateTable("invoice").set({ status: "sent", sent_at: new Date() })
|
|
53
|
+
.where("id", "=", id).where("status", "=", "pending")
|
|
54
|
+
.executeTakeFirst();
|
|
55
|
+
if (res.numUpdatedRows === 0n) throw new ConflictError();
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The same applies to "never overwrite a final value": write
|
|
59
|
+
`ended_on: (eb) => eb.fn.coalesce("ended_on", eb.val(today))`, or filter
|
|
60
|
+
`.where("ended_on", "is", null)`, rather than setting it unconditionally.
|
|
61
|
+
|
|
62
|
+
### 3. When the decision spans rows: lock, then re-read
|
|
63
|
+
|
|
64
|
+
Invariants such as "at least one admin remains", "total allocated ≤ budget" or
|
|
65
|
+
"no overlapping booking" cannot be expressed as one conditional update. Lock a
|
|
66
|
+
row that every competing writer must also lock (usually the parent), then read
|
|
67
|
+
the state you decide on **after** the lock, inside the same transaction:
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
await db.transaction().execute(async (trx) => {
|
|
71
|
+
await trx.selectFrom("org").select("id").where("id", "=", orgId).forUpdate().execute();
|
|
72
|
+
// read AFTER the lock - a snapshot taken before it is stale
|
|
73
|
+
const admins = await trx.selectFrom("membership").select("user_id")
|
|
74
|
+
.where("org_id", "=", orgId).where("role", "=", "admin")
|
|
75
|
+
.where("deactivated_at", "is", null)
|
|
76
|
+
.execute();
|
|
77
|
+
if (admins.length <= 1) throw new ConflictError();
|
|
78
|
+
await trx.updateTable("membership").set({ role: "member" })
|
|
79
|
+
.where("org_id", "=", orgId).where("user_id", "=", userId).execute();
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Rules that make the lock actually work:
|
|
84
|
+
|
|
85
|
+
- **Every write path takes the same lock**: create, update, delete, imports,
|
|
86
|
+
background jobs, and any insert of a child row that references the locked
|
|
87
|
+
resource. A lock that one path skips serializes nothing.
|
|
88
|
+
- **When there is no natural row to lock**, use a transaction-scoped advisory
|
|
89
|
+
lock on a stable bigint key, again in every path. It is released at
|
|
90
|
+
commit/rollback:
|
|
91
|
+
```typescript
|
|
92
|
+
await trx.selectNoFrom((eb) => eb.fn("pg_advisory_xact_lock", [eb.val(key)]).as("locked")).execute();
|
|
93
|
+
```
|
|
94
|
+
- **With a join, lock only the intended table**: `.forUpdate()` alone emits
|
|
95
|
+
`FOR UPDATE`, which locks matching rows of *every* joined table. Pass the
|
|
96
|
+
table: `.forUpdate("order")` emits `for update of "order"`.
|
|
97
|
+
- **Lock several rows in a stable order** (`.orderBy("id")` on the locking
|
|
98
|
+
select, or sort ids before locking one by one); two batches locking the same
|
|
99
|
+
rows in different orders deadlock.
|
|
100
|
+
- **No slow external calls while holding locks** (HTTP, file downloads, LLM
|
|
101
|
+
calls). Fetch first, then open the transaction, lock, re-check, and write.
|
|
102
|
+
- Keyset paging (`where id > lastSeenId order by id`), not `offset`, for lists
|
|
103
|
+
that change between page requests; rows shift under an offset.
|
|
104
|
+
|
|
105
|
+
### 4. One transaction for all writes of one operation
|
|
106
|
+
|
|
107
|
+
If a parent and its children, or a record and its audit row, must exist together,
|
|
108
|
+
write them on the same `trx`. A helper that writes must take the executor as a
|
|
109
|
+
parameter instead of importing the global `db`, or it silently runs outside the
|
|
110
|
+
caller's transaction:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// RIGHT - callers pass db or trx
|
|
114
|
+
async function createDraft(executor: Kysely<DB>, input: DraftInput) { ... }
|
|
115
|
+
await db.transaction().execute(async (trx) => {
|
|
116
|
+
const draft = await createDraft(trx, input);
|
|
117
|
+
await createDraftLines(trx, draft.id, input.lines); // rolls back with the draft
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 5. A caught database error poisons the transaction
|
|
122
|
+
|
|
123
|
+
After any statement fails inside a PostgreSQL transaction, every later statement
|
|
124
|
+
fails with `current transaction is aborted, commands ignored until end of
|
|
125
|
+
transaction block` (25P02) until rollback. Catching the error in TypeScript and
|
|
126
|
+
carrying on does not help. To try something that may fail and continue, wrap it
|
|
127
|
+
in a savepoint, and savepoints exist only on a **controlled** transaction:
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
// db.transaction().execute(trx => ...) gives a Transaction: it has NO .savepoint(),
|
|
131
|
+
// and trx.transaction() throws "calling the transaction method for a Transaction is not supported".
|
|
132
|
+
const trx = await db.startTransaction().execute(); // ControlledTransaction
|
|
133
|
+
try {
|
|
134
|
+
const sp = await trx.savepoint("try_optional").execute();
|
|
135
|
+
try {
|
|
136
|
+
await sp.insertInto("tag").values(tag).execute();
|
|
137
|
+
await sp.releaseSavepoint("try_optional").execute();
|
|
138
|
+
} catch (e) {
|
|
139
|
+
await sp.rollbackToSavepoint("try_optional").execute(); // trx usable again
|
|
140
|
+
if ((e as { code?: string }).code !== "23505") throw e; // only the expected failure is optional
|
|
141
|
+
}
|
|
142
|
+
await trx.commit().execute();
|
|
143
|
+
} catch (e) {
|
|
144
|
+
await trx.rollback().execute();
|
|
145
|
+
throw e;
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Prefer avoiding the error instead (an `onConflict`, or checking that an optional
|
|
150
|
+
function or extension exists before calling it). A `where not exists` guard is not
|
|
151
|
+
a substitute: two concurrent inserts both see no row. Also,
|
|
152
|
+
when you do catch, catch narrowly: fall back on an expected error code only, and
|
|
153
|
+
rethrow timeouts and other database errors instead of returning an empty result.
|
|
154
|
+
Do not type the handle as `any`; that is how a missing `.savepoint()` reaches
|
|
155
|
+
production.
|
|
@@ -14,6 +14,19 @@ db.selectFrom("document").selectAll()
|
|
|
14
14
|
// .where("search_vector", "@@", sql`plainto_tsquery('english', ${userInput})`)
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
+
Two traps when you also highlight or re-check matches in TypeScript:
|
|
18
|
+
|
|
19
|
+
- **Positions clamp at 16383.** Every word past that position is stored as
|
|
20
|
+
16383, so phrase/proximity queries (`<->`, `phraseto_tsquery`, quoted
|
|
21
|
+
`websearch_to_tsquery` phrases) are unreliable on long documents. Use plain term
|
|
22
|
+
presence as the SQL prefilter and verify word order on the text separately.
|
|
23
|
+
- **Lexemes are normalized** (stemmed, lowercased, stop words removed). Do not
|
|
24
|
+
use a lexeme as a raw-text prefix or regex; build highlight patterns from the
|
|
25
|
+
user's words with the operator keywords (`or`, `and`, `-`) and stop words removed.
|
|
26
|
+
A literal pattern still misses stemmed matches (a search for `running` matches a
|
|
27
|
+
document that says `runs`); when highlights must agree with the matches, let
|
|
28
|
+
PostgreSQL produce them with `ts_headline` and the same configuration.
|
|
29
|
+
|
|
17
30
|
## Advanced Grouping (ROLLUP / CUBE / GROUPING SETS)
|
|
18
31
|
|
|
19
32
|
No builder exists — pass the grouping spec to `.groupBy()` as a `sql` fragment; the SELECT list stays typed. See [aggregations.ts](references/aggregations.ts).
|
|
@@ -147,6 +147,56 @@ with `ifExists`, so re-applying it after the others is a safe no-op). Verify the
|
|
|
147
147
|
ledger is a contiguous prefix after the DELETE, and prefer letting the deploy's own
|
|
148
148
|
migrate job re-apply rather than running migrations from a laptop against prod.
|
|
149
149
|
|
|
150
|
+
## Migration Safety on Tables That Already Have Data
|
|
151
|
+
|
|
152
|
+
**Kysely runs all pending migrations in one transaction** on PostgreSQL (unless
|
|
153
|
+
the migrator is given `disableTransactions: true`, which applies to every
|
|
154
|
+
migration). So every lock a migration takes is held until the *whole batch*
|
|
155
|
+
commits, and one failure rolls the whole batch back.
|
|
156
|
+
|
|
157
|
+
- **Constraints on existing tables: add `NOT VALID`, validate later.** A plain
|
|
158
|
+
`ADD CONSTRAINT ... CHECK`/`FOREIGN KEY` scans the whole table while holding a
|
|
159
|
+
lock that blocks writes (`ACCESS EXCLUSIVE` for a CHECK, which blocks reads too;
|
|
160
|
+
`SHARE ROW EXCLUSIVE` on both tables for a foreign key). `NOT VALID` skips the scan and still enforces the rule
|
|
161
|
+
for new writes; `VALIDATE CONSTRAINT` then needs only `SHARE UPDATE EXCLUSIVE`.
|
|
162
|
+
Kysely's `addCheckConstraint` has no `NOT VALID` option, so use `sql`, and put
|
|
163
|
+
the `VALIDATE` in a later migration that ships in a separate deploy (in the same
|
|
164
|
+
batch, the first statement's lock is still held). A database that missed the
|
|
165
|
+
first deploy (a preview, a restored copy) gets both in one batch, which is safe
|
|
166
|
+
but takes the long lock; where that matters, run it one migration at a time:
|
|
167
|
+
```typescript
|
|
168
|
+
// migration A
|
|
169
|
+
await sql`alter table "order" add constraint order_total_nonneg check (total >= 0) not valid`.execute(db);
|
|
170
|
+
// migration B, a later deploy
|
|
171
|
+
await sql`alter table "order" validate constraint order_total_nonneg`.execute(db);
|
|
172
|
+
```
|
|
173
|
+
`NOT VALID` is also how you add a rule while old rows still violate it: fix them,
|
|
174
|
+
then validate. Before adding a constraint, query for existing violations.
|
|
175
|
+
- **`CREATE INDEX CONCURRENTLY` cannot run inside a transaction**, so it fails in a
|
|
176
|
+
default Kysely migration. If you run it outside (a script, or a migrator with
|
|
177
|
+
transactions disabled), a failed build leaves an **INVALID** index behind, and a
|
|
178
|
+
retry with `IF NOT EXISTS` silently keeps the broken one. Check
|
|
179
|
+
`pg_index.indisvalid`, drop the invalid index, then retry the create. Without a
|
|
180
|
+
transaction, earlier statements of a failed migration stay applied while the
|
|
181
|
+
migration is not recorded, so keep such a migration to that one statement or
|
|
182
|
+
make every statement safe to run again (`IF NOT EXISTS`, `IF EXISTS`). Kysely
|
|
183
|
+
0.29.0 to 0.29.2 take the migration lock with `pg_advisory_xact_lock`, which
|
|
184
|
+
ends with its own statement when transactions are disabled, so two deploy jobs
|
|
185
|
+
can run the same migration at once: on those versions upgrade (0.29.3 and later
|
|
186
|
+
hold a session-level lock) or make sure only one job migrates at a time.
|
|
187
|
+
- **Deleting or merging rows:** find every foreign key that points at them and
|
|
188
|
+
repoint or preserve those rows first. Rows that hold user-entered data are safer
|
|
189
|
+
soft-retired (a `retired_at` column) than deleted when the state can reverse.
|
|
190
|
+
- **`down()` must not destroy data created after `up()`.** A `down` that drops a
|
|
191
|
+
table or cascade-deletes rows users have since edited is data loss. Reverse
|
|
192
|
+
exactly what `up` did (including rows an earlier migration had seeded), and when
|
|
193
|
+
a safe reversal is impossible, throw with an explanation instead of deleting.
|
|
194
|
+
- **Depend on an earlier migration only if yours sorts after it.** See the
|
|
195
|
+
ordering section above; re-stamp before merge when another branch landed a later
|
|
196
|
+
timestamp.
|
|
197
|
+
- **Commit the regenerated types with the migration**, and update tests, factories
|
|
198
|
+
and seeds that reference a dropped or renamed column in the same change.
|
|
199
|
+
|
|
150
200
|
## Schema Comments — Document in the DB, Not Just in Migration Source
|
|
151
201
|
|
|
152
202
|
Design notes written as `//` comments in a migration file are invisible the moment
|
|
@@ -233,3 +233,68 @@ import { jsonBuildObject } from "kysely/helpers/postgres";
|
|
|
233
233
|
)
|
|
234
234
|
```
|
|
235
235
|
|
|
236
|
+
|
|
237
|
+
### LIMIT, Counts and Filters: Cap Last
|
|
238
|
+
|
|
239
|
+
`LIMIT` runs after `WHERE`, `GROUP BY` and `ORDER BY` of *its own* query, but a
|
|
240
|
+
limit in a CTE, subquery, or a pre-fetch in TypeScript caps rows **before**
|
|
241
|
+
whatever you do next. The bug is always the same: the cap is applied to a set
|
|
242
|
+
that has not yet been filtered or aggregated.
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
// WRONG - newest 50 messages, THEN keep the ones with attachments: may return 0
|
|
246
|
+
const recent = await db.selectFrom("message").selectAll()
|
|
247
|
+
.orderBy("sent_at", "desc").limit(50).execute();
|
|
248
|
+
const withFiles = recent.filter((m) => m.attachment_count > 0);
|
|
249
|
+
|
|
250
|
+
// RIGHT - filter in SQL, then cap
|
|
251
|
+
await db.selectFrom("message").selectAll()
|
|
252
|
+
.where("attachment_count", ">", 0)
|
|
253
|
+
.orderBy("sent_at", "desc").limit(50).execute();
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- **Aggregate before you cap.** Per-group totals, minima ("next due date") and
|
|
257
|
+
"has any X" flags must be computed over all rows; apply the display limit to the
|
|
258
|
+
grouped result (or to a separate list query), never to the input rows.
|
|
259
|
+
- **Exclude ineligible rows (superseded, cancelled, inactive) before the batch
|
|
260
|
+
cap**, or they fill every batch and starve real work.
|
|
261
|
+
- **Count and list from one base query.** Build the filtered query once and derive
|
|
262
|
+
both, so a filter added to one cannot be missing from the other:
|
|
263
|
+
```typescript
|
|
264
|
+
const base = db.selectFrom("invoice").where("org_id", "=", orgId)
|
|
265
|
+
.$if(status !== undefined, (qb) => qb.where("status", "=", status!));
|
|
266
|
+
const [rows, { total }] = await Promise.all([
|
|
267
|
+
base.selectAll().orderBy("created_at", "desc").orderBy("id", "desc")
|
|
268
|
+
.limit(pageSize).offset(offset).execute(),
|
|
269
|
+
base.select((eb) => eb.cast<number>(eb.fn.countAll(), "integer").as("total"))
|
|
270
|
+
.executeTakeFirstOrThrow(),
|
|
271
|
+
]);
|
|
272
|
+
```
|
|
273
|
+
The same goes for a ranking subquery or `EXISTS` that supports a match check:
|
|
274
|
+
it must use the same match condition.
|
|
275
|
+
- **Exact match before fuzzy search.** Look up an exact identifier match directly
|
|
276
|
+
(or count exact matches over the full set) before running the limited candidate
|
|
277
|
+
search, or a limit can push the exact hit out of the candidates.
|
|
278
|
+
- **Don't `executeTakeFirst()` on a non-unique match.** If a name or partial key
|
|
279
|
+
can match several rows, fetch `.limit(2)` and treat two rows as ambiguous
|
|
280
|
+
instead of silently picking one.
|
|
281
|
+
- **A one-to-many join multiplies rows**, so `limit(n)` after the join caps
|
|
282
|
+
joined rows, not parents. Limit the parents in a subquery/CTE, or aggregate the
|
|
283
|
+
children with `jsonArrayFrom` (see [json-jsonb-arrays.md](json-jsonb-arrays.md)).
|
|
284
|
+
- **An empty list is not "no filter".** `.where("id", "in", [])` compiles to
|
|
285
|
+
`"id" in ()`, a syntax error. Branch in code: return `[]` early when the list is
|
|
286
|
+
empty (and do not fall back to a default filter), or skip the predicate only when
|
|
287
|
+
the filter was genuinely not supplied.
|
|
288
|
+
|
|
289
|
+
### Deterministic Ordering
|
|
290
|
+
|
|
291
|
+
- **`DESC` puts NULLs first** in PostgreSQL (NULL sorts as larger than every
|
|
292
|
+
value). For "newest first" on a nullable column, say so:
|
|
293
|
+
`.orderBy("paid_at", (ob) => ob.desc().nullsLast())`.
|
|
294
|
+
- **Add a unique tie-breaker** (`.orderBy("id")`) whenever you take the first row,
|
|
295
|
+
page, or pick one of several equal values; otherwise the choice can change
|
|
296
|
+
between runs.
|
|
297
|
+
- **Order inside the aggregate.** An `ORDER BY` in the subquery feeding
|
|
298
|
+
`json_agg` does not guarantee aggregate order. Put it on the aggregate:
|
|
299
|
+
`eb.fn.jsonAgg("line").orderBy("line.position")` emits
|
|
300
|
+
`json_agg("line" order by "line"."position")`.
|
|
@@ -44,3 +44,5 @@ db.selectFrom("job").selectAll()
|
|
|
44
44
|
// Wait behavior: .skipLocked() (skip) or .noWait() (error instead of blocking)
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
+
With a join, `.forUpdate()` locks rows of every joined table; pass the table (`.forUpdate("job")`). For which row to lock, re-reading after the lock, advisory locks and lock order, see [concurrency-and-transactions.md](concurrency-and-transactions.md).
|
|
48
|
+
|