@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.
Files changed (48) hide show
  1. package/README.md +24 -0
  2. package/package.json +1 -1
  3. package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
  4. package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
  5. package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
  6. package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
  7. package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
  8. package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
  9. package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
  10. package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
  11. package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
  12. package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
  13. package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
  14. package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
  15. package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
  16. package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
  17. package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
  18. package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
  19. package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
  20. package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
  21. package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
  22. package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
  23. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
  24. package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
  25. package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
  26. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
  27. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
  28. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
  29. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
  30. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
  31. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
  32. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
  33. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
  34. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
  35. package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
  36. package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
  37. package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
  38. package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
  39. package/plugins/pr-review/skills/pr-review/judge.md +29 -0
  40. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
  41. package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
  42. package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
  43. package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
  44. package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
  45. package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
  46. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
  47. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
  48. 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) — the eight pitfalls (raw `sql`, forgetting `.execute()`, `whereRef`, typed function returns, FK indexing, typed `sql` literals, DATE timezones, the `between` operator)
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).
@@ -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
+