@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/cursor/db-deadlock-prevention/SKILL.md

@@ -0,0 +1,204 @@
+# Deadlock Prevention
+
+> Deadlocks occur when two or more transactions hold locks and each waits for a lock the other holds; prevention through consistent lock ordering and detection through timeout-based abort resolves them.
+
+## When to Use
+
+- Designing transactions that lock multiple rows or tables
+- Debugging `ERROR: deadlock detected` in application logs
+- Setting lock timeout strategies for concurrent workloads
+- Preventing deadlocks in batch operations that update many rows
+- Reviewing transaction code that acquires multiple locks
+
+## Instructions
+
+### Key Concepts
+
+**1. What Is a Deadlock**
+
+Transaction A locks row 1, Transaction B locks row 2. Then A tries to lock row 2 (blocked by B) and B tries to lock row 1 (blocked by A). Neither can proceed.
+
+```sql
+-- Session A                           -- Session B
+BEGIN;                                 BEGIN;
+UPDATE accounts SET balance = 100      UPDATE accounts SET balance = 200
+  WHERE id = 1;                          WHERE id = 2;
+-- A holds lock on row 1              -- B holds lock on row 2
+
+UPDATE accounts SET balance = 200      UPDATE accounts SET balance = 100
+  WHERE id = 2;                          WHERE id = 1;
+-- A waits for B's lock on row 2      -- B waits for A's lock on row 1
+                                       -- DEADLOCK! PostgreSQL detects and
+                                       -- aborts one transaction
+```
+
+**2. Lock Ordering (Primary Prevention)**
+
+All transactions that need to lock multiple rows must lock them in the same deterministic order. The simplest approach: sort by primary key ascending.
+
+```sql
+-- Safe: always lock lower ID first
+BEGIN;
+SELECT * FROM accounts
+  WHERE id IN (1, 2)
+  ORDER BY id
+  FOR UPDATE;
+-- Both rows locked in consistent order -- no deadlock possible
+
+UPDATE accounts SET balance = balance - 100 WHERE id = 1;
+UPDATE accounts SET balance = balance + 100 WHERE id = 2;
+COMMIT;
+```
+
+**3. Lock Timeout**
+
+Set a maximum wait time for locks. If the lock is not acquired within the timeout, the statement fails rather than waiting indefinitely.
+
+```sql
+SET lock_timeout = '5s';
+-- Any lock acquisition that takes longer than 5 seconds raises:
+-- ERROR: canceling statement due to lock timeout
+```
+
+Combine with retry logic: catch the timeout error, wait briefly, retry.
+
+**4. Deadlock Detection**
+
+PostgreSQL automatically detects deadlocks after `deadlock_timeout` (default 1 second). It builds a wait-for graph and looks for cycles. When a cycle is found, one transaction is aborted with `ERROR: deadlock detected`. The victim is chosen to minimize the amount of work rolled back.
+
+**5. Reducing Lock Scope**
+
+- Lock fewer rows: only lock the rows you actually need to modify
+- Lock for shorter duration: keep transactions short and focused
+- Use `FOR NO KEY UPDATE` instead of `FOR UPDATE` when not modifying key columns
+- Consider optimistic locking for low-contention resources (see `db-optimistic-locking`)
+
+### Worked Example
+
+Bank transfer that avoids deadlocks:
+
+```sql
+-- UNSAFE: lock order depends on transfer direction
+-- Transfer $100 from account 1 to account 2
+BEGIN;
+SELECT * FROM accounts WHERE id = 1 FOR UPDATE;  -- lock sender
+SELECT * FROM accounts WHERE id = 2 FOR UPDATE;  -- lock receiver
+UPDATE accounts SET balance = balance - 100 WHERE id = 1;
+UPDATE accounts SET balance = balance + 100 WHERE id = 2;
+COMMIT;
+
+-- If a concurrent transfer goes from account 2 to account 1,
+-- the lock order is reversed: deadlock!
+
+-- SAFE: always lock the lower account ID first
+CREATE OR REPLACE FUNCTION transfer(
+  from_id INT, to_id INT, amount NUMERIC
+) RETURNS VOID AS $$
+BEGIN
+  -- Lock both accounts in deterministic order
+  PERFORM * FROM accounts
+    WHERE id IN (from_id, to_id)
+    ORDER BY id
+    FOR UPDATE;
+
+  -- Now safe to update in any order
+  UPDATE accounts SET balance = balance - amount WHERE id = from_id;
+  UPDATE accounts SET balance = balance + amount WHERE id = to_id;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+The key insight: `ORDER BY id FOR UPDATE` guarantees both accounts are locked in ascending ID order regardless of which is the sender and which is the receiver.
+
+### Anti-Patterns
+
+1. **Locking rows in query-result order instead of a deterministic order.** If two queries return the same rows in different orders (e.g., one sorted by timestamp, another by name), deadlock is possible. Always use a deterministic sort key (primary key) for lock acquisition.
+
+2. **Not handling `ERROR: deadlock detected`.** When PostgreSQL aborts a transaction due to deadlock, the transaction is already rolled back. The application must retry the entire transaction, not just the failed statement.
+
+3. **Setting `deadlock_timeout` too high.** Transactions wait longer before detection, wasting connection pool slots. The default of 1 second is appropriate for most workloads. Lower it only if you have very short transactions and want faster detection.
+
+4. **Acquiring locks incrementally in a loop.** Locking one row at a time in a loop creates a window for deadlock between each lock acquisition. Lock all needed rows in one statement:
+
+```sql
+-- BAD: incremental locking
+FOR account_id IN SELECT unnest(account_ids) LOOP
+  SELECT * FROM accounts WHERE id = account_id FOR UPDATE;
+END LOOP;
+
+-- GOOD: batch locking in deterministic order
+SELECT * FROM accounts
+  WHERE id = ANY(account_ids)
+  ORDER BY id
+  FOR UPDATE;
+```
+
+### PostgreSQL Specifics
+
+- `deadlock_timeout` (default 1s): how long a transaction waits before PostgreSQL checks for deadlocks. The check itself is expensive, so this avoids checking on every lock wait.
+- `log_lock_waits = on`: logs any lock wait that exceeds `deadlock_timeout`, even if no deadlock occurs. Essential for identifying lock contention hotspots.
+- Monitor current locks: `SELECT * FROM pg_locks WHERE NOT granted;` shows all waiting lock requests.
+- Find blockers: `SELECT pg_blocking_pids(pid) FROM pg_stat_activity WHERE wait_event_type = 'Lock';`
+
+## Details
+
+### Advanced Topics
+
+**Deadlock detection algorithm:** PostgreSQL builds a wait-for graph where nodes are transactions and edges represent "waiting for lock held by." A cycle in this graph means deadlock. The victim is chosen to minimize rollback cost -- typically the transaction that has done the least work.
+
+**Advisory lock deadlocks:** `pg_advisory_lock` calls participate in PostgreSQL's deadlock detection. If Transaction A holds advisory lock 1 and waits for advisory lock 2, while Transaction B holds advisory lock 2 and waits for advisory lock 1, PostgreSQL detects and resolves the deadlock just like row-level deadlocks.
+
+**Batch operations:** Break large batch updates into smaller transactions to reduce the window during which locks are held:
+
+```sql
+-- Instead of one transaction updating 1 million rows:
+-- Process in batches of 1000
+DO $$
+DECLARE batch_ids INT[];
+BEGIN
+  FOR batch_ids IN
+    SELECT array_agg(id ORDER BY id) FROM (
+      SELECT id FROM large_table
+      WHERE needs_update = true
+      ORDER BY id LIMIT 1000
+    ) sub
+  LOOP
+    UPDATE large_table SET ... WHERE id = ANY(batch_ids);
+    -- Each batch is a separate transaction (implicit commit in DO block)
+  END LOOP;
+END $$;
+```
+
+### Engine Differences
+
+MySQL InnoDB detects deadlocks **immediately** (no timeout-based check like PostgreSQL) and rolls back the transaction with the fewest row modifications. This is generally faster detection but uses a different victim selection strategy.
+
+MySQL's **gap locking** creates additional deadlock scenarios not present in PostgreSQL. Two transactions inserting into the same index gap can deadlock even without explicit locking, because gap locks conflict with insert intention locks. This is a common surprise for developers migrating from PostgreSQL to MySQL.
+
+### Real-World Case Studies
+
+A payment processing system experienced 50+ deadlocks per hour during peak load. Investigation revealed the root cause: transfer transactions locked the sender account first, then the receiver. When two users simultaneously transferred money to each other (A to B, and B to A), the lock order reversed, causing deadlocks. The fix was straightforward: always lock the account with the lower ID first using `ORDER BY id FOR UPDATE`. This single change eliminated deadlocks entirely. Adding `log_lock_waits = on` to the PostgreSQL configuration provided ongoing monitoring to catch any new lock contention patterns.
+
+## Source
+
+- [PostgreSQL Deadlocks](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-DEADLOCKS)
+- Gray, J. & Reuter, A. "Transaction Processing: Concepts and Techniques" (1993)
+
+## Process
+
+1. Identify all transactions that lock multiple rows and establish a consistent lock ordering (ascending primary key).
+2. Replace incremental lock acquisition loops with batch `WHERE id = ANY(...) ORDER BY id FOR UPDATE` statements.
+3. Enable `log_lock_waits = on` and monitor for lock contention; set `lock_timeout` to prevent indefinite waits.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-pessimistic-locking, db-optimistic-locking, db-mvcc, db-isolation-levels, db-acid-properties
+
+## Success Criteria
+
+- Multi-row locking uses consistent ordering (ascending primary key)
+- Deadlock detection monitoring enabled (`log_lock_waits = on`)
+- Application code handles `ERROR: deadlock detected` with transaction retry logic
+- Batch operations broken into smaller transactions to reduce lock hold time

package/dist/agents/skills/cursor/db-deadlock-prevention/skill.yaml

@@ -0,0 +1,41 @@
+name: db-deadlock-prevention
+version: '1.0.0'
+description: Lock ordering, timeout strategies, deadlock detection, and resolution patterns
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-pessimistic-locking
+  - db-optimistic-locking
+  - db-mvcc
+  - db-isolation-levels
+  - db-acid-properties
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - deadlock
+  - lock-ordering
+  - deadlock-detection
+  - deadlock-timeout
+  - lock-timeout
+  - deadlock-prevention
+  - lock-graph
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/explicit-locking.html#LOCKING-DEADLOCKS
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/db-denormalization/SKILL.md

@@ -0,0 +1,176 @@
+# Denormalization
+
+> Intentionally introducing controlled redundancy into a normalized schema to eliminate expensive joins or aggregations, applied only after measured proof of a performance problem.
+
+## When to Use
+
+- Optimizing read-heavy workloads where join latency is the bottleneck
+- Building dashboard or reporting queries that aggregate across many tables
+- Reducing query complexity for frequently accessed data paths
+- Caching computed aggregates that are expensive to recalculate on every read
+- Designing CQRS read models separate from the write-optimized normalized schema
+
+## Instructions
+
+The cardinal rule: **normalize first, denormalize only when you have measured proof of a performance problem.** Denormalization trades write complexity and consistency risk for read performance.
+
+### Technique 1: Precomputed Columns
+
+Store a derived value directly on the parent row instead of computing it on every read.
+
+**Example -- order total stored on the orders table:**
+
+```sql
+ALTER TABLE orders ADD COLUMN total NUMERIC(10,2);
+
+-- Trigger to keep it consistent
+CREATE OR REPLACE FUNCTION update_order_total()
+RETURNS TRIGGER AS $$
+BEGIN
+  UPDATE orders
+  SET total = (
+    SELECT COALESCE(SUM(line_price * quantity), 0)
+    FROM order_items
+    WHERE order_id = COALESCE(NEW.order_id, OLD.order_id)
+  )
+  WHERE id = COALESCE(NEW.order_id, OLD.order_id);
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_order_total
+AFTER INSERT OR UPDATE OR DELETE ON order_items
+FOR EACH ROW EXECUTE FUNCTION update_order_total();
+```
+
+Now `SELECT id, total FROM orders WHERE customer_id = 42` avoids joining and summing order_items entirely.
+
+### Technique 2: Materialized Views
+
+Create a precomputed query result that refreshes on demand.
+
+```sql
+CREATE MATERIALIZED VIEW monthly_sales AS
+SELECT
+  date_trunc('month', o.order_date) AS month,
+  p.category,
+  COUNT(*) AS order_count,
+  SUM(oi.line_price * oi.quantity) AS revenue
+FROM orders o
+JOIN order_items oi ON o.id = oi.order_id
+JOIN products p ON oi.product_id = p.id
+GROUP BY 1, 2;
+
+CREATE UNIQUE INDEX idx_monthly_sales ON monthly_sales (month, category);
+
+-- Refresh without blocking reads
+REFRESH MATERIALIZED VIEW CONCURRENTLY monthly_sales;
+```
+
+Use materialized views when: the underlying data changes infrequently relative to reads, exact real-time accuracy is not required, and the query is expensive (multiple joins, aggregations).
+
+### Technique 3: Duplicated Columns for Join Avoidance
+
+Copy a frequently-read column into a table that would otherwise require a join.
+
+**Example -- customer name on orders:**
+
+```sql
+ALTER TABLE orders ADD COLUMN customer_name TEXT;
+
+-- Application-level sync on order creation
+INSERT INTO orders (customer_id, customer_name, order_date, total)
+SELECT 42, c.name, CURRENT_DATE, 0
+FROM customers c WHERE c.id = 42;
+```
+
+The consistency risk: if the customer changes their name, `orders.customer_name` becomes stale. Mitigation options:
+
+1. **Trigger-based sync:** A trigger on `customers` updates all related `orders` rows. Expensive for high-volume updates.
+2. **Accept staleness:** For historical records (invoices, receipts), the name at time of order is actually the correct business value.
+3. **Application-level sync:** Update both tables in the same transaction.
+
+### Technique 4: Summary Tables for Analytics
+
+Pre-aggregate data on a schedule for dashboard queries.
+
+```sql
+CREATE TABLE daily_metrics (
+  metric_date DATE PRIMARY KEY,
+  new_users   INT NOT NULL DEFAULT 0,
+  orders      INT NOT NULL DEFAULT 0,
+  revenue     NUMERIC(12,2) NOT NULL DEFAULT 0
+);
+
+-- Scheduled job (pg_cron or application cron) refreshes daily
+INSERT INTO daily_metrics (metric_date, new_users, orders, revenue)
+SELECT
+  CURRENT_DATE - 1,
+  (SELECT COUNT(*) FROM users WHERE created_at::date = CURRENT_DATE - 1),
+  (SELECT COUNT(*) FROM orders WHERE order_date = CURRENT_DATE - 1),
+  (SELECT COALESCE(SUM(total), 0) FROM orders WHERE order_date = CURRENT_DATE - 1)
+ON CONFLICT (metric_date) DO UPDATE SET
+  new_users = EXCLUDED.new_users,
+  orders = EXCLUDED.orders,
+  revenue = EXCLUDED.revenue;
+```
+
+### Anti-Patterns
+
+1. **Denormalizing without measurement.** "This join might be slow" is not evidence. Run `EXPLAIN ANALYZE`, measure actual query latency, and confirm the join is the bottleneck before duplicating data.
+2. **Denormalizing when an index would suffice.** Often a missing index produces the same symptoms as a costly join. Add the index first, measure again, then consider denormalization.
+3. **Treating denormalization as the default.** Starting with a denormalized schema makes future requirements unpredictable. Normalize first, denormalize the specific hot paths you identify.
+4. **Forgetting the consistency tax.** Every denormalized copy is a consistency obligation. If you cannot implement a reliable sync mechanism (trigger, application logic, scheduled refresh), do not denormalize.
+
+### Worked Example: E-Commerce Product Listing
+
+A product listing page shows product name, average rating, and review count. The normalized query joins `products`, `reviews`, and computes `AVG(rating)` and `COUNT(*)` per product. At 10M reviews, this query takes 800ms.
+
+Solution: Add `avg_rating NUMERIC(3,2)` and `review_count INT` columns to `products`. A trigger on `reviews` updates both columns. The listing query becomes a simple single-table scan at 3ms.
+
+## Details
+
+### Decision Framework
+
+1. **Measure.** Run `EXPLAIN ANALYZE` on the slow query. Identify whether the bottleneck is a join, an aggregation, or a sequential scan.
+2. **Index first.** If a missing index explains the cost, add it. Re-measure.
+3. **Choose the lightest denormalization.** Prefer materialized views (no schema change, easy to drop) over duplicated columns (schema change, trigger required) over summary tables (separate refresh logic).
+4. **Implement consistency.** For every denormalized copy, define when and how it refreshes. Document the staleness window.
+
+### PostgreSQL Materialized View Refresh Strategies
+
+- **Manual:** `REFRESH MATERIALIZED VIEW mv_name;` -- takes an exclusive lock, blocks reads during refresh.
+- **Concurrent:** `REFRESH MATERIALIZED VIEW CONCURRENTLY mv_name;` -- requires a unique index, does not block reads, but is slower.
+- **Scheduled:** Use `pg_cron` to refresh on a cadence: `SELECT cron.schedule('0 * * * *', 'REFRESH MATERIALIZED VIEW CONCURRENTLY monthly_sales');`
+- **Application-triggered:** Refresh after a batch write completes. Best when writes are infrequent and bursty.
+
+### MySQL Callout
+
+MySQL does not support materialized views natively. The common workaround is a regular table populated by a scheduled event or application logic. MySQL also lacks `CONCURRENTLY` refresh semantics -- refreshing a surrogate materialized view requires either a full table swap (rename trick) or accepting a lock during the refresh window.
+
+### Real-World Case Study: Social Media Feed
+
+A social platform normalized posts, likes, comments, and shares into separate tables. The home feed query joined 5 tables with aggregations, taking 2+ seconds at scale. The team added a `feed_items` denormalized table: one row per post with precomputed `like_count`, `comment_count`, `share_count`, and `author_name`. Triggers on each source table kept the feed current. Feed query latency dropped to 15ms. The consistency tax: 4 triggers, one maintenance job for orphan cleanup, and a monthly audit query to detect drift.
+
+## Source
+
+- [PostgreSQL Materialized Views](https://www.postgresql.org/docs/current/rules-materializedviews.html)
+- Kleppmann, M. "Designing Data-Intensive Applications" (2017), Chapter 3
+- PostgreSQL Wiki: Materialized View Refresh Strategies
+
+## Process
+
+1. Read the techniques and decision framework in this document.
+2. Measure the actual query performance to confirm a denormalization need exists.
+3. Apply the lightest denormalization technique that solves the measured problem, and implement the consistency mechanism.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-first-normal-form, db-second-normal-form, db-third-normal-form
+
+## Success Criteria
+
+- Denormalization is applied only to measured performance bottlenecks, not as a default design pattern.
+- Every denormalized copy has a documented consistency mechanism (trigger, application sync, or scheduled refresh).

package/dist/agents/skills/cursor/db-denormalization/skill.yaml

@@ -0,0 +1,38 @@
+name: db-denormalization
+version: '1.0.0'
+description: When and how to intentionally denormalize for performance, read-heavy patterns, and materialized views
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-first-normal-form
+  - db-second-normal-form
+  - db-third-normal-form
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - denormalization
+  - materialized-view
+  - read-performance
+  - redundant-data
+  - caching
+  - CQRS
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/rules-materializedviews.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/db-document-in-relational/SKILL.md

@@ -0,0 +1,225 @@
+# Document Data in Relational Databases
+
+> Using JSONB columns to store semi-structured data alongside relational tables, with indexing strategies and guidelines for when to embed vs normalize.
+
+## When to Use
+
+- User preferences and application settings that vary per user
+- API response caching where the response structure varies
+- Form builder configurations with dynamic field sets
+- Product attributes that vary by type (see also db-entity-attribute-value)
+- Any data where the schema varies per row but relational integrity matters for core fields
+
+## Instructions
+
+### Key Concepts
+
+PostgreSQL JSONB stores binary JSON -- it supports indexing, containment checks, and path queries. The key design decision is **when to embed in JSONB vs when to normalize:**
+
+**Embed in JSONB when:**
+
+- Data is read and written as a unit (e.g., user settings blob)
+- No cross-row queries are needed on the embedded data
+- Schema varies per row (different products have different attributes)
+- No referential integrity is needed for embedded data
+
+**Normalize into relational columns when:**
+
+- Data is queried independently or appears in WHERE/JOIN clauses
+- FK constraints are needed
+- Data participates in JOINs with other tables
+- 1:N relationships that grow unbounded (avoid arrays in JSONB)
+
+**The hybrid model** -- relational columns for queryable/constrained fields, JSONB for flexible/varying fields:
+
+```sql
+CREATE TABLE products (
+  id          serial PRIMARY KEY,
+  name        varchar NOT NULL,
+  price       numeric(10,2) NOT NULL,
+  category_id int REFERENCES categories(id),
+  attrs       jsonb DEFAULT '{}'
+);
+```
+
+Core fields (`name`, `price`, `category_id`) are relational -- type-safe, constrained, indexable. Varying fields (`attrs`) are JSONB -- flexible, no schema migration needed.
+
+**Indexing strategies:**
+
+```sql
+-- GIN index for containment/existence queries (@>, ?, ?&, ?|)
+CREATE INDEX idx_products_attrs ON products USING gin (attrs);
+
+-- Expression index for specific frequently-queried paths
+CREATE INDEX idx_products_color ON products ((attrs->>'color'));
+```
+
+### Worked Example
+
+E-commerce product catalog with type-varying attributes:
+
+```sql
+-- Products with different attribute sets
+INSERT INTO products (name, price, category_id, attrs) VALUES
+  ('Running Shoe', 129.99, 1, '{"color": "red", "size": "10", "material": "mesh"}'),
+  ('LED Bulb', 8.99, 2, '{"wattage": 60, "color_temp": "warm", "lumens": 800}'),
+  ('Cotton T-Shirt', 24.99, 3, '{"color": "blue", "size": "L", "fabric": "100% cotton"}');
+```
+
+**Containment query (uses GIN index):**
+
+```sql
+SELECT name, price FROM products
+WHERE attrs @> '{"color": "red"}';
+-- Returns: Running Shoe
+```
+
+**Path query (uses expression index):**
+
+```sql
+SELECT name, price FROM products
+WHERE attrs->>'color' = 'blue';
+-- Returns: Cotton T-Shirt
+```
+
+**Aggregation on JSON field:**
+
+```sql
+SELECT attrs->>'color' AS color, count(*)
+FROM products
+WHERE attrs ? 'color'
+GROUP BY attrs->>'color';
+```
+
+**EXPLAIN ANALYZE demonstrating index usage:**
+
+```sql
+EXPLAIN ANALYZE SELECT * FROM products WHERE attrs @> '{"color": "red"}';
+-- Bitmap Index Scan on idx_products_attrs
+--   Recheck Cond: (attrs @> '{"color": "red"}'::jsonb)
+```
+
+Without the GIN index, this query degrades to a sequential scan on every row.
+
+### Anti-Patterns
+
+1. **Storing entire entity as JSONB when most fields are known and stable.** You lose type safety, constraints, and query efficiency. Use relational columns for stable fields.
+2. **Deeply nested JSONB structures (3+ levels).** Deep nesting makes queries unreadable (`attrs->'specs'->'dimensions'->'width'`) and un-indexable at deep paths.
+3. **Using JSON instead of JSONB.** The `json` type preserves whitespace and key ordering but cannot be indexed. Always use `jsonb` unless you need exact text preservation.
+4. **JSONB columns in JOIN conditions.** Terrible performance without expression indexes. If a JSON field participates in JOINs, extract it to a relational column.
+5. **JSONB documents larger than 1MB per row.** Large documents cause TOAST overhead, slow updates, and memory pressure. Normalize large structures into relational tables.
+
+### PostgreSQL Specifics
+
+**JSONB operators:**
+
+| Operator | Purpose             | Example                                        |
+| -------- | ------------------- | ---------------------------------------------- | -------- | ------------------------- |
+| `->`     | Get element as JSON | `attrs->'color'` returns `"red"` (with quotes) |
+| `->>`    | Get element as text | `attrs->>'color'` returns `red` (no quotes)    |
+| `@>`     | Contains            | `attrs @> '{"color":"red"}'`                   |
+| `?`      | Key exists          | `attrs ? 'color'`                              |
+| `?&`     | All keys exist      | `attrs ?& array['color','size']`               |
+| `?       | `                   | Any key exists                                 | `attrs ? | array['color','wattage']` |
+
+**GIN index operator classes:**
+
+- `jsonb_ops` -- supports all operators, larger index size
+- `jsonb_path_ops` -- supports only `@>`, but 2-3x smaller index
+
+```sql
+-- Use jsonb_path_ops when only containment queries are needed
+CREATE INDEX ON products USING gin (attrs jsonb_path_ops);
+```
+
+**SQL/JSON path queries** (PostgreSQL 12+):
+
+```sql
+SELECT * FROM products
+WHERE jsonb_path_exists(attrs, '$.color ? (@ == "red")');
+```
+
+## Details
+
+### Advanced Topics
+
+**Generated columns from JSONB** for computed relational columns:
+
+```sql
+ALTER TABLE products
+ADD COLUMN color varchar
+GENERATED ALWAYS AS (attrs->>'color') STORED;
+
+-- Now indexable and queryable as a regular column
+CREATE INDEX idx_products_color_col ON products (color);
+```
+
+Generated columns are automatically updated when `attrs` changes. Use this to "promote" frequently queried JSONB fields to relational columns.
+
+**Partial indexes on JSONB paths:**
+
+```sql
+CREATE INDEX idx_products_wattage ON products ((attrs->>'wattage'))
+WHERE attrs ? 'wattage';
+```
+
+Only indexes rows that have the `wattage` key -- smaller and faster for sparse attributes.
+
+**Partial updates with jsonb_set:**
+
+```sql
+-- Update a single key without rewriting the entire JSONB value
+UPDATE products
+SET attrs = jsonb_set(attrs, '{color}', '"green"')
+WHERE id = 1;
+```
+
+This is more efficient than replacing the entire `attrs` value, especially for large documents.
+
+**TOAST storage:** JSONB values exceeding ~2KB are compressed and stored out-of-line. Very large JSONB values (100KB+) incur TOAST overhead on every read. Monitor with `SELECT pg_column_size(attrs) FROM products ORDER BY 1 DESC LIMIT 10;`.
+
+### Engine Differences
+
+MySQL 5.7+ supports a `JSON` column type but lacks JSONB:
+
+- MySQL requires generated columns with B-tree indexes for JSON path queries:
+
+```sql
+ALTER TABLE products
+ADD COLUMN color varchar(50)
+GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(attrs, '$.color'))) VIRTUAL;
+CREATE INDEX idx_color ON products(color);
+```
+
+- MySQL lacks GIN indexes and containment operators (`@>`)
+- MySQL multi-valued indexes (8.0.17+) can index JSON arrays: `CREATE INDEX idx_tags ON products ((CAST(attrs->'$.tags' AS UNSIGNED ARRAY)));`
+- MySQL `JSON_TABLE` (8.0+) flattens JSON to rows for complex queries
+- MySQL `JSON_CONTAINS()` is the closest equivalent to PostgreSQL's `@>` but cannot use specialized indexes
+
+### Real-World Case Studies
+
+**Multi-tenant SaaS platform with custom fields per tenant.** Originally used EAV (Entity-Attribute-Value) with 100M rows across 500 tenants. Cross-field queries ("all contacts where region = East AND tier = Enterprise") took 30+ seconds due to self-joins. Migrated to a JSONB `custom_fields` column with a GIN index. Same queries now complete in 15ms. Storage reduced 60% (one row per entity vs N rows per entity in EAV). For the 5 most-queried custom fields per tenant, added expression indexes that dropped those specific queries to under 3ms.
+
+## Source
+
+- [PostgreSQL JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)
+- [PostgreSQL JSON Functions](https://www.postgresql.org/docs/current/functions-json.html)
+
+## Process
+
+1. Read the key concepts to understand when to embed in JSONB vs normalize to relational columns.
+2. Apply the hybrid model: relational columns for stable, queryable fields; JSONB for varying, per-row data.
+3. Verify with EXPLAIN ANALYZE that GIN or expression indexes are used for JSONB queries.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-entity-attribute-value, db-polymorphic-associations, db-first-normal-form, db-denormalization, db-expression-index
+
+## Success Criteria
+
+- JSONB is used only for varying or semi-structured fields -- stable fields are relational columns.
+- GIN or expression indexes are present for queried JSONB paths.
+- Frequently queried JSONB fields are promoted to generated columns or expression indexes.
+- JSONB documents stay under 1MB per row.