@gallopsystems/agent-skills 1.13.0 → 1.15.0

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

@@ -17,7 +17,21 @@ Use this skill when:
 
 ## Reference Files
 
-For detailed examples, see these topic-focused reference files:
+This skill is split into topic guides — read the [Core Principles](#core-principles) below, then open the guide matching what you're doing:
+
+- [expression-builder.md](references/expression-builder.md) — the ExpressionBuilder (`eb`) foundation, `eb.val` vs `eb.lit`, standalone `eb`, conditional expression arrays, string concatenation
+- [query-patterns.md](references/query-patterns.md) — SELECT, WHERE clauses, JOINs (incl. callback format), aggregations, ORDER BY, CTEs, JSON aggregation
+- [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
+- [window-functions.md](references/window-functions.md) — ROW_NUMBER/RANK, LAG/LEAD, windowed aggregates, frames
+- [set-lateral-locking.md](references/set-lateral-locking.md) — set operations (UNION/INTERSECT/EXCEPT), LATERAL joins, row locking (FOR UPDATE / SKIP LOCKED)
+- [full-text-and-grouping.md](references/full-text-and-grouping.md) — full-text search (tsvector/tsquery), advanced grouping (ROLLUP/CUBE/GROUPING SETS)
+- [migrations-and-codegen.md](references/migrations-and-codegen.md) — migrations (config, commands, file structure, column types, gotchas) and type generation
+- [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)
+- [helpers-and-extending.md](references/helpers-and-extending.md) — PostgreSQL helpers summary, `mergeAction`, custom helper functions, custom expression classes
+- [deep-types.md](references/deep-types.md) — fixing the "excessively deep types" error with `$assertType`
+- [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
+
+Runnable, copy-pasteable query examples live alongside as `.ts` files:
 
 - [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
@@ -35,1247 +49,10 @@ For detailed examples, see these topic-focused reference files:
 
 ## Core Principles
 
-1. **Prefer Kysely methods over raw SQL**: Almost everything you can do in SQL, you can do in Kysely without `sql``
+1. **Always use Kysely's query builder — never reach for raw `sql`**: Almost anything expressible in SQL is expressible type-safely through Kysely's methods and the ExpressionBuilder (`eb`); raw `sql`` throws away the type safety this stack depends on. Treat it as a true last resort — only when Kysely genuinely cannot express the query (and type the template literal when you must). Being unsure how to do something is the cue to check the reference guides above, **not** to drop to raw SQL.
 2. **Use the ExpressionBuilder (eb)**: The `eb` parameter in callbacks is the foundation of type-safe query building
 3. **Let TypeScript guide you**: If it compiles, it's likely correct SQL
 
-## ExpressionBuilder (eb) - The Foundation
-
-The `eb` parameter in select/where callbacks provides all expression methods:
-
-```typescript
-.select((eb) => [
-  eb.ref("column").as("alias"),                    // Column reference
-  eb.fn<string>("upper", [eb.ref("email")]),       // Function call (typed!)
-  eb.fn.count("id").as("count"),                   // Aggregate function
-  eb.fn.sum("amount").as("total"),                 // SUM
-  eb.fn.avg("rating").as("avgRating"),             // AVG
-  eb.fn.coalesce("nullable_col", eb.val(0)),       // COALESCE
-  eb.case().when("status", "=", "active")          // CASE expression
-    .then("Active").else("Inactive").end(),
-  eb("quantity", "*", eb.ref("unit_price")),       // Binary expression
-  eb.exists(subquery),                             // EXISTS
-  eb.not(expression),                              // NOT / negation
-  eb.cast(eb.val(" "), "text"),                    // Cast value to type
-  eb.and([...]),                                   // AND conditions
-  eb.or([...]),                                    // OR conditions
-])
-```
-
-### eb.val() vs eb.lit()
-
-```typescript
-// eb.val() - Creates a parameterized value ($1, $2, etc.) - PREFERRED for user input
-// Note: eb.val() alone may fail with "could not determine data type of parameter"
-// Use eb.cast(eb.val(...), "text") for string values in function arguments
-eb.val("user input")                    // Becomes: $1 with parameter "user input"
-eb.cast(eb.val("safe"), "text")         // Becomes: $1::text - always works
-
-// eb.lit() - Creates a literal value in SQL
-// ONLY accepts: numbers, booleans, null - NOT strings (throws "unsafe immediate value")
-eb.lit(1)             // Becomes: 1 (directly in SQL)
-eb.lit(true)          // Becomes: true
-eb.lit(null)          // Becomes: NULL
-
-// For string literals, use sql`` template instead
-sql`'active'`         // Becomes: 'active' (directly in SQL)
-sql<string>`'label'`  // Typed string literal
-```
-
-### Standalone ExpressionBuilder
-
-For reusable helpers outside query callbacks:
-
-```typescript
-import { expressionBuilder } from "kysely";
-import type { DB } from "./db.d.ts";
-
-// Create standalone expression builder
-const eb = expressionBuilder<DB, "user">();
-
-// Use in helper functions
-function isActiveUser() {
-  return eb.and([
-    eb("is_active", "=", true),
-    eb("role", "!=", "banned"),
-  ]);
-}
-```
-
-### Conditional Expressions with Arrays
-
-Build dynamic filters by collecting expressions:
-
-```typescript
-.where((eb) => {
-  const filters: Expression<SqlBool>[] = [];
-
-  if (firstName) filters.push(eb("first_name", "=", firstName));
-  if (lastName) filters.push(eb("last_name", "=", lastName));
-  if (minAge) filters.push(eb("age", ">=", minAge));
-
-  // Combine all filters with AND (empty array = no filter)
-  return eb.and(filters);
-})
-```
-
-## String Concatenation
-
-Use the `||` operator with `sql` template for clean string concatenation:
-
-```typescript
-// RECOMMENDED - Clean and type-safe with eb.ref()
-.select((eb) => [
-  sql<string>`${eb.ref("first_name")} || ' ' || ${eb.ref("last_name")}`.as("full_name"),
-])
-// Output: "first_name" || ' ' || "last_name"
-
-// ALTERNATIVE - Pure eb() chaining (parameterized literals)
-.select((eb) => [
-  eb(eb("first_name", "||", " "), "||", eb.ref("last_name")).as("full_name"),
-])
-// Output: "first_name" || $1 || "last_name"
-
-// VERBOSE - concat() function (avoid unless you need NULL handling)
-.select((eb) => [
-  eb.fn<string>("concat", [
-    eb.ref("first_name"),
-    eb.cast(eb.val(" "), "text"),
-    eb.ref("last_name"),
-  ]).as("full_name"),
-])
-```
-
-**Note**: `concat()` treats NULL as empty string, while `||` propagates NULL. Use `concat()` only when you need that NULL behavior.
-
-## Query Patterns
-
-### Basic SELECT
-
-```typescript
-// Select all columns
-const users = await db.selectFrom("user").selectAll().execute();
-
-// Select specific columns with aliases
-const users = await db
-  .selectFrom("user")
-  .select(["id", "email", "first_name as firstName"])
-  .execute();
-
-// Single row (returns T | undefined)
-const user = await db.selectFrom("user").selectAll()
-  .where("id", "=", userId).executeTakeFirst();
-
-// Single row that must exist (throws if not found)
-const user = await db.selectFrom("user").selectAll()
-  .where("id", "=", userId).executeTakeFirstOrThrow();
-```
-
-### WHERE Clauses
-
-```typescript
-// Equality, comparison, IN, LIKE
-.where("status", "=", "active")
-.where("price", ">", 100)
-.where("role", "in", ["admin", "manager"])
-.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")
-
-// OR conditions
-.where((eb) => eb.or([
-  eb("role", "=", "admin"),
-  eb("role", "=", "manager"),
-]))
-
-// Complex AND/OR
-.where((eb) => eb.and([
-  eb("is_active", "=", true),
-  eb.or([
-    eb("price", "<", 50),
-    eb("stock", ">", 100),
-  ]),
-]))
-```
-
-### JOINs
-
-```typescript
-// Inner join
-.innerJoin("order", "order.user_id", "user.id")
-
-// Left join
-.leftJoin("category", "category.id", "product.category_id")
-
-// Self-join with alias
-.selectFrom("category as c")
-.leftJoin("category as parent", "parent.id", "c.parent_id")
-
-// Multiple joins
-.innerJoin("order", "order.id", "order_item.order_id")
-.innerJoin("product", "product.id", "order_item.product_id")
-.innerJoin("user", "user.id", "order.user_id")
-```
-
-### Complex JOINs (Callback Format)
-
-Use the callback format when you need:
-- Multiple join conditions (composite keys)
-- Mixed column-to-column and column-to-literal comparisons
-- OR conditions within joins
-- Subquery joins (derived tables)
-
-**Join Builder Methods:**
-- `onRef(col1, op, col2)` - Column-to-column comparison
-- `on(col, op, value)` - Column-to-literal comparison
-- `on((eb) => ...)` - Complex expressions with OR logic
-
-```typescript
-// Multi-condition join (composite key + filter)
-.leftJoin("invoice as i", (join) =>
-  join
-    .onRef("sp.service_provider_id", "=", "i.service_provider_id")
-    .onRef("sp.year", "=", "i.year")
-    .onRef("sp.month", "=", "i.month")
-    .on("i.status", "!=", "invalidated")
-)
-
-// Join with OR conditions
-.leftJoin("order as o", (join) =>
-  join
-    .onRef("o.user_id", "=", "u.id")
-    .on((eb) =>
-      eb.or([
-        eb("o.status", "=", "completed"),
-        eb("o.status", "=", "shipped"),
-      ])
-    )
-)
-
-// Subquery join (derived table) - two callbacks
-.leftJoin(
-  (eb) =>
-    eb
-      .selectFrom("order")
-      .select((eb) => [
-        "user_id",
-        eb.fn.count("id").as("order_count"),
-        eb.fn.max("created_at").as("last_order_at"),
-      ])
-      .groupBy("user_id")
-      .as("order_stats"),  // MUST have alias!
-  (join) => join.onRef("order_stats.user_id", "=", "u.id")
-)
-
-// Cross join (always-true condition) - for joining aggregated CTEs
-.leftJoin("summary_cte", (join) =>
-  join.on(sql`true`, "=", sql`true`)
-)
-```
-
-### Aggregations
-
-```typescript
-.select((eb) => [
-  "status",
-  eb.fn.count("id").as("count"),
-  eb.fn.sum("total_amount").as("totalAmount"),
-  eb.fn.avg("total_amount").as("avgAmount"),
-])
-.groupBy("status")
-.having((eb) => eb.fn.count("id"), ">", 5)
-```
-
-#### FILTER (WHERE ...) on Aggregates
-
-PostgreSQL's `FILTER (WHERE ...)` clause is available on **all** aggregate function builders via `.filterWhere()`:
-
-```typescript
-.select((eb) => [
-  eb.fn.count("id").filterWhere("status", "=", "active").as("active_count"),
-  eb.fn.countAll().filterWhere("role", "!=", "banned").as("non_banned"),
-  eb.fn.sum("amount").filterWhere("type", "=", "credit").as("total_credits"),
-])
-
-// Also works as the first argument to .having()
-.having(
-  (eb) => eb.fn.countAll().filterWhere("status", "!=", "signed"),
-  "=",
-  0
-)
-```
-
-### ORDER BY
-
-```typescript
-// Simple ordering
-.orderBy("created_at", "desc")
-.orderBy("name", "asc")
-
-// NULLS FIRST / NULLS LAST - use order builder callback
-.orderBy("category_id", (ob) => ob.asc().nullsLast())
-.orderBy("priority", (ob) => ob.desc().nullsFirst())
-
-// Multiple columns - chain orderBy calls (array syntax is deprecated)
-.orderBy("category_id", "asc")
-.orderBy("price", "desc")
-.orderBy("name", "asc")
-```
-
-### CTEs (Common Table Expressions)
-
-Use CTEs for complex queries with multiple aggregation levels:
-
-```typescript
-const result = await db
-  .with("order_totals", (db) =>
-    db.selectFrom("order")
-      .innerJoin("user", "user.id", "order.user_id")
-      .select((eb) => [
-        "user.id as userId",
-        "user.email",
-        eb.fn.sum("order.total_amount").as("totalSpent"),
-        eb.fn.count("order.id").as("orderCount"),
-      ])
-      .groupBy(["user.id", "user.email"])
-  )
-  .selectFrom("order_totals")
-  .selectAll()
-  .orderBy("totalSpent", "desc")
-  .execute();
-```
-
-### JSON Aggregation (PostgreSQL)
-
-```typescript
-import { jsonBuildObject } from "kysely/helpers/postgres";
-// Note: jsonAgg is accessed via eb.fn.jsonAgg(), not imported
-
-.with("tasks", (db) =>
-  db.selectFrom("task")
-    .leftJoin("user", "user.id", "task.assignee_id")
-    .select((eb) => [
-      "task.job_id",
-      eb.fn.jsonAgg(
-        jsonBuildObject({
-          id: eb.ref("task.id"),
-          status: eb.ref("task.status"),
-          assignee: jsonBuildObject({
-            id: eb.ref("user.id"),
-            name: eb.fn<string>("concat", [
-              eb.ref("user.first_name"),
-              eb.cast(eb.val(" "), "text"),
-              eb.ref("user.last_name"),
-            ]),
-          }),
-        })
-      )
-      .filterWhere("task.id", "is not", null) // Filter nulls from left join
-      .as("tasks"),
-    ])
-    .groupBy("task.job_id")
-)
-```
-
-## JSON, JSONB, and Array Handling
-
-### JSONB Columns
-
-**NO `JSON.stringify` or `JSON.parse` needed!** The `pg` driver handles JSONB automatically:
-
-```typescript
-// INSERT - pass objects directly
-await db
-  .insertInto("user")
-  .values({
-    email: "test@example.com",
-    metadata: { preferences: { theme: "dark" }, count: 42 },
-  })
-  .execute();
-
-// UPDATE - pass objects directly
-await db
-  .updateTable("user")
-  .set({
-    metadata: { preferences: { theme: "light" } },
-  })
-  .where("id", "=", userId)
-  .execute();
-
-// READ - returns parsed object, not string
-const user = await db
-  .selectFrom("user")
-  .select(["id", "metadata"])
-  .executeTakeFirst();
-console.log(user.metadata.preferences.theme); // "dark" - already an object!
-```
-
-### Array Columns (text[], int[], etc.)
-
-**NO `JSON.stringify` needed for array columns!** The `pg` driver handles arrays natively:
-
-```typescript
-// INSERT with array - pass array directly
-await db
-  .insertInto("product")
-  .values({
-    name: "Product",
-    tags: ["phone", "electronics", "premium"], // Direct array!
-  })
-  .execute();
-
-// READ - returns as native JavaScript array
-const product = await db
-  .selectFrom("product")
-  .select(["name", "tags"])
-  .executeTakeFirst();
-console.log(product.tags); // ["phone", "electronics", "premium"]
-
-// UPDATE array
-await db
-  .updateTable("product")
-  .set({ tags: ["updated", "tags"] })
-  .where("id", "=", productId)
-  .execute();
-```
-
-### Querying Arrays
-
-```typescript
-// Array contains all values (@>) - operator works natively!
-.where("tags", "@>", sql`ARRAY['phone', 'premium']::text[]`)
-
-// Arrays overlap (&&) - operator works natively!
-.where("tags", "&&", sql`ARRAY['premium', 'basic']::text[]`)
-
-// Array contains value (ANY) - type-safe with eb.fn
-.where((eb) => eb(sql`${searchTerm}`, "=", eb.fn("any", [eb.ref("tags")])))
-// eb.ref("tags") validates column exists - eb.ref("invalid") would be a TS error
-```
-
-### Querying JSONB
-
-```typescript
-// Key exists (?) - operator works natively!
-.where("metadata", "?", "theme")
-
-// Any key exists (?|) - operator works natively!
-.where("metadata", "?|", sql`array['theme', 'language']`)
-
-// All keys exist (?&) - operator works natively!
-.where("metadata", "?&", sql`array['theme', 'notifications']`)
-
-// JSONB contains (@>) - operator works natively!
-.where("metadata", "@>", sql`'{"notifications": true}'::jsonb`)
-
-// Extract field as text (->> as operator) - type-safe!
-.where((eb) => eb(eb("metadata", "->>", "theme"), "=", "dark"))
-// eb("metadata", ...) validates column - eb("invalid", ...) would be TS error
-
-// Extract nested path (#>> still needs sql``)
-.where(sql`metadata#>>'{preferences,theme}'`, "=", "dark")
-
-// In SELECT - type-safe with eb()
-.select((eb) => [
-  eb("metadata", "->", "preferences").as("prefs"),   // Returns JSONB
-  eb("metadata", "->>", "theme").as("theme"),        // Returns text
-])
-// Nested paths still need sql``
-.select(sql`metadata#>'{preferences,theme}'`.as("t"))   // Nested as JSONB
-.select(sql<string>`metadata#>>'{a,b}'`.as("t"))        // Nested as text
-```
-
-### JSONPath (PostgreSQL 12+)
-
-```typescript
-// JSONPath match (@@) - works as native operator!
-.where("metadata", "@@", sql`'$.preferences.theme == "dark"'`)
-
-// JSONPath exists (@?) - NOT in Kysely's allowlist, use function instead
-// Use jsonb_path_exists() for type-safe column validation
-.where((eb) =>
-  eb.fn("jsonb_path_exists", [eb.ref("metadata"), sql`'$.preferences.theme'`])
-)
-// eb.ref("metadata") validates column - eb.ref("invalid") would be TS error
-
-// Extract with JSONPath - type-safe with eb.fn
-.select((eb) => [
-  "id",
-  eb.fn("jsonb_path_query_first", [eb.ref("metadata"), sql`'$.preferences.theme'`]).as("theme"),
-])
-
-// JSONPath with variables
-const searchValue = "dark";
-.where((eb) =>
-  eb.fn("jsonb_path_exists", [
-    eb.ref("metadata"),
-    sql`'$.preferences.theme ? (@ == $val)'`,
-    sql`jsonb_build_object('val', ${searchValue}::text)`,
-  ])
-)
-```
-
-### Conditional Queries ($if)
-
-Use `$if()` for runtime-conditional query modifications:
-
-```typescript
-const result = await db
-  .selectFrom("user")
-  .selectAll()
-  .$if(!includeInactive, (qb) => qb.where("is_active", "=", true))
-  .$if(includeMetadata, (qb) => qb.select("metadata"))
-  .$if(!!searchTerm, (qb) => qb.where("name", "like", `%${searchTerm}%`))
-  .$if(!!roleFilter, (qb) => qb.where("role", "in", roleFilter!))
-  .execute();
-```
-
-**Type behavior**: Columns added via `$if` become optional in the result type since inclusion isn't guaranteed at compile time.
-
-### Relations (jsonArrayFrom / jsonObjectFrom)
-
-Kysely is NOT an ORM - it uses PostgreSQL's JSON functions for nested data:
-
-```typescript
-import { jsonArrayFrom, jsonObjectFrom } from "kysely/helpers/postgres";
-
-// One-to-many: User with their orders
-const users = await db
-  .selectFrom("user")
-  .select((eb) => [
-    "user.id",
-    "user.email",
-    jsonArrayFrom(
-      eb
-        .selectFrom("order")
-        .select(["order.id", "order.status", "order.total_amount"])
-        .whereRef("order.user_id", "=", "user.id")
-        .orderBy("order.created_at", "desc")
-    ).as("orders"),
-  ])
-  .execute();
-
-// Many-to-one: Product with its category
-const products = await db
-  .selectFrom("product")
-  .select((eb) => [
-    "product.id",
-    "product.name",
-    jsonObjectFrom(
-      eb
-        .selectFrom("category")
-        .select(["category.id", "category.name"])
-        .whereRef("category.id", "=", "product.category_id")
-    ).as("category"),
-  ])
-  .execute();
-```
-
-**Critical: Use explicit `.select()` instead of `.selectAll()` with nested json helpers**
-
-When using `jsonObjectFrom` containing a nested `jsonArrayFrom` (or vice versa), using `selectAll("table")` breaks TypeScript's type inference. The result type becomes `unknown` or loses the nested structure, requiring `$castTo` to fix.
-
-```typescript
-// WRONG - selectAll() breaks type inference for nested json helpers
-const invoice = await db
-  .selectFrom("invoices")
-  .selectAll("invoices")
-  .select((eb) => [
-    jsonObjectFrom(
-      eb
-        .selectFrom("payment_plans")
-        .selectAll()  // ❌ This breaks type inference!
-        .select((eb2) => [
-          jsonArrayFrom(
-            eb2.selectFrom("installments").selectAll()
-              .whereRef("installments.plan_id", "=", "payment_plans.id")
-          ).as("installments"),
-        ])
-        .whereRef("payment_plans.invoice_id", "=", "invoices.id")
-    ).as("payment_plan"),  // Type is unknown or broken
-  ])
-  .executeTakeFirst();
-
-// RIGHT - explicit select() preserves type inference
-const invoice = await db
-  .selectFrom("invoices")
-  .selectAll("invoices")
-  .select((eb) => [
-    jsonObjectFrom(
-      eb
-        .selectFrom("payment_plans")
-        .select([  // ✅ Explicit columns!
-          "payment_plans.id",
-          "payment_plans.invoice_id",
-          "payment_plans.notes",
-          "payment_plans.created_at",
-        ])
-        .select((eb2) => [
-          jsonArrayFrom(
-            eb2.selectFrom("installments").selectAll()
-              .whereRef("installments.plan_id", "=", "payment_plans.id")
-          ).as("installments"),
-        ])
-        .whereRef("payment_plans.invoice_id", "=", "invoices.id")
-    ).as("payment_plan"),  // Type is properly inferred!
-  ])
-  .executeTakeFirst();
-```
-
-**Why this happens**: Kysely's type inference for nested json helpers relies on tracking the selected columns through the query chain. `selectAll()` returns all columns dynamically, which confuses TypeScript when combined with additional `.select()` calls that add nested json helpers. Using explicit column names gives TypeScript the static information it needs.
-
-**Rule of thumb**: When combining `jsonObjectFrom`/`jsonArrayFrom` with nested json helpers, always use explicit `.select([...columns])` instead of `.selectAll()` on the subquery containing the nested helper.
-
-### Reusable Helpers
-
-Create composable, type-safe helper functions using `Expression<T>`:
-
-```typescript
-import { Expression, sql } from "kysely";
-
-// Helper that takes and returns Expression<string>
-function lower(expr: Expression<string>) {
-  return sql<string>`lower(${expr})`;
-}
-
-// Use in queries
-.where(({ eb, ref }) => eb(lower(ref("email")), "=", email.toLowerCase()))
-```
-
-### Splitting Query Building and Execution
-
-Build queries without executing, useful for dynamic query construction:
-
-```typescript
-// Build query (doesn't execute)
-let query = db
-  .selectFrom("user")
-  .select(["id", "email"]);
-
-// Add conditions dynamically
-if (role) {
-  query = query.where("role", "=", role);
-}
-if (isActive !== undefined) {
-  query = query.where("is_active", "=", isActive);
-}
-
-// Execute when ready
-const results = await query.execute();
-
-// Or compile to SQL without executing
-const compiled = query.compile();
-console.log(compiled.sql);        // The SQL string
-console.log(compiled.parameters); // Bound parameters
-```
-
-### Subqueries
-
-```typescript
-// Subquery in WHERE
-.where("id", "in",
-  db.selectFrom("order").select("user_id").where("status", "=", "completed")
-)
-
-// EXISTS subquery
-.where((eb) =>
-  eb.exists(
-    db.selectFrom("review")
-      .select(sql`1`.as("one"))
-      .whereRef("review.product_id", "=", eb.ref("product.id"))
-  )
-)
-```
-
-### INSERT Operations
-
-```typescript
-// Single insert with returning
-const user = await db
-  .insertInto("user")
-  .values({ email: "test@example.com", first_name: "Test", last_name: "User" })
-  .returning(["id", "email"])
-  .executeTakeFirst();
-
-// Multiple rows
-await db
-  .insertInto("user")
-  .values([
-    { email: "a@example.com", first_name: "A", last_name: "User" },
-    { email: "b@example.com", first_name: "B", last_name: "User" },
-  ])
-  .execute();
-
-// Upsert (ON CONFLICT) - type-safe with expression builder
-await db
-  .insertInto("product")
-  .values({ sku: "ABC123", name: "Product", stock_quantity: 10 })
-  .onConflict((oc) =>
-    oc.column("sku").doUpdateSet((eb) => ({
-      stock_quantity: eb("product.stock_quantity", "+", eb.ref("excluded.stock_quantity")),
-    }))
-  )
-  .execute();
-// eb("product.invalid_column", ...) would be a TypeScript error!
-
-// Insert from SELECT
-await db
-  .insertInto("archive")
-  .columns(["user_id", "data", "archived_at"])
-  .expression(
-    db.selectFrom("user")
-      .select(["id", "metadata", sql`now()`.as("archived_at")])
-      .where("is_active", "=", false)
-  )
-  .execute();
-```
-
-### UPDATE Operations
-
-```typescript
-// Simple update
-await db
-  .updateTable("user")
-  .set({ is_active: false })
-  .where("id", "=", userId)
-  .execute();
-
-// Update with expression
-await db
-  .updateTable("product")
-  .set((eb) => ({
-    stock_quantity: eb("stock_quantity", "+", 10),
-  }))
-  .where("sku", "=", "ABC123")
-  .returning(["id", "stock_quantity"])
-  .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)
-
-```typescript
-import { PostgresDialect } from "kysely";
-import { defineConfig } from "kysely-ctl";
-import pg from "pg";
-
-export default defineConfig({
-  dialect: new PostgresDialect({
-    pool: new pg.Pool({
-      connectionString: process.env.DATABASE_URL,
-    }),
-  }),
-  migrations: {
-    migrationFolder: "src/db/migrations",
-  },
-  seeds: {
-    seedFolder: "src/db/seeds",
-  },
-});
-```
-
-### Migration Commands
-
-```bash
-npx kysely migrate:make migration-name  # Create migration
-npx kysely migrate:latest               # Run all pending migrations
-npx kysely migrate:down                 # Rollback last migration
-npx kysely seed make seed-name          # Create seed
-npx kysely seed run                     # Run all seeds
-```
-
-### Migration File Structure
-
-```typescript
-import type { Kysely } from "kysely";
-import { sql } from "kysely";
-
-// Always use Kysely<any> - migrations should be frozen in time
-export async function up(db: Kysely<any>): Promise<void> {
-  await db.schema
-    .createTable("user")
-    .addColumn("id", "bigint", (col) => col.primaryKey().generatedAlwaysAsIdentity())
-    .addColumn("email", "text", (col) => col.notNull().unique())
-    .addColumn("created_at", "timestamptz", (col) => col.notNull().defaultTo(sql`now()`))
-    .execute();
-
-  // IMPORTANT: Always index foreign key columns!
-  await db.schema.createIndex("idx_order_user_id").on("order").column("user_id").execute();
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  await db.schema.dropTable("user").execute();
-}
-```
-
-### Recommended Column Types
-
-```typescript
-// Primary keys: Use identity columns (SQL standard, prevents accidental ID conflicts)
-.addColumn("id", "bigint", (col) => col.primaryKey().generatedAlwaysAsIdentity())
-// NOT serial/bigserial - those allow manual ID inserts that can cause conflicts
-
-// Timestamps: Always use timestamptz (stores UTC, converts to client timezone)
-.addColumn("created_at", "timestamptz", (col) => col.notNull().defaultTo(sql`now()`))
-// NOT timestamp - loses timezone information
-
-// Money: Use numeric with precision (exact decimal, no floating point errors)
-.addColumn("price", "numeric(10, 2)", (col) => col.notNull())
-// NOT float/real/double precision - those have rounding errors
-
-// Strings: Use text (no length limit, same performance as varchar)
-.addColumn("name", "text", (col) => col.notNull())
-// varchar(n) only if you need a hard length constraint
-
-// JSON: Use jsonb (binary, indexable, faster queries)
-.addColumn("metadata", "jsonb")
-// NOT json - stored as text, no indexing, slower
-
-// Foreign keys: Create indexes manually (PostgreSQL doesn't auto-index FKs)
-await db.schema.createIndex("idx_order_user_id").on("order").column("user_id").execute();
-```
-
-### Data Type Gotchas
-
-```typescript
-// CORRECT - Space after comma in numeric types
-.addColumn("price", "numeric(10, 2)")
-
-// WRONG - Will fail with "invalid column data type"
-.addColumn("price", "numeric(10,2)")
-
-// For complex types, use sql template
-.addColumn("price", sql`numeric(10, 2)`)
-```
-
-### Migration Ordering Is Append-Only — Out-of-Order Timestamps Break Prod Deploys
-
-Kysely's migrator enforces a **strict append-only ledger**: it refuses to run any
-unexecuted migration whose timestamp sorts *before* the last-executed one
-(throwing `Corrupted migrations: previously executed migration ... is missing`).
-This bites when two branches each add a migration, and the one that merges *second*
-carries the *earlier* timestamp:
-
-```
-branch A merges first  → 1700000200000_drop_thing      (runs in prod)
-branch B merges second → 1700000100000_add_table       (timestamp is EARLIER)
-                       → 1700000100001_add_column
-```
-
-Prod has already recorded `...200000_drop_thing` as executed. On the next deploy
-the `migrate` job sees two pending migrations that sort *before* it, throws
-"Corrupted migrations", and **exits non-zero**. If migrations run as a pre-deploy
-job (common on PaaS like DigitalOcean App Platform), the failed job fails the whole
-deploy and the platform **auto-rolls-back to the previous image** — so prod silently
-stays on stale code and every subsequent deploy fails the same way. A self-reinforcing
-loop that looks like a deploy/token problem but is really a migration-ledger problem.
-
-**Prevent it:** before merging a long-lived branch, check whether `main` has merged
-any migration with a *later* timestamp than yours. If so, regenerate your migration's
-timestamp so it sorts last (`migrate:make` again, or rename the file) **before it
-merges** — only safe while the migration has not yet run in any shared DB. Never
-re-stamp a migration that prod has already executed; that forces it to re-run.
-
-**Fix it once prod is wedged:** reconcile the ledger so the executed set is a clean
-*prefix* again, then let the normal strict migrate job run. Do **not** reach for
-`allowUnorderedMigrations: true` — it works (kysely-ctl spreads the `migrations`
-config into the `Migrator`), but it permanently weakens the ordering guard to paper
-over one bad state. Instead, surgically remove the prematurely-recorded row from the
-migration ledger table (default `kysely_migration`):
-
-```sql
--- prod ledger has the later-timestamp migration recorded, blocking the two earlier ones
-DELETE FROM kysely_migration WHERE name = '1700000200000_drop_thing';
-```
-
-Now `add_table → add_column → drop_thing` are all pending in true timestamp order, and
-the next deploy's strict migrate job applies them cleanly. This only works when the
-removed migration is **idempotent to re-run** (e.g. a `dropTable`/`dropColumn` written
-with `ifExists`, so re-applying it after the others is a safe no-op). Verify the
-ledger is a contiguous prefix after the DELETE, and prefer letting the deploy's own
-migrate job re-apply rather than running migrations from a laptop against prod.
-
-## Type Generation
-
-Use `kysely-codegen` to generate types from your database:
-
-```bash
-npx kysely-codegen --url "postgresql://..." --out-file src/db/db.d.ts
-```
-
-Generated types use:
-- `Generated<T>` for auto-increment columns (optional on insert)
-- `ColumnType<Select, Insert, Update>` for different operation types
-- `Timestamp` for timestamptz columns
-
-## Common Pitfalls to Avoid
-
-### 1. Don't Resort to `sql`` When Kysely Has a Method
-
-```typescript
-// WRONG
-.select(sql`count(*)`.as("count"))
-
-// RIGHT
-.select((eb) => eb.fn.countAll().as("count"))
-
-// WRONG - raw SQL for FILTER (WHERE ...) on aggregates
-.having(sql<number>`count(*) filter (where status != 'signed')`, "=", 0)
-
-// RIGHT - .filterWhere() works on all aggregate function builders
-.having(
-  (eb) => eb.fn.countAll().filterWhere("status", "!=", "signed"),
-  "=",
-  0
-)
-```
-
-### 2. Don't Forget .execute()
-
-Queries are lazy - they won't run without calling an execute method:
-
-```typescript
-// This does nothing!
-db.selectFrom("user").selectAll();
-
-// This runs the query
-await db.selectFrom("user").selectAll().execute();
-```
-
-### 3. Use whereRef for Column-to-Column Comparisons
-
-```typescript
-// WRONG - Compares to string literal "other.column"
-.where("table.column", "=", "other.column")
-
-// RIGHT - Compares to actual column value
-.whereRef("table.column", "=", "other.column")
-```
-
-### 4. Type Your Function Returns
-
-```typescript
-// Better type inference
-eb.fn<string>("concat", [...])
-eb.fn<number>("length", [...])
-```
-
-### 5. PostgreSQL Does NOT Auto-Index Foreign Keys
-
-Always create indexes on foreign key columns:
-
-```typescript
-await db.schema.createIndex("idx_order_user_id").on("order").column("user_id").execute();
-```
-
-### 6. Always Type `sql` Template Literals
-
-When using `sql` template literals, the inferred type is `unknown` since Kysely can't know what the SQL expression resolves to. Always provide an explicit type:
-
-```typescript
-// WRONG - Returns unknown type
-eb.fn.coalesce("some_json_col", sql`'{}'::jsonb`)
-
-// RIGHT - Explicit type annotation
-eb.fn.coalesce("some_json_col", sql<Record<string, unknown>>`'{}'::jsonb`)
-
-// For complex types (e.g., JSON column from a CTE), use typeof with eb.ref
-// This ensures the fallback type matches the column type exactly
-eb.fn
-  .coalesce(
-    eb.ref("jobs_agg.jobs"),
-    sql<typeof eb.ref<"jobs_agg.jobs">>`'[]'::json`
-  )
-  .as("jobs")
-```
-
-**Key rule**: Every `sql` template literal should have a type parameter: `sql<TYPE>`. This ensures proper type inference throughout your query chain.
-
-### 7. DATE Columns Cause Timezone Issues
-
-By default, the `pg` driver converts DATE columns to JavaScript `Date` objects. This causes timezone problems:
-
-```
-Database: 2025-01-01 (just a date, no time)
-JS Date:  2025-01-01T00:00:00.000Z (interpreted as UTC midnight)
-User in NYC sees: Dec 31, 2024 (5 hours behind UTC)
-```
-
-**Solution: Parse DATE as string and let the frontend handle formatting**
-
-Step 1: Configure `pg` to return DATE as string:
-
-```typescript
-import pg from "pg";
-
-// Tell pg to return DATE columns as strings instead of Date objects
-const DATE_OID = 1082;
-pg.types.setTypeParser(DATE_OID, (val: string) => val);
-```
-
-Step 2: Update `kysely-codegen` to generate matching types:
-
-```bash
-npx kysely-codegen \
-  --url="$DATABASE_URL" \
-  --out-file=server/db/db.d.ts \
-  --dialect=postgres \
-  --date-parser=string
-```
-
-Now DATE columns return strings like `"2025-01-01"` and the frontend can parse/format respecting the user's timezone.
-
-**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`:
-
-```typescript
-import {
-  jsonArrayFrom,    // One-to-many relations (subquery → array)
-  jsonObjectFrom,   // Many-to-one relations (subquery → object | null)
-  jsonBuildObject,  // Build JSON object from expressions
-  mergeAction,      // Get action performed in MERGE query (PostgreSQL 15+)
-} from "kysely/helpers/postgres";
-```
-
-**Note**: `jsonAgg` is NOT imported - use `eb.fn.jsonAgg()` instead.
-
-### mergeAction (PostgreSQL 15+)
-
-For MERGE queries, get which action was performed:
-
-```typescript
-import { mergeAction } from "kysely/helpers/postgres";
-
-const result = await db
-  .mergeInto("person")
-  .using("person_updates", "person.id", "person_updates.id")
-  .whenMatched()
-  .thenUpdateSet({ name: eb.ref("person_updates.name") })
-  .whenNotMatched()
-  .thenInsertValues({ id: eb.ref("person_updates.id"), name: eb.ref("person_updates.name") })
-  .returning([mergeAction().as("action"), "id"])
-  .execute();
-
-// result[0].action is 'INSERT' | 'UPDATE' | 'DELETE'
-```
-
-## Extending Kysely
-
-### Custom Helper Functions
-
-Most extensions use the `sql` template tag with `RawBuilder<T>`:
-
-```typescript
-import { sql, RawBuilder } from "kysely";
-
-// Create a typed helper function
-function json<T>(value: T): RawBuilder<T> {
-  return sql`CAST(${JSON.stringify(value)} AS JSONB)`;
-}
-
-// Use in queries
-.select((eb) => [
-  json({ name: "value" }).as("data"),
-])
-```
-
-### Custom Expression Classes
-
-For reusable expressions, implement the `Expression<T>` interface:
-
-```typescript
-import { Expression, OperationNode, sql } from "kysely";
-
-class JsonValue<T> implements Expression<T> {
-  readonly #value: T;
-
-  constructor(value: T) {
-    this.#value = value;
-  }
-
-  get expressionType(): T | undefined {
-    return undefined;
-  }
-
-  toOperationNode(): OperationNode {
-    return sql`CAST(${JSON.stringify(this.#value)} AS JSONB)`.toOperationNode();
-  }
-}
-```
-
-**Note**: Module augmentation and inheritance-based extension are not recommended.
-
-## Handling "Excessively Deep Types" Error
-
-### The Problem
-
-Complex queries with many CTEs can overwhelm TypeScript's type instantiation limits:
-
-```
-Type instantiation is excessively deep and possibly infinite
-```
-
-This commonly occurs with 12+ `with` clauses, as Kysely's nested helper types accumulate.
-
-### The Solution: `$assertType`
-
-Use `$assertType` to simplify the type chain at intermediate points:
-
-```typescript
-const result = await db
-  .with("cte1", (qb) =>
-    qb.selectFrom("user")
-      .select(["id", "email"])
-      .$assertType<{ id: number; email: string }>()  // Simplify type here
-  )
-  .with("cte2", (qb) =>
-    qb.selectFrom("cte1")
-      .select("email")
-      .$assertType<{ email: string }>()
-  )
-  // ... more CTEs
-  .selectFrom("cteN")
-  .selectAll()
-  .execute();
-```
-
-**Key points**:
-- The asserted type must structurally match the actual type (full type safety preserved)
-- Apply to several intermediate `with` clauses in large queries
-- TypeScript cannot automatically simplify these types - explicit assertion is required
-
 ## Contributing Back
 
 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?"**