@gallopsystems/agent-skills 1.6.1 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.6.1",
+  "version": "1.7.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.
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/select-where.ts

@@ -121,6 +121,59 @@ const complexFilter = await db
   )
   .execute();
 
+// ============================================
+// BETWEEN — use eb.between(), NOT the "between" operator
+// ============================================
+
+// CORRECT: eb.between(col, lo, hi) / eb.betweenSymmetric(col, lo, hi)
+const midPriced = await db
+  .selectFrom("product")
+  .selectAll()
+  .where((eb) => eb.between("price", "50", "100"))
+  .execute();
+// SQL: where "price" between $1 and $2
+
+// betweenSymmetric handles bounds given in either order (swaps if lo > hi)
+const inRange = await db
+  .selectFrom("product")
+  .selectAll()
+  .where((eb) => eb.betweenSymmetric("price", "100", "50"))
+  .execute();
+// SQL: where "price" between symmetric $1 and $2
+
+// GOTCHA: the string-operator form generates INVALID SQL — do NOT use it.
+//   .where("price", "between", ["50", "100"])
+// compiles to:  "price" between ($1, $2)   -- a tuple, which is a Postgres
+// syntax error ("between (a, b)" is not "between a and b"). Always use
+// eb.between() / eb.betweenSymmetric() instead.
+
+// ============================================
+// ANY (array / subquery membership)
+// ============================================
+
+// value = ANY(array_column) — type-safe with eb.fn.any
+const taggedPremium = await db
+  .selectFrom("product")
+  .selectAll()
+  .where((eb) => eb(eb.val("premium"), "=", eb.fn.any("tags")))
+  .execute();
+// SQL: where $1 = any("tags")
+
+// value = ANY(subquery)
+const ownersOfDogs = await db
+  .selectFrom("user")
+  .selectAll()
+  .where((eb) =>
+    eb(
+      eb.val("dog"),
+      "=",
+      eb.fn.any(
+        eb.selectFrom("pet").select("species").whereRef("pet.owner_id", "=", "user.id")
+      )
+    )
+  )
+  .execute();
+
 // ============================================
 // KEY PATTERNS SUMMARY
 // ============================================
@@ -143,4 +196,10 @@ const complexFilter = await db
 4. eb() inside where callbacks
    - eb("column", "=", value) creates comparison
    - Returns Expression<SqlBool> for composability
+
+5. BETWEEN: use eb.between(col, lo, hi) / eb.betweenSymmetric(...)
+   - The "between" string operator emits invalid SQL ("between (a, b)") — avoid.
+
+6. ANY: eb(eb.val(x), "=", eb.fn.any("array_col" | subquery))
+   - Membership test against an array column or a subquery result.
 */

package/plugins/kysely-postgres/skills/kysely-postgres/references/set-operations.ts

@@ -0,0 +1,97 @@
+/**
+ * Set Operations (UNION / INTERSECT / EXCEPT)
+ * Combine the rows of two compatible queries.
+ *
+ *   .union(q) / .unionAll(q)         -> UNION / UNION ALL
+ *   .intersect(q) / .intersectAll(q) -> INTERSECT / INTERSECT ALL
+ *   .except(q) / .exceptAll(q)       -> EXCEPT / EXCEPT ALL
+ *
+ * The plain forms remove duplicates; the *All forms keep them (and are cheaper).
+ * Both sides must select the same number of columns with compatible types and
+ * matching output names — align them with `as` aliases when they differ.
+ */
+import { db } from "./db";
+
+// ============================================
+// UNION — distinct rows from both queries
+// ============================================
+
+// Align column names with aliases so both branches produce the same shape.
+const contacts = await db
+  .selectFrom("user")
+  .select(["id", "email as contact"])
+  .union(db.selectFrom("supplier").select(["id", "contact_email as contact"]))
+  .execute();
+// SQL: select "id", "email" as "contact" from "user"
+//      union select "id", "contact_email" as "contact" from "supplier"
+
+// UNION ALL — keep duplicates (faster; no dedup pass)
+const allEvents = await db
+  .selectFrom("order")
+  .select(["id", "created_at"])
+  .unionAll(db.selectFrom("review").select(["id", "created_at"]))
+  .execute();
+
+// ============================================
+// INTERSECT — rows present in BOTH queries
+// ============================================
+
+const usersWhoAreAlsoReviewers = await db
+  .selectFrom("order")
+  .select("user_id")
+  .intersect(db.selectFrom("review").select("user_id"))
+  .execute();
+
+// INTERSECT ALL keeps duplicate matches
+const repeated = await db
+  .selectFrom("order")
+  .select("user_id")
+  .intersectAll(db.selectFrom("review").select("user_id"))
+  .execute();
+
+// ============================================
+// EXCEPT — rows in the FIRST query but not the second
+// ============================================
+
+// Users who placed an order but never wrote a review.
+const ordersWithoutReviews = await db
+  .selectFrom("order")
+  .select("user_id")
+  .except(db.selectFrom("review").select("user_id"))
+  .execute();
+
+const ordersWithoutReviewsKeepDupes = await db
+  .selectFrom("order")
+  .select("user_id")
+  .exceptAll(db.selectFrom("review").select("user_id"))
+  .execute();
+
+// ============================================
+// ORDERING THE COMBINED RESULT
+// ============================================
+
+// orderBy/limit after a set op apply to the whole combined result.
+const recentCombined = await db
+  .selectFrom("order")
+  .select(["id", "created_at"])
+  .unionAll(db.selectFrom("review").select(["id", "created_at"]))
+  .orderBy("created_at", "desc")
+  .limit(20)
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Both branches must select the same columns (count + compatible types) with
+   matching output names — use `as` to line them up.
+
+2. Plain forms dedupe; *All forms keep duplicates and skip the dedup pass.
+   Reach for unionAll/intersectAll/exceptAll unless you actually need DISTINCT.
+
+3. EXCEPT/INTERSECT are set-difference / set-intersection on whole rows.
+
+4. orderBy/limit chained after the set op apply to the combined result, not the
+   individual branches.
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/window-functions.ts

@@ -0,0 +1,294 @@
+/**
+ * Window Functions
+ * Ranking, value, and aggregate functions over OVER() windows.
+ *
+ * Two builders cover almost everything:
+ *   - eb.fn.agg<T>("NAME", [args]).over(...)  for named window functions
+ *     (ROW_NUMBER, RANK, LAG, ...) that have no dedicated helper
+ *   - eb.fn.sum/count/avg/min/max(col).over(...)  for windowed aggregates
+ *
+ * The OVER() body is built with a callback: (ob) => ob.partitionBy(...).orderBy(...)
+ * Call .over() with no callback for an empty OVER ().
+ *
+ * The one thing the builder CANNOT express is a frame clause
+ * (ROWS/RANGE/GROUPS BETWEEN) — see WINDOW FRAMES below.
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+
+// ============================================
+// RANKING FUNCTIONS
+// ============================================
+
+// ROW_NUMBER / RANK / DENSE_RANK — use eb.fn.agg (no dedicated helper)
+// Rank products by price within each category.
+const rankedProducts = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "id",
+    "name",
+    "category_id",
+    eb.fn
+      .agg<number>("ROW_NUMBER")
+      .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+      .as("row_num"),
+    eb.fn
+      .agg<number>("RANK")
+      .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+      .as("price_rank"),
+    eb.fn
+      .agg<number>("DENSE_RANK")
+      .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+      .as("dense_rank"),
+  ])
+  .execute();
+// SQL: ROW_NUMBER() over(partition by "category_id" order by "price" desc) as "row_num"
+
+// NTILE / PERCENT_RANK / CUME_DIST — NTILE takes an argument (use sql.lit)
+const productBuckets = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "id",
+    eb.fn
+      .agg<number>("NTILE", [sql.lit(4)])
+      .over((ob) => ob.orderBy("price", "desc"))
+      .as("price_quartile"),
+    eb.fn
+      .agg<number>("PERCENT_RANK")
+      .over((ob) => ob.orderBy("price", "desc"))
+      .as("pct_rank"),
+  ])
+  .execute();
+// SQL: NTILE(4) over(order by "price" desc) as "price_quartile"
+
+// ============================================
+// VALUE FUNCTIONS (LAG / LEAD / FIRST_VALUE / NTH_VALUE)
+// ============================================
+
+// LAG / LEAD — args: (column, offset?, default?). Wrap literals in sql.lit().
+// Type the result yourself; nullable unless you supply a default.
+const orderTrends = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "created_at",
+    "total_amount",
+    eb.fn
+      .agg<number | null>("LAG", ["total_amount", sql.lit(1)])
+      .over((ob) => ob.partitionBy("user_id").orderBy("created_at"))
+      .as("prev_amount"),
+    eb.fn
+      .agg<number | null>("LEAD", ["total_amount", sql.lit(1)])
+      .over((ob) => ob.partitionBy("user_id").orderBy("created_at"))
+      .as("next_amount"),
+    // With a default value (no nulls): LAG(total_amount, 1, 0)
+    eb.fn
+      .agg<number>("LAG", ["total_amount", sql.lit(1), sql.lit(0)])
+      .over((ob) => ob.partitionBy("user_id").orderBy("created_at"))
+      .as("prev_amount_or_zero"),
+  ])
+  .execute();
+// SQL: LAG("total_amount", 1, 0) over(partition by "user_id" order by "created_at") as "prev_amount_or_zero"
+
+// FIRST_VALUE / NTH_VALUE
+const categoryExtremes = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "id",
+    "category_id",
+    eb.fn
+      .agg<number>("FIRST_VALUE", ["price"])
+      .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+      .as("highest_in_category"),
+    eb.fn
+      .agg<number | null>("NTH_VALUE", ["price", sql.lit(2)])
+      .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+      .as("second_highest"),
+  ])
+  .execute();
+
+// ============================================
+// AGGREGATE WINDOWS (sum/count/avg/min/max .over())
+// ============================================
+
+// Empty OVER () — aggregate over the whole result set, no collapsing of rows
+const withGrandTotal = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "total_amount",
+    eb.fn.sum<number>("total_amount").over().as("grand_total"),
+  ])
+  .execute();
+// SQL: sum("total_amount") over() as "grand_total"
+
+// Running total — ORDER BY without a frame defaults to
+// "RANGE UNBOUNDED PRECEDING -> CURRENT ROW" (cumulative)
+const runningTotals = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "created_at",
+    "total_amount",
+    eb.fn
+      .sum<number>("total_amount")
+      .over((ob) => ob.orderBy("created_at"))
+      .as("running_total"),
+  ])
+  .execute();
+// SQL: sum("total_amount") over(order by "created_at") as "running_total"
+
+// Partition total + percent-of-partition (mix a window into a raw expression)
+const sharePerCategory = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "id",
+    "category_id",
+    "price",
+    eb.fn
+      .sum<number>("price")
+      .over((ob) => ob.partitionBy("category_id"))
+      .as("category_total"),
+    sql<number>`${eb.ref("price")} * 100.0 / ${eb.fn
+      .sum("price")
+      .over((ob) => ob.partitionBy("category_id"))}`.as("pct_of_category"),
+  ])
+  .execute();
+
+// ============================================
+// FILTER + DISTINCT IN WINDOWS (PostgreSQL)
+// ============================================
+
+// .filterWhere() composes with .over() — conditional windowed aggregation
+const activeCounts = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "user_id",
+    eb.fn
+      .countAll<number>()
+      .filterWhere("status", "=", "completed")
+      .over((ob) => ob.partitionBy("user_id"))
+      .as("completed_orders_for_user"),
+  ])
+  .execute();
+// SQL: count(*) filter(where "status" = $1) over(partition by "user_id")
+
+// COUNT(DISTINCT ...) OVER (...)
+const distinctStatuses = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "user_id",
+    eb.fn
+      .count<number>("status")
+      .distinct()
+      .over((ob) => ob.partitionBy("user_id"))
+      .as("distinct_statuses_for_user"),
+  ])
+  .execute();
+// SQL: count(distinct "status") over(partition by "user_id")
+
+// ============================================
+// WINDOW FRAMES (ROWS/RANGE BETWEEN) — RAW SQL REQUIRED
+// ============================================
+
+// Kysely's OverBuilder exposes ONLY partitionBy + orderBy. There is no frame
+// node in its AST at all (confirmed 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. So a frame clause must be written as raw SQL.
+//
+// You do NOT lose all type safety: interpolate eb.ref() for columns (validated)
+// and sql.lit() for bounds, and type the result with sql<T>. Only the function
+// name and the frame keywords are raw text.
+
+// Moving average over the last 3 rows
+const movingAverage = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "created_at",
+    "total_amount",
+    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"),
+  ])
+  .execute();
+// SQL: avg("total_amount") over ( order by "created_at" rows between 2 preceding and current row )
+
+// Cumulative sum with an explicit frame
+const cumulative = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    sql<number>`sum(${eb.ref("total_amount")}) over (
+      partition by ${eb.ref("user_id")}
+      order by ${eb.ref("created_at")}
+      rows between unbounded preceding and current row
+    )`.as("cumulative_sum"),
+  ])
+  .execute();
+
+// ============================================
+// COMMON PATTERNS
+// ============================================
+
+// Top-N per group: rank in a CTE, then filter in the outer query.
+// (You can't filter on a window alias in the same SELECT's WHERE — windows are
+// computed after WHERE — so the CTE/subquery wrapper is required.)
+const top3ProductsPerCategory = await db
+  .with("ranked", (db) =>
+    db
+      .selectFrom("product")
+      .select((eb) => [
+        "id",
+        "name",
+        "category_id",
+        "price",
+        eb.fn
+          .agg<number>("ROW_NUMBER")
+          .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+          .as("rn"),
+      ])
+  )
+  .selectFrom("ranked")
+  .selectAll()
+  .where("rn", "<=", 3)
+  .execute();
+
+// Percent of total (empty OVER () as the denominator)
+const pctOfTotal = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "id",
+    "price",
+    sql<number>`round(${eb.ref("price")} * 100.0 / ${eb.fn
+      .sum("price")
+      .over()}, 2)`.as("pct_of_total"),
+  ])
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Named window functions: eb.fn.agg<T>("ROW_NUMBER").over((ob) => ...)
+   - ROW_NUMBER, RANK, DENSE_RANK, NTILE, PERCENT_RANK, CUME_DIST
+   - LAG, LEAD, FIRST_VALUE, LAST_VALUE, NTH_VALUE
+   - Function arguments go in the array; wrap literals in sql.lit().
+
+2. Windowed aggregates: eb.fn.sum/count/avg/min/max(col).over((ob) => ...)
+   - .over() with no callback => OVER () over the whole result set.
+   - .filterWhere(...) and .distinct() compose with .over().
+
+3. OVER body: (ob) => ob.partitionBy(col | [cols]).orderBy(col, "desc")
+
+4. Frames (ROWS/RANGE BETWEEN) are NOT supported by the builder (issue #505).
+   Write the window as raw sql, keeping eb.ref() for columns and sql<T> for the
+   result type. Only the function name + frame keywords are raw.
+
+5. Filtering on a window result (e.g. row_number = 1) needs a CTE/subquery:
+   windows are computed after WHERE, so wrap and filter in the outer query.
+*/