@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/codex/db-nested-sets/skill.yaml

@@ -0,0 +1,38 @@
+name: db-nested-sets
+version: "1.0.0"
+description: Left/right numbering for hierarchies -- fast reads, expensive writes, and when to use
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-adjacency-list
+  - db-closure-table
+  - db-hierarchical-data
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - nested-sets
+  - left-right
+  - MPTT
+  - modified-preorder-tree-traversal
+  - hierarchy
+  - tree-reads
+metadata:
+  author: community
+  upstream: "en.wikipedia.org/wiki/Nested_set_model"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-optimistic-locking/SKILL.md

@@ -0,0 +1,151 @@
+# Optimistic Locking
+
+> Optimistic locking assumes conflicts are rare, allows concurrent reads without locks, and detects conflicts at write time using version columns or conditional updates.
+
+## When to Use
+
+- Web applications with read-heavy workloads and infrequent write conflicts
+- Edit-and-save workflows (CMS, admin panels, document editing)
+- Any scenario where holding database locks during user think-time is unacceptable
+- APIs where multiple clients may update the same resource concurrently
+- Distributed systems where database-level locks are impractical
+
+## Instructions
+
+### Key Concepts
+
+**1. Version Column Pattern**
+
+Add an integer `version` column. Read the row including version. Update with a WHERE clause that checks the version, incrementing it on success. If no rows are affected, someone else modified the row first.
+
+```sql
+ALTER TABLE products ADD COLUMN version INTEGER NOT NULL DEFAULT 0;
+
+-- Read
+SELECT id, name, stock, version FROM products WHERE id = 42;
+-- returns: id=42, name='Widget', stock=10, version=3
+
+-- Update (conditional on version)
+UPDATE products
+  SET stock = 9, version = version + 1
+  WHERE id = 42 AND version = 3;
+
+-- Check result: if 0 rows affected, conflict detected
+```
+
+**2. Timestamp-Based**
+
+Use `updated_at` instead of an integer version. Less reliable -- two updates in the same millisecond create a false "no conflict" result. Acceptable only for low-contention workloads where millisecond-level collisions are extremely unlikely.
+
+**3. Conditional Update (Compare-and-Swap)**
+
+No extra column needed. Compare the relevant field values directly:
+
+```sql
+UPDATE accounts
+  SET balance = 350.00
+  WHERE id = 1 AND balance = 500.00;
+```
+
+Only works when you can compare the fields that matter. Not suitable when multiple fields may change independently.
+
+**4. Conflict Detection and Retry**
+
+When `rows_affected = 0`, the row was modified by another transaction. The correct response is to re-read the current state, re-apply business logic, and retry. Limit retries (3-5) with exponential backoff. Return HTTP 409 Conflict to the client if retries are exhausted.
+
+### Worked Example
+
+Product inventory update in an e-commerce system:
+
+```sql
+-- Step 1: Read current state
+SELECT id, name, stock, version
+  FROM products WHERE id = 42;
+-- returns: stock=10, version=3
+
+-- Step 2: Application logic
+-- Customer orders 1 unit, new stock = 9
+
+-- Step 3: Conditional update
+UPDATE products
+  SET stock = 9, version = version + 1
+  WHERE id = 42 AND version = 3
+  RETURNING version;
+-- If returns a row: success, new version = 4
+-- If returns nothing: conflict, another transaction modified this row
+
+-- Step 4: Retry on conflict (pseudocode)
+max_retries = 3
+for attempt in range(max_retries):
+    row = SELECT id, stock, version FROM products WHERE id = 42
+    new_stock = row.stock - 1
+    if new_stock < 0:
+        raise OutOfStock()
+    result = UPDATE products SET stock = new_stock, version = version + 1
+               WHERE id = 42 AND version = row.version
+    if result.rows_affected == 1:
+        break  -- success
+    -- else: conflict, retry with fresh data
+else:
+    raise ConflictError("Too many concurrent modifications")
+```
+
+### Anti-Patterns
+
+1. **Forgetting to check `rows_affected`.** The UPDATE silently does nothing on conflict. Without checking the result, the application assumes success and proceeds with stale data.
+
+2. **Using optimistic locking for high-contention resources.** If conflicts exceed 5-10%, pessimistic locking (`SELECT FOR UPDATE`) is more efficient. Fewer wasted retries means better throughput. See `db-pessimistic-locking`.
+
+3. **Version column not included in every UPDATE.** If any code path updates the row without incrementing version, the version becomes meaningless and conflicts go undetected.
+
+4. **Retrying without re-reading.** The retry must re-read the current state and re-apply business logic. Re-executing the same UPDATE with the same stale version will fail again indefinitely.
+
+### PostgreSQL Specifics
+
+- Use `RETURNING` to get the new version in one round trip: `UPDATE ... SET version = version + 1 ... RETURNING version;`
+- The `xmin` system column changes on every update and can serve as a free version indicator. However, `xmin` is a 32-bit transaction ID that wraps around and is not safe for long-lived comparisons or external storage (e.g., in an API ETag).
+- `pg_advisory_lock` can be combined with optimistic locking as a hybrid approach for specific high-contention scenarios.
+
+## Details
+
+### Advanced Topics
+
+**Combining with Read Committed:** The `WHERE version = $old` check in the UPDATE provides conflict detection that Read Committed does not natively offer. This gives you most of the benefit of stricter isolation levels without the overhead of Serializable or the complexity of retry logic for serialization failures.
+
+**Optimistic locking in distributed systems:** The same pattern appears outside databases. HTTP ETags implement optimistic concurrency for REST APIs. Redis CAS (WATCH/MULTI/EXEC) provides optimistic locking for cache updates. The principle is universal: read, compute, write-if-unchanged.
+
+**Advisory locks as hybrid:** For resources that are usually low-contention but occasionally spike, use `pg_try_advisory_lock` to attempt an immediate lock. If it fails (contention detected), fall back to optimistic retry. This avoids both the overhead of always locking and the wasted work of retrying under contention.
+
+### Engine Differences
+
+MySQL InnoDB supports the same version column pattern. MySQL's `ROW_COUNT()` function serves the same role as PostgreSQL's returned row count for checking `rows_affected`. Both engines handle optimistic locking at the application level -- it is not a database feature but a design pattern implemented through conditional updates.
+
+The pattern is identical across engines because it does not depend on engine-specific features. The only difference is syntax for the result check (`RETURNING` in PostgreSQL vs `ROW_COUNT()` in MySQL).
+
+### Real-World Case Studies
+
+A content management system had editors frequently working on the same articles. Pessimistic locking (`SELECT FOR UPDATE`) caused editors to wait for each other, sometimes for minutes during long editing sessions. Switching to optimistic locking with version columns and a merge UI for conflicts improved throughput significantly. Actual conflicts occurred in less than 2% of edits, and when they did occur, editors could review and merge changes rather than losing work.
+
+## Source
+
+- Fowler, M. "Patterns of Enterprise Application Architecture" (2002) -- Optimistic Offline Lock
+- [PostgreSQL Application-Level Consistency](https://www.postgresql.org/docs/current/applevel-consistency.html)
+
+## Process
+
+1. Add a `version` integer column (default 0) to mutable entities that may be concurrently modified.
+2. Include `AND version = $expected_version` in every UPDATE, with `version = version + 1` in the SET clause.
+3. Check `rows_affected` after every conditional update and implement retry logic with exponential backoff for conflicts.
+
+## 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-mvcc, db-isolation-levels, db-deadlock-prevention, db-acid-properties, prisma-transactions, drizzle-transactions, api-conditional-requests
+
+## Success Criteria
+
+- Version column present on mutable entities subject to concurrent modification
+- Every UPDATE includes version check in WHERE clause and increments version
+- `rows_affected` checked after every conditional update
+- Retry logic handles conflicts with exponential backoff and a maximum retry count

package/dist/agents/skills/codex/db-optimistic-locking/skill.yaml

@@ -0,0 +1,44 @@
+name: db-optimistic-locking
+version: '1.0.0'
+description: Version columns, conditional updates, conflict detection and retry patterns for optimistic concurrency control
+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-mvcc
+  - db-isolation-levels
+  - db-deadlock-prevention
+  - db-acid-properties
+  - prisma-transactions
+  - drizzle-transactions
+  - api-conditional-requests
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - optimistic-locking
+  - version-column
+  - conditional-update
+  - conflict-detection
+  - retry-pattern
+  - compare-and-swap
+  - OCC
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/applevel-consistency.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-partial-index/SKILL.md

@@ -0,0 +1,196 @@
+# Partial Indexes
+
+> Indexes with a WHERE clause that index only a subset of rows, reducing size and improving performance for targeted query patterns.
+
+## When to Use
+
+- Queries that always filter on a known condition (e.g., `WHERE deleted_at IS NULL`)
+- Soft-delete patterns where only non-deleted rows are queried
+- Status columns where one specific status dominates the workload (e.g., `WHERE status = 'pending'`)
+- Enforcing unique constraints on a subset of rows
+- Large tables where only a small fraction of rows are actively queried
+
+## Instructions
+
+### Key Concepts
+
+A partial index includes a WHERE clause in the CREATE INDEX statement. Only rows matching the condition are stored in the index.
+
+**Syntax:**
+
+```sql
+CREATE INDEX idx_active_orders ON orders (created_at) WHERE status = 'active';
+```
+
+This index only contains rows where `status = 'active'`. The planner uses this index only when the query's WHERE clause matches or logically implies the index predicate.
+
+**Partial unique index** -- enforces uniqueness on a subset:
+
+```sql
+CREATE UNIQUE INDEX idx_unique_active_email
+ON users (email)
+WHERE deleted_at IS NULL;
+```
+
+This allows multiple deleted users with the same email while enforcing uniqueness for active users -- a common requirement in soft-delete systems.
+
+**Size advantage:** When the filtered subset is small relative to the full table, the partial index is dramatically smaller. An index covering 1% of rows is roughly 1% the size of a full index.
+
+### Worked Example
+
+SaaS task queue with 10M rows where 99% of tasks are completed:
+
+```sql
+CREATE TABLE tasks (
+  id         SERIAL PRIMARY KEY,
+  tenant_id  INT NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'pending',
+  payload    JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Full index on status (indexes all 10M rows):
+CREATE INDEX idx_tasks_status_full ON tasks (created_at) WHERE true;
+
+-- Partial index on only pending tasks (~100K rows):
+CREATE INDEX idx_tasks_pending ON tasks (created_at) WHERE status = 'pending';
+```
+
+**Query using the partial index:**
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, payload
+FROM tasks
+WHERE status = 'pending' AND created_at > '2024-01-01'
+ORDER BY created_at;
+```
+
+```
+Index Scan using idx_tasks_pending on tasks
+  (cost=0.29..245.12 rows=523 width=156)
+  (actual time=0.021..1.832 rows=498 loops=1)
+  Index Cond: (created_at > '2024-01-01')
+Execution Time: 2.104 ms
+```
+
+**Size comparison:**
+
+```sql
+SELECT
+  pg_size_pretty(pg_relation_size('idx_tasks_status_full')) AS full_size,
+  pg_size_pretty(pg_relation_size('idx_tasks_pending'))     AS partial_size;
+```
+
+```
+ full_size | partial_size
+-----------+--------------
+ 250 MB    | 2.5 MB
+```
+
+The partial index is 100x smaller and produces faster scans because it has fewer pages to traverse.
+
+### Anti-Patterns
+
+1. **Partial index with a condition matching most rows.** `WHERE status != 'archived'` on a table where 95% of rows are non-archived provides minimal size benefit. The predicate should filter to a small fraction of the table.
+
+2. **Forgetting the predicate in queries.** If the index is `WHERE status = 'pending'` but your query is `WHERE created_at > '2024-01-01'` without mentioning status, the planner cannot use the partial index.
+
+3. **Overly complex predicates.** The planner matches partial index predicates using implication logic, but complex expressions with OR, NOT, or function calls may not be recognized. Keep predicates simple.
+
+4. **Partial indexes on frequently changing conditions.** If rows transition through status values rapidly, the index must constantly add and remove entries. This generates excessive write amplification.
+
+### PostgreSQL Specifics
+
+**Predicate implication.** PostgreSQL's planner uses logical implication to match queries to partial indexes. A query `WHERE status = 'pending' AND created_at > '2024-01-01'` implies the predicate `WHERE status = 'pending'`, so the index is used.
+
+**Monitoring usage:**
+
+```sql
+SELECT indexrelname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+WHERE indexrelname = 'idx_tasks_pending';
+```
+
+**Partial indexes with UNIQUE constraints** are fully supported. This is one of PostgreSQL's most powerful features for soft-delete patterns:
+
+```sql
+-- Allow reuse of usernames after account deletion:
+CREATE UNIQUE INDEX idx_unique_username
+ON users (username)
+WHERE deleted_at IS NULL;
+```
+
+## Details
+
+### Advanced Topics
+
+**Combining partial with composite indexes.** You can create a partial composite index for highly targeted access patterns:
+
+```sql
+CREATE INDEX idx_pending_by_tenant
+ON tasks (tenant_id, created_at)
+WHERE status = 'pending';
+```
+
+**Partial GIN indexes on JSONB.** Index only JSONB rows matching a condition:
+
+```sql
+CREATE INDEX idx_events_purchase_gin
+ON events USING GIN (metadata)
+WHERE event_type = 'purchase';
+```
+
+**Partial indexes for multi-tenant isolation.** For a tenant that generates 50% of the workload, a tenant-specific partial index can be highly effective:
+
+```sql
+CREATE INDEX idx_tenant_5_orders
+ON orders (created_at)
+WHERE tenant_id = 5;
+```
+
+**Predicate complexity limits.** PostgreSQL can match simple predicates involving `=`, `<`, `>`, `IS NULL`, `IS NOT NULL`, and boolean AND combinations. Predicates using OR, NOT, or function calls are less likely to be matched automatically.
+
+### Engine Differences
+
+**MySQL does not support partial indexes.** Workarounds include:
+
+1. **Generated columns with indexes.** Create a stored generated column that computes a value only for the target subset, then index it:
+
+```sql
+ALTER TABLE tasks ADD COLUMN is_pending TINYINT
+  GENERATED ALWAYS AS (IF(status = 'pending', 1, NULL)) STORED;
+CREATE INDEX idx_pending ON tasks (is_pending, created_at);
+```
+
+2. **Covering the condition in a composite index.** Put the filtered column first in a composite index: `CREATE INDEX idx_status_date ON tasks (status, created_at)`. This does not reduce index size but at least narrows the scan.
+
+**SQL Server** supports "filtered indexes" with identical syntax to PostgreSQL partial indexes.
+
+**MySQL 8.0 functional indexes** can approximate some partial index use cases but without the size reduction benefit.
+
+### Real-World Case Studies
+
+**Social media platform with 500M posts.** A moderation system needed to query the 0.1% of posts flagged for review. Without a partial index, the moderation queue query scanned 500M rows (Seq Scan, 4.2 seconds). Adding `CREATE INDEX idx_flagged ON posts (created_at) WHERE flagged = true` reduced the query to 3ms (Index Scan on ~500K rows). Index size: 12MB instead of the 12GB a full index would have consumed. The 1000x size reduction also meant the partial index stayed entirely in the buffer cache.
+
+## Source
+
+- [PostgreSQL Partial Indexes](https://www.postgresql.org/docs/current/indexes-partial.html)
+
+## Process
+
+1. Read the key concepts to understand when partial indexes provide significant benefits.
+2. Apply partial indexes to queries that consistently filter on a known condition targeting a small subset of rows.
+3. Verify with EXPLAIN ANALYZE that the planner uses the partial index and compare index sizes with `pg_relation_size`.
+
+## 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-btree-index, db-composite-index, db-expression-index, db-explain-reading, db-scan-types
+
+## Success Criteria
+
+- Partial indexes target high-selectivity conditions where the indexed subset is a small fraction of the table.
+- Query predicates match or imply the index predicate so the planner can use the index.
+- Partial unique indexes are used for soft-delete uniqueness constraints where appropriate.

package/dist/agents/skills/codex/db-partial-index/skill.yaml

@@ -0,0 +1,39 @@
+name: db-partial-index
+version: '1.0.0'
+description: Filtered indexes with WHERE clauses to reduce index size and target specific query 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-btree-index
+  - db-composite-index
+  - db-expression-index
+  - db-explain-reading
+  - db-scan-types
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - partial-index
+  - filtered-index
+  - conditional-index
+  - WHERE-clause-index
+  - index-size
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/indexes-partial.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-pessimistic-locking/SKILL.md

@@ -0,0 +1,158 @@
+# Pessimistic Locking
+
+> Pessimistic locking acquires locks before modifying data, guaranteeing exclusive access and preventing conflicts at the cost of reduced concurrency.
+
+## When to Use
+
+- High-contention resources where optimistic retries would be excessive (conflict rate > 5-10%)
+- Financial transactions requiring guaranteed exclusive access to account rows
+- Inventory decrements where overselling is unacceptable
+- Queue-like processing patterns using `SKIP LOCKED`
+- Any workflow where two concurrent modifications to the same row would cause data corruption
+
+## Instructions
+
+### Key Concepts
+
+**1. SELECT FOR UPDATE**
+
+Acquires a row-level exclusive lock. Other transactions attempting `FOR UPDATE` or `UPDATE` on the same row block until the lock is released at `COMMIT` or `ROLLBACK`.
+
+```sql
+BEGIN;
+SELECT * FROM accounts WHERE id = 1 FOR UPDATE;
+-- Row is now locked -- other transactions wait here
+UPDATE accounts SET balance = balance - 100 WHERE id = 1;
+COMMIT;  -- lock released
+```
+
+**2. Lock Modes**
+
+PostgreSQL offers four row-level lock strengths:
+
+| Mode                | Blocks                        | Use Case                           |
+| ------------------- | ----------------------------- | ---------------------------------- |
+| `FOR UPDATE`        | All other row locks           | Full exclusive access              |
+| `FOR NO KEY UPDATE` | Other updates (not KEY SHARE) | Update non-key columns             |
+| `FOR SHARE`         | Updates (not other SHARE)     | Shared read lock, prevent changes  |
+| `FOR KEY SHARE`     | Only FOR UPDATE               | Prevent key changes, allow updates |
+
+Use the weakest lock that satisfies your requirements. `FOR NO KEY UPDATE` is preferred over `FOR UPDATE` when you are not modifying primary key or unique constraint columns.
+
+**3. NOWAIT and SKIP LOCKED**
+
+```sql
+-- NOWAIT: fail immediately instead of waiting
+SELECT * FROM accounts WHERE id = 1 FOR UPDATE NOWAIT;
+-- ERROR: could not obtain lock on row (if already locked)
+
+-- SKIP LOCKED: skip already-locked rows
+SELECT * FROM tasks WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED;
+-- Returns the next unlocked row, or nothing if all are locked
+```
+
+**4. Lock Duration**
+
+Row locks are held until the end of the transaction (`COMMIT` or `ROLLBACK`). There is no way to release a row lock early within a transaction. Keep transactions short to minimize blocking.
+
+### Worked Example
+
+Job queue processing with `SKIP LOCKED` -- multiple workers dequeue tasks concurrently:
+
+```sql
+-- Worker 1                            -- Worker 2
+BEGIN;                                 BEGIN;
+SELECT id, payload FROM tasks          SELECT id, payload FROM tasks
+  WHERE status = 'pending'               WHERE status = 'pending'
+  ORDER BY created_at                    ORDER BY created_at
+  LIMIT 1                               LIMIT 1
+  FOR UPDATE SKIP LOCKED;               FOR UPDATE SKIP LOCKED;
+-- returns task 101                    -- returns task 102 (101 is locked)
+
+UPDATE tasks                           UPDATE tasks
+  SET status = 'processing',             SET status = 'processing',
+      worker_id = 'w1'                       worker_id = 'w2'
+  WHERE id = 101;                        WHERE id = 102;
+
+-- ... process task ...                -- ... process task ...
+
+UPDATE tasks SET status = 'done'       UPDATE tasks SET status = 'done'
+  WHERE id = 101;                        WHERE id = 102;
+COMMIT;                                COMMIT;
+```
+
+Both workers operate on different tasks without conflicts. No retries needed.
+
+### Anti-Patterns
+
+1. **Locking rows during user think-time.** Holding `FOR UPDATE` across an HTTP request-response cycle blocks other users for seconds or minutes. Use optimistic locking for user-facing edit workflows instead. See `db-optimistic-locking`.
+
+2. **Locking more rows than needed.** `SELECT * FROM orders FOR UPDATE` without a WHERE clause locks every row in the table. Always scope your lock to the minimum set of rows.
+
+3. **Forgetting `SKIP LOCKED` in queue patterns.** Without it, all workers serialize on the same row instead of processing in parallel. The second worker blocks until the first commits.
+
+4. **Mixing `FOR UPDATE` with `SERIALIZABLE` isolation.** Redundant and can cause unexpected serialization failures. `FOR UPDATE` in Read Committed already provides the exclusion you need. Adding Serializable adds SSI overhead with no additional benefit for the locked rows.
+
+### PostgreSQL Specifics
+
+- **Monitoring locks:** `SELECT * FROM pg_locks WHERE relation = 'accounts'::regclass;`
+- **Lock timeout:** `SET lock_timeout = '5s';` to prevent indefinite waits
+- **Deadlock timeout:** `deadlock_timeout` (default 1s) controls when PostgreSQL checks for deadlocks
+- **Advisory locks:** `pg_advisory_lock(key)` for application-defined locking that does not map to specific rows. Useful for locking abstract resources (e.g., a customer ID across multiple tables).
+- **Who is blocking whom:** `SELECT pg_blocking_pids(pid) FROM pg_stat_activity;`
+
+## Details
+
+### Advanced Topics
+
+**Advisory locks for distributed coordination:**
+
+```sql
+-- Lock on an application-defined key (e.g., customer ID for cross-table operations)
+SELECT pg_advisory_lock(hashtext('customer:' || customer_id::text));
+-- ... perform operations across multiple tables ...
+-- Lock released at end of session (or use pg_advisory_xact_lock for transaction scope)
+```
+
+**Table-level locks:** `LOCK TABLE orders IN EXCLUSIVE MODE;` for bulk operations that need to prevent all concurrent modifications. Rarely needed -- prefer row-level locks.
+
+**Lock escalation:** PostgreSQL does not escalate row locks to table locks (unlike SQL Server). You can lock millions of individual rows without the engine deciding to lock the entire table. This makes PostgreSQL's locking behavior more predictable.
+
+### Engine Differences
+
+MySQL InnoDB uses **gap locking** in addition to row locking under Repeatable Read. A `FOR UPDATE` query can lock index gaps between rows, blocking inserts into ranges -- even inserts that would not conflict with the locked rows. This causes unexpected blocking and is a common source of contention in MySQL.
+
+PostgreSQL does not use gap locks because MVCC handles phantom prevention differently. This means PostgreSQL's `FOR UPDATE` is more precisely targeted: it locks exactly the rows selected, nothing more.
+
+MySQL's `LOCK IN SHARE MODE` is the equivalent of PostgreSQL's `FOR SHARE`. MySQL 8.0+ also supports `FOR SHARE` and `SKIP LOCKED` syntax, matching PostgreSQL's capabilities.
+
+### Real-World Case Studies
+
+A ticket booking system for concert events originally used optimistic locking for seat selection. During high-demand on-sale events, the optimistic retry rate reached 40% as thousands of users competed for the same popular seats. Switching to `SELECT ... FOR UPDATE NOWAIT` with immediate user feedback ("seat unavailable, please pick another") reduced conflicts to near zero. Users got instant feedback instead of experiencing retry loops, and the system handled 10x the concurrent load without contention issues.
+
+## Source
+
+- [PostgreSQL Explicit Locking](https://www.postgresql.org/docs/current/explicit-locking.html)
+- Kleppmann, M. "Designing Data-Intensive Applications" (2017)
+
+## Process
+
+1. Identify rows that require exclusive access during modification and use the weakest lock mode sufficient.
+2. Add `SKIP LOCKED` for queue patterns and `NOWAIT` when immediate feedback is preferred over waiting.
+3. Keep transactions holding locks as short as possible and monitor lock waits via `pg_locks` and `log_lock_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-optimistic-locking, db-deadlock-prevention, db-isolation-levels, db-mvcc, db-acid-properties, prisma-transactions, drizzle-transactions
+
+## Success Criteria
+
+- Row locks scoped to the minimum necessary rows with appropriate WHERE clauses
+- Transactions holding locks are kept short (no user think-time under lock)
+- `SKIP LOCKED` used for queue/worker patterns
+- `NOWAIT` used when immediate feedback is preferred over blocking
+- Lock waits monitored via `pg_locks` and `log_lock_waits = on`

package/dist/agents/skills/codex/db-pessimistic-locking/skill.yaml

@@ -0,0 +1,44 @@
+name: db-pessimistic-locking
+version: '1.0.0'
+description: SELECT FOR UPDATE, lock granularity, lock duration, and row-level locking strategies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-optimistic-locking
+  - db-deadlock-prevention
+  - db-isolation-levels
+  - db-mvcc
+  - db-acid-properties
+  - prisma-transactions
+  - drizzle-transactions
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - pessimistic-locking
+  - select-for-update
+  - row-lock
+  - lock-granularity
+  - lock-duration
+  - exclusive-lock
+  - shared-lock
+  - FOR-NO-KEY-UPDATE
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/explicit-locking.html
+state:
+  persistent: false
+  files: []
+depends_on: []