@gallopsystems/agent-skills 1.6.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md

@@ -19,15 +19,19 @@ Use this skill when:
 
 For detailed examples, see these topic-focused reference files:
 
-- [select-where.ts](references/select-where.ts) - Basic SELECT patterns, WHERE clauses, AND/OR conditions
-- [joins.ts](references/joins.ts) - Simple joins, callback joins, subquery joins, cross joins
-- [aggregations.ts](references/aggregations.ts) - COUNT, SUM, AVG, GROUP BY, HAVING
+- [select-where.ts](references/select-where.ts) - Basic SELECT patterns, WHERE clauses, AND/OR, BETWEEN, ANY
+- [joins.ts](references/joins.ts) - Simple joins, callback joins, subquery joins, cross joins, lateral joins
+- [aggregations.ts](references/aggregations.ts) - COUNT, SUM, AVG, GROUP BY, HAVING, ROLLUP/CUBE/GROUPING SETS
+- [window-functions.ts](references/window-functions.ts) - ROW_NUMBER/RANK, LAG/LEAD, windowed aggregates, frames
 - [orderby-pagination.ts](references/orderby-pagination.ts) - ORDER BY, NULLS handling, DISTINCT, pagination
-- [ctes.ts](references/ctes.ts) - Common Table Expressions, multiple CTEs, recursive CTEs
+- [ctes.ts](references/ctes.ts) - Common Table Expressions, multiple CTEs, recursive CTEs, MATERIALIZED
+- [set-operations.ts](references/set-operations.ts) - UNION, INTERSECT, EXCEPT (and *All variants)
 - [json-arrays.ts](references/json-arrays.ts) - JSONB handling, array columns, jsonBuildObject, jsonAgg
 - [relations.ts](references/relations.ts) - jsonArrayFrom, jsonObjectFrom for nested data
+- [full-text-search.ts](references/full-text-search.ts) - tsvector/tsquery matching with @@, ranking
+- [locking.ts](references/locking.ts) - FOR UPDATE/SHARE, SKIP LOCKED, NOWAIT, job-queue pattern
 - [mutations.ts](references/mutations.ts) - INSERT, UPDATE, DELETE, UPSERT, INSERT FROM SELECT
-- [expressions.ts](references/expressions.ts) - CASE, $if, subqueries, eb.val/lit/not, standalone expressionBuilder
+- [expressions.ts](references/expressions.ts) - CASE, $if, subqueries, eb.val/lit/not, standalone eb, dynamic refs
 
 ## Core Principles
 
@@ -177,6 +181,9 @@ const user = await db.selectFrom("user").selectAll()
 .where("name", "like", "%search%")
 .where("deleted_at", "is", null)
 
+// BETWEEN - use eb.between(), NOT the "between" operator (see Pitfall #8)
+.where((eb) => eb.between("age", 18, 65))
+
 // Multiple conditions (chained = AND)
 .where("is_active", "=", true)
 .where("role", "=", "admin")
@@ -750,6 +757,115 @@ await db
   .executeTakeFirst();
 ```
 
+## Window Functions
+
+Two builders cover almost everything. See [window-functions.ts](references/window-functions.ts) for the full set.
+
+```typescript
+// Named window functions (no dedicated helper): eb.fn.agg<T>("NAME", [args])
+.select((eb) => [
+  eb.fn.agg<number>("ROW_NUMBER")
+    .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+    .as("rank"),
+  // LAG/LEAD args go in the array; wrap literals in sql.lit()
+  eb.fn.agg<number | null>("LAG", ["total_amount", sql.lit(1)])
+    .over((ob) => ob.partitionBy("user_id").orderBy("created_at"))
+    .as("prev_amount"),
+])
+
+// Windowed aggregates: .over() on sum/count/avg/min/max
+.select((eb) => [
+  eb.fn.sum<number>("total_amount").over((ob) => ob.orderBy("created_at")).as("running_total"),
+  eb.fn.avg<number>("price").over().as("grand_avg"),               // empty OVER ()
+  // .filterWhere() and .distinct() compose with .over()
+  eb.fn.countAll<number>().filterWhere("status", "=", "completed")
+    .over((ob) => ob.partitionBy("user_id")).as("completed_for_user"),
+])
+```
+
+**Filtering on a window result** (e.g. `row_number = 1`) needs a CTE/subquery — windows are computed after `WHERE`, so rank in a CTE then filter the outer query.
+
+**Window frames (`ROWS`/`RANGE BETWEEN`) require raw SQL.** Kysely's `OverBuilder` exposes only `partitionBy`/`orderBy` — there is no frame node in its AST at all (true through 0.28, 0.29, and `main`), and `.over()` rejects a raw `sql` argument. Frame support is the open feature request [kysely-org/kysely#505](https://github.com/kysely-org/kysely/issues/505). Write the frame as raw SQL but keep column refs typed via `eb.ref()`:
+
+```typescript
+// Only the function name + frame keywords are raw; columns stay validated.
+sql<number>`avg(${eb.ref("total_amount")}) over (
+  order by ${eb.ref("created_at")} rows between 2 preceding and current row
+)`.as("moving_avg_3")
+```
+
+## Set Operations (UNION / INTERSECT / EXCEPT)
+
+Combine two compatible queries. Plain forms dedupe; `*All` forms keep duplicates (and are cheaper). See [set-operations.ts](references/set-operations.ts).
+
+```typescript
+db.selectFrom("order").select("user_id")
+  .except(db.selectFrom("review").select("user_id"))   // orders, never reviewed
+  .execute();
+// .union/.unionAll, .intersect/.intersectAll, .except/.exceptAll
+// Both branches must select matching columns/names — align with `as` aliases.
+```
+
+## LATERAL Joins (PostgreSQL)
+
+A `LATERAL` subquery can reference earlier tables via `whereRef` and runs per outer row — the best tool for **top-N-per-group with a per-row LIMIT**. Use `*Lateral` + `join.onTrue()`. See [joins.ts](references/joins.ts).
+
+```typescript
+// Each user's 3 most recent orders
+db.selectFrom("user as u")
+  .innerJoinLateral(
+    (eb) => eb.selectFrom("order as o")
+      .select(["o.id", "o.total_amount", "o.created_at"])
+      .whereRef("o.user_id", "=", "u.id")
+      .orderBy("o.created_at", "desc").limit(3).as("recent"),
+    (join) => join.onTrue()
+  )
+  .select(["u.email", "recent.id", "recent.total_amount"])
+  .execute();
+// leftJoinLateral / crossJoinLateral also exist.
+```
+
+## Row Locking (FOR UPDATE / SKIP LOCKED)
+
+Pessimistic locks for read-modify-write and job queues (run inside a transaction). See [locking.ts](references/locking.ts).
+
+```typescript
+// Job-queue worker: grab the next pending jobs, skipping rows other workers hold
+db.selectFrom("job").selectAll()
+  .where("status", "=", "pending")
+  .orderBy("created_at").limit(10)
+  .forUpdate().skipLocked()
+  .execute();
+// Lock strength: forKeyShare < forShare < forNoKeyUpdate < forUpdate
+// Wait behavior: .skipLocked() (skip) or .noWait() (error instead of blocking)
+```
+
+## Full-Text Search (PostgreSQL)
+
+`@@` is a real Kysely operator — keep it as the operator and put the FTS functions on each side as `sql` fragments. See [full-text-search.ts](references/full-text-search.ts).
+
+```typescript
+db.selectFrom("document").selectAll()
+  .where(
+    sql`to_tsvector('english', ${sql.ref("body")})`,
+    "@@",
+    sql`websearch_to_tsquery('english', ${userInput})`,
+  )
+  .execute();
+// A stored tsvector column can be the typed LHS directly:
+// .where("search_vector", "@@", sql`plainto_tsquery('english', ${userInput})`)
+```
+
+## Advanced Grouping (ROLLUP / CUBE / GROUPING SETS)
+
+No builder exists — pass the grouping spec to `.groupBy()` as a `sql` fragment; the SELECT list stays typed. See [aggregations.ts](references/aggregations.ts).
+
+```typescript
+.groupBy(sql`rollup("status")`)                              // hierarchical subtotals
+.groupBy(sql`cube("order_id", "product_id")`)               // all combinations
+.groupBy(sql`grouping sets (("status"), ("user_id"), ())`)  // explicit sets
+```
+
 ## Migrations
 
 ### Configuration (kysely.config.ts)
@@ -980,6 +1096,19 @@ Now DATE columns return strings like `"2025-01-01"` and the frontend can parse/f
 
 **Note**: This applies to DATE columns only. TIMESTAMPTZ columns already handle timezones correctly by storing UTC and converting on read.
 
+### 8. Don't Use the `between` String Operator — It Emits Invalid SQL
+
+The `"between"` operator looks like it should work but compiles to a tuple, which is a PostgreSQL syntax error:
+
+```typescript
+// WRONG - compiles to: "age" between ($1, $2)  -> Postgres syntax error
+.where("age", "between", [18, 65])
+
+// RIGHT - use the expression-builder helpers
+.where((eb) => eb.between("age", 18, 65))            // "age" between $1 and $2
+.where((eb) => eb.betweenSymmetric("age", 65, 18))   // swaps bounds if needed
+```
+
 ## PostgreSQL Helpers Summary
 
 All helpers from `kysely/helpers/postgres`:

package/plugins/kysely-postgres/skills/kysely-postgres/references/aggregations.ts

@@ -3,6 +3,7 @@
  * COUNT, SUM, AVG, GROUP BY, HAVING
  */
 import { db } from "./db";
+import { sql } from "kysely";
 
 // ============================================
 // BASIC AGGREGATIONS
@@ -109,6 +110,44 @@ const groupsWithNoUnsigned = await db
   )
   .execute();
 
+// ============================================
+// ADVANCED GROUPING (ROLLUP / CUBE / GROUPING SETS)
+// ============================================
+
+// Kysely has no builder for these grouping constructs, so pass them to
+// .groupBy() as a sql`` fragment. The SELECT list stays fully typed; only the
+// grouping spec is raw. Rows with NULL in a grouped column are the subtotals.
+
+// ROLLUP — hierarchical subtotals + grand total
+// (type, region) -> (type) -> ()
+const rollup = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "status",
+    eb.fn.sum("total_amount").as("total"),
+  ])
+  .groupBy(sql`rollup("status")`)
+  .execute();
+// SQL: group by rollup("status")
+
+// CUBE — all combinations of the grouped columns
+const cube = await db
+  .selectFrom("order_item")
+  .select((eb) => [
+    "order_id",
+    "product_id",
+    eb.fn.sum("quantity").as("qty"),
+  ])
+  .groupBy(sql`cube("order_id", "product_id")`)
+  .execute();
+
+// GROUPING SETS — pick exactly which groupings to compute
+const sets = await db
+  .selectFrom("order")
+  .select((eb) => ["status", "user_id", eb.fn.sum("total_amount").as("total")])
+  .groupBy(sql`grouping sets (("status"), ("user_id"), ())`)
+  .execute();
+
 // ============================================
 // AGGREGATE FUNCTIONS REFERENCE
 // ============================================
@@ -164,4 +203,9 @@ const productStats = await db
    - Replaces CASE WHEN ... inside aggregates for conditional aggregation
    - Works as the first argument to .having() for filtered aggregate conditions
    - Example: eb.fn.count("id").filterWhere("status", "=", "active").as("active_count")
+
+6. ROLLUP / CUBE / GROUPING SETS (no builder):
+   - Pass to .groupBy() as a sql`` fragment: .groupBy(sql`rollup("a", "b")`)
+   - SELECT list stays typed; subtotal rows have NULL in the rolled-up columns
+   - Windowed aggregates (sum/count/... .over()) live in window-functions.ts
 */

package/plugins/kysely-postgres/skills/kysely-postgres/references/ctes.ts

@@ -132,6 +132,44 @@ const categoryHierarchy = await db
   .selectAll()
   .execute();
 
+// ============================================
+// MATERIALIZED / NOT MATERIALIZED (PostgreSQL)
+// ============================================
+
+// PostgreSQL can inline a CTE into the outer query (so the planner optimizes
+// across the boundary) or materialize it once into a temp result. Force either
+// with a name-builder callback as the first arg to .with():
+//   (cte) => cte("name").materialized()      -> WITH "name" AS MATERIALIZED (...)
+//   (cte) => cte("name").notMaterialized()   -> WITH "name" AS NOT MATERIALIZED (...)
+
+// MATERIALIZED: compute the CTE once and reuse it (good when it's expensive and
+// referenced multiple times, or to deliberately create an optimization fence).
+const expensiveOnce = await db
+  .with(
+    (cte) => cte("active_products").materialized(),
+    (db) =>
+      db
+        .selectFrom("product")
+        .select(["id", "name", "price"])
+        .where("is_active", "=", true)
+  )
+  .selectFrom("active_products")
+  .selectAll()
+  .execute();
+// SQL: with "active_products" as materialized (select ...) select * from ...
+
+// NOT MATERIALIZED: let the planner inline it (often lets index conditions from
+// the outer query push down into the CTE).
+const inlined = await db
+  .with(
+    (cte) => cte("recent_orders").notMaterialized(),
+    (db) =>
+      db.selectFrom("order").select(["id", "user_id"]).where("status", "=", "pending")
+  )
+  .selectFrom("recent_orders")
+  .selectAll()
+  .execute();
+
 // ============================================
 // KEY PATTERNS SUMMARY
 // ============================================
@@ -156,7 +194,12 @@ const categoryHierarchy = await db
    - Base case UNION ALL recursive case
    - Recursive case joins to the CTE itself
 
-5. When to use CTEs:
+5. MATERIALIZED / NOT MATERIALIZED (PostgreSQL):
+   - First arg becomes a callback: (cte) => cte("name").materialized()
+   - materialized(): compute once (expensive + reused, or optimization fence)
+   - notMaterialized(): let the planner inline it (push predicates down)
+
+6. When to use CTEs:
    - Complex multi-step aggregations
    - Reusing a subquery multiple times
    - Breaking down complex logic

package/plugins/kysely-postgres/skills/kysely-postgres/references/expressions.ts

@@ -240,6 +240,27 @@ const filteredProducts = await db
   .$if(conditions.length > 0, (qb) => qb.where((eb) => eb.and(conditions)))
   .execute();
 
+// ============================================
+// DYNAMIC COLUMN REFERENCES (db.dynamic)
+// ============================================
+
+// When a column name is only known at runtime (e.g. a user-chosen sort field),
+// db.dynamic.ref() injects it as a properly-quoted identifier — NOT as a value,
+// and without dropping to sql``. Validate the name against an allowlist first;
+// dynamic refs bypass the compile-time column check.
+const sortable = ["first_name", "last_name", "email"] as const;
+type Sortable = (typeof sortable)[number];
+
+async function getUsersSortedBy(column: Sortable) {
+  const { ref } = db.dynamic;
+  return db
+    .selectFrom("user")
+    .select(["id", "email"])
+    .orderBy(ref(column)) // runtime column, still quoted as an identifier
+    .execute();
+}
+// ref("first_name") -> "first_name" (an identifier), never a bound parameter
+
 // ============================================
 // KEY PATTERNS SUMMARY
 // ============================================
@@ -269,4 +290,9 @@ const filteredProducts = await db
 6. Expression<SqlBool>[] arrays:
    - Build conditions dynamically
    - Combine with eb.and([...]) or eb.or([...])
+
+7. Dynamic column references: db.dynamic.ref(name)
+   - For runtime-chosen columns (e.g. sort fields)
+   - Emits a quoted identifier, not a bound value
+   - Bypasses the compile-time column check — allowlist the name first
 */

package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-search.ts

@@ -0,0 +1,115 @@
+/**
+ * Full-Text Search (PostgreSQL)
+ * tsvector / tsquery matching with the @@ operator.
+ *
+ * Kysely has no dedicated FTS helpers, but @@ IS in its operator allowlist, so
+ * you build the document (to_tsvector / a tsvector column) and the query
+ * (to_tsquery family) with sql`` fragments and let @@ stay a typed operator.
+ * Keep columns type-checked via sql.ref(); only the FTS functions are raw.
+ *
+ * tsquery builders:
+ *   to_tsquery        - operator syntax: 'cat & dog', 'cat | dog', 'cat & !dog'
+ *   plainto_tsquery   - plain words, ANDed together (user-friendly)
+ *   websearch_to_tsquery - Google-style: quotes for phrases, - to exclude
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+
+// ============================================
+// MATCH ON A COMPUTED tsvector
+// ============================================
+
+// to_tsvector(...) @@ to_tsquery(...). @@ stays a real operator, so the LHS and
+// RHS are the only raw parts; the column ref is validated by sql.ref().
+const matches = await db
+  .selectFrom("document")
+  .selectAll()
+  .where(
+    sql`to_tsvector('english', ${sql.ref("body")})`,
+    "@@",
+    sql`to_tsquery('english', ${sql.lit("cat & dog")})`
+  )
+  .execute();
+// SQL: where to_tsvector('english', "body") @@ to_tsquery('english', 'cat & dog')
+
+// plainto_tsquery — turn free-text user input into an ANDed query safely
+const userSearch = async (term: string) =>
+  db
+    .selectFrom("document")
+    .selectAll()
+    .where(
+      sql`to_tsvector('english', ${sql.ref("body")})`,
+      "@@",
+      sql`plainto_tsquery('english', ${term})`
+    )
+    .execute();
+
+// websearch_to_tsquery — Google-style syntax ("phrase", -exclude, OR)
+const webSearch = async (term: string) =>
+  db
+    .selectFrom("document")
+    .selectAll()
+    .where(
+      sql`to_tsvector('english', ${sql.ref("body")})`,
+      "@@",
+      sql`websearch_to_tsquery('english', ${term})`
+    )
+    .execute();
+
+// ============================================
+// MATCH ON A STORED tsvector COLUMN (preferred)
+// ============================================
+
+// Production setups store a tsvector column (often a GENERATED column with a
+// GIN index) instead of computing to_tsvector at query time. Then @@ works
+// directly against the column name — fully typed on the left.
+const fastMatches = await db
+  .selectFrom("document")
+  .selectAll()
+  .where("search_vector", "@@", sql`to_tsquery('english', ${sql.lit("cat")})`)
+  .execute();
+// SQL: where "search_vector" @@ to_tsquery('english', 'cat')
+
+// ============================================
+// RELEVANCE RANKING (ts_rank)
+// ============================================
+
+// ts_rank has no helper — use sql<number> and order by the alias.
+const ranked = await db
+  .selectFrom("document")
+  .select((eb) => [
+    "id",
+    "title",
+    sql<number>`ts_rank(${eb.ref(
+      "search_vector"
+    )}, websearch_to_tsquery('english', ${"cat dog"}))`.as("rank"),
+  ])
+  .where(
+    "search_vector",
+    "@@",
+    sql`websearch_to_tsquery('english', ${"cat dog"})`
+  )
+  .orderBy("rank", "desc")
+  .limit(20)
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. @@ is a real Kysely operator — keep it as the operator and put the FTS
+   functions on either side as sql`` fragments. Don't wrap the whole predicate.
+
+2. Validate columns with sql.ref(); a stored tsvector column can be the typed
+   LHS directly (where("search_vector", "@@", ...)).
+
+3. Query builders by input source:
+   - to_tsquery: you control operator syntax (& | !).
+   - plainto_tsquery: untrusted plain words, ANDed.
+   - websearch_to_tsquery: Google-style user input.
+
+4. Rank with ts_rank/ts_rank_cd via sql<number>, then orderBy the alias.
+   For performance, store a tsvector column with a GIN index rather than
+   computing to_tsvector() per query.
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/joins.ts

@@ -183,6 +183,53 @@ const usersWithSummary = await db
   .where("u.role", "=", "admin")
   .execute();
 
+// ============================================
+// LATERAL JOINS (PostgreSQL)
+// ============================================
+
+// A LATERAL subquery can reference columns from earlier tables in the FROM
+// clause via whereRef — the subquery runs once per outer row. Use the
+// *Lateral methods + join.onTrue() (the join condition lives inside the
+// subquery, so the ON is just "true").
+
+// Top-N-per-group with a per-row LIMIT — the classic LATERAL use case.
+// Get each user's 3 most recent orders.
+const usersWithRecentOrders = await db
+  .selectFrom("user as u")
+  .innerJoinLateral(
+    (eb) =>
+      eb
+        .selectFrom("order as o")
+        .select(["o.id", "o.total_amount", "o.created_at"])
+        .whereRef("o.user_id", "=", "u.id") // references the outer row
+        .orderBy("o.created_at", "desc")
+        .limit(3)
+        .as("recent"),
+    (join) => join.onTrue()
+  )
+  .select(["u.email", "recent.id", "recent.total_amount", "recent.created_at"])
+  .execute();
+// SQL: from "user" as "u" inner join lateral (... where "o"."user_id" = "u"."id"
+//      order by "o"."created_at" desc limit $1) as "recent" on true
+
+// leftJoinLateral keeps outer rows even when the subquery returns nothing.
+const usersWithMaybeOrder = await db
+  .selectFrom("user as u")
+  .leftJoinLateral(
+    (eb) =>
+      eb
+        .selectFrom("order as o")
+        .select(["o.id", "o.total_amount"])
+        .whereRef("o.user_id", "=", "u.id")
+        .orderBy("o.created_at", "desc")
+        .limit(1)
+        .as("latest"),
+    (join) => join.onTrue()
+  )
+  .select(["u.email", "latest.id", "latest.total_amount"]) // null if no orders
+  .execute();
+// crossJoinLateral also exists (no ON clause at all).
+
 // ============================================
 // KEY PATTERNS SUMMARY
 // ============================================
@@ -203,4 +250,9 @@ const usersWithSummary = await db
 
 4. Cross joins: join.on(sql`true`, "=", sql`true`)
    - For joining unrelated data (like CTE summaries)
+
+5. Lateral joins: .innerJoinLateral((eb) => eb...whereRef(outer).as("x"),
+   (join) => join.onTrue())
+   - Subquery can reference outer rows; runs per row.
+   - Best tool for top-N-per-group with a per-row LIMIT.
 */

package/plugins/kysely-postgres/skills/kysely-postgres/references/locking.ts

@@ -0,0 +1,94 @@
+/**
+ * Row Locking (SELECT ... FOR ...)
+ * Pessimistic locks for read-modify-write and job-queue patterns.
+ *
+ * Lock strength (weakest -> strongest):
+ *   .forKeyShare()      -> FOR KEY SHARE
+ *   .forShare()         -> FOR SHARE
+ *   .forNoKeyUpdate()   -> FOR NO KEY UPDATE
+ *   .forUpdate()        -> FOR UPDATE
+ *
+ * Wait behavior (chain after a lock):
+ *   .skipLocked()       -> SKIP LOCKED   (ignore already-locked rows)
+ *   .noWait()           -> NOWAIT        (error instead of blocking)
+ */
+import { db } from "./db";
+
+// ============================================
+// BASIC LOCKS
+// ============================================
+
+// FOR UPDATE — lock the selected rows until the transaction ends.
+// Run inside a transaction; the lock is released on commit/rollback.
+const lockedOrder = await db
+  .selectFrom("order")
+  .selectAll()
+  .where("id", "=", 1)
+  .forUpdate()
+  .executeTakeFirst();
+// SQL: select * from "order" where "id" = $1 for update
+
+// FOR SHARE — allow concurrent reads-with-lock, block writers.
+const sharedRow = await db
+  .selectFrom("product")
+  .selectAll()
+  .where("id", "=", 1)
+  .forShare()
+  .executeTakeFirst();
+
+// ============================================
+// JOB QUEUE: FOR UPDATE SKIP LOCKED
+// ============================================
+
+// The canonical worker pattern: each worker grabs the next available job and
+// SKIP LOCKED steps over rows other workers already hold — no blocking, no
+// double-processing. Pair with a RETURNING update or do the work in the same tx.
+const nextJobs = await db
+  .selectFrom("job")
+  .selectAll()
+  .where("status", "=", "pending")
+  .orderBy("created_at")
+  .limit(10)
+  .forUpdate()
+  .skipLocked()
+  .execute();
+// SQL: ... for update skip locked
+
+// NOWAIT — fail fast instead of waiting for a contended lock
+const grabOrFail = await db
+  .selectFrom("order")
+  .selectAll()
+  .where("id", "=", 1)
+  .forUpdate()
+  .noWait()
+  .executeTakeFirst();
+// SQL: ... for update nowait
+
+// ============================================
+// WEAKER UPDATE LOCKS
+// ============================================
+
+// FOR NO KEY UPDATE — like FOR UPDATE but doesn't block FK reference inserts.
+// FOR KEY SHARE — weakest; blocks only key-changing updates/deletes.
+const noKeyLock = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("id", "=", 1)
+  .forNoKeyUpdate()
+  .executeTakeFirst();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Always lock inside a transaction — locks release at commit/rollback.
+
+2. Job queue: .forUpdate().skipLocked() with .limit() + ORDER BY.
+   Workers never block each other and never grab the same row.
+
+3. .noWait() throws on contention; .skipLocked() silently skips — pick per use.
+
+4. Lock strength: forKeyShare < forShare < forNoKeyUpdate < forUpdate.
+   Prefer the weakest lock that still prevents your race.
+*/