@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/claude-code/db-migration-rollback/SKILL.md

@@ -0,0 +1,223 @@
+# Migration Rollback Strategies
+
+> Forward-only vs reversible migrations, data backfill safety, and blue-green schema patterns for confident schema evolution.
+
+## When to Use
+
+- Deciding whether a migration needs a rollback script
+- Planning a deployment that modifies both schema and data
+- Designing blue-green or canary database deployment strategies
+- Recovering from a failed migration in production
+- Evaluating migration framework rollback capabilities
+
+## Instructions
+
+### Key Concepts
+
+**1. Forward-Only vs Reversible Migrations**
+
+Forward-only migrations have no `down` step. Rollback means deploying a new forward migration that undoes the change. This is safer for data mutations because `down` migrations that drop columns destroy data.
+
+```sql
+-- Reversible migration:
+-- UP:
+ALTER TABLE orders ADD COLUMN priority INT DEFAULT 0;
+-- DOWN:
+ALTER TABLE orders DROP COLUMN priority;
+-- DANGER: if priority was populated with real data, DOWN destroys it
+
+-- Forward-only approach:
+-- Migration 001: add column
+ALTER TABLE orders ADD COLUMN priority INT DEFAULT 0;
+-- If rollback needed, deploy migration 002:
+-- Migration 002: remove column (explicit, reviewed, data-loss acknowledged)
+ALTER TABLE orders DROP COLUMN priority;
+```
+
+**2. Data Migration vs Schema Migration**
+
+Schema migrations change structure (DDL). Data migrations change content (DML). Never mix them in a single migration file. Schema changes are generally safe to roll back; data changes are not.
+
+```sql
+-- MIGRATION 001 (schema): add column
+ALTER TABLE users ADD COLUMN status TEXT;
+
+-- MIGRATION 002 (data): populate column
+UPDATE users SET status = 'active' WHERE deleted_at IS NULL;
+UPDATE users SET status = 'deleted' WHERE deleted_at IS NOT NULL;
+
+-- Rolling back 002 is safe (SET status = NULL)
+-- Rolling back 001 after 002 would lose the status data
+```
+
+**3. Blue-Green Schema Pattern**
+
+Run two schema versions simultaneously. The "blue" schema is current production; the "green" schema is the new version. Both coexist until the green schema is validated.
+
+```sql
+-- Blue schema (current): orders table with status VARCHAR
+-- Green schema (new): orders table with status_enum ENUM type
+
+-- Step 1: Add green column alongside blue
+ALTER TABLE orders ADD COLUMN status_enum order_status;
+
+-- Step 2: Both exist, application writes to both
+-- Step 3: Validate green data matches blue
+SELECT count(*) FROM orders
+  WHERE status_enum::text != status;
+-- Must return 0
+
+-- Step 4: Switch reads to green
+-- Step 5: Drop blue column
+ALTER TABLE orders DROP COLUMN status;
+```
+
+**4. Backfill Safety Rules**
+
+Data backfills are the most dangerous part of any migration:
+
+- Always backfill in batches (1K-10K rows per batch)
+- Always include a `WHERE` clause that limits scope
+- Always run in a separate transaction per batch
+- Always have a verification query ready
+- Never backfill and add a `NOT NULL` constraint in the same migration
+
+```sql
+-- Safe backfill pattern:
+DO $$
+DECLARE
+  batch_start BIGINT := 0;
+  batch_end BIGINT;
+  rows_updated INT;
+BEGIN
+  LOOP
+    batch_end := batch_start + 5000;
+    UPDATE orders
+    SET priority = CASE
+      WHEN total > 1000 THEN 'high'
+      ELSE 'normal'
+    END
+    WHERE id > batch_start AND id <= batch_end
+      AND priority IS NULL;
+    GET DIAGNOSTICS rows_updated = ROW_COUNT;
+    batch_start := batch_end;
+    EXIT WHEN rows_updated = 0;
+    COMMIT;
+    PERFORM pg_sleep(0.1);  -- brief pause to reduce load
+  END LOOP;
+END $$;
+```
+
+### Worked Example
+
+Scenario: rename `orders.status` from free-text VARCHAR to an ENUM with validation, with full rollback capability.
+
+```sql
+-- Migration 001 (schema): expand
+ALTER TABLE orders ADD COLUMN status_v2 order_status_enum;
+
+-- Migration 002 (data): backfill
+-- Run in batches, mapping old values to enum values
+UPDATE orders SET status_v2 = CASE status
+  WHEN 'pending' THEN 'pending'::order_status_enum
+  WHEN 'Pending' THEN 'pending'::order_status_enum
+  WHEN 'shipped' THEN 'shipped'::order_status_enum
+  WHEN 'SHIPPED' THEN 'shipped'::order_status_enum
+  ELSE 'unknown'::order_status_enum
+END
+WHERE id BETWEEN $1 AND $2 AND status_v2 IS NULL;
+
+-- Migration 003 (validation): verify completeness
+-- Run as a check, not a migration
+SELECT status, count(*) FROM orders
+  WHERE status_v2 IS NULL GROUP BY status;
+-- Must return 0 rows
+
+-- Migration 004 (schema): contract
+-- Only deployed after all application code reads status_v2
+ALTER TABLE orders DROP COLUMN status;
+ALTER TABLE orders RENAME COLUMN status_v2 TO status;
+
+-- ROLLBACK PLAN (if issues found after migration 002):
+-- Deploy migration 005:
+UPDATE orders SET status = status_v2::text WHERE status IS NULL;
+ALTER TABLE orders DROP COLUMN status_v2;
+-- Data preserved, original column restored
+```
+
+### Anti-Patterns
+
+1. **Writing `down` migrations that drop columns containing user data.** The `down` migration should be reviewed with the same rigor as the `up`. If it destroys data, it needs a backup step or should not exist.
+
+2. **Mixing DDL and DML in one migration.** If the DML fails partway through, the DDL may or may not be rolled back depending on the database engine. Keep them separate for predictable rollback behavior.
+
+3. **Deploying a data migration without a verification query.** Every data migration needs a `SELECT` that proves the migration succeeded. Run it before proceeding to the next migration.
+
+4. **Assuming `down` migrations are tested.** Teams write `down` migrations but never run them. They rot and fail when actually needed. Test rollbacks in staging before relying on them.
+
+5. **Rolling back schema changes that other migrations depend on.** Migration 003 adds a column; migration 004 adds an index on it. Rolling back 003 without rolling back 004 first breaks the schema. Track migration dependencies explicitly.
+
+### PostgreSQL Specifics
+
+- Transactional DDL means a migration that fails partway through is fully rolled back. This is a significant safety advantage over MySQL.
+- `pg_dump --schema-only` captures a point-in-time schema snapshot. Take one before every risky migration as a last-resort recovery option.
+- `pg_stat_progress_copy` and `pg_stat_progress_create_index` provide real-time progress for long-running operations.
+- Advisory locks can prevent concurrent migration execution: `SELECT pg_advisory_lock(12345)` at migration start, released on commit.
+
+## Details
+
+### Advanced Topics
+
+**Blue-Green Database Deployments:** Run two complete database instances (blue and green) behind a load balancer. Apply migrations to the green database, validate, then switch traffic. Rollback is instant: switch traffic back to blue. Limitation: the databases must be synchronized, which is complex for write-heavy workloads.
+
+**Schema Versioning Table:**
+
+```sql
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  applied_at TIMESTAMPTZ DEFAULT now(),
+  checksum TEXT,  -- hash of migration file content
+  execution_time_ms INT,
+  rolled_back_at TIMESTAMPTZ  -- NULL if still applied
+);
+```
+
+Track rollbacks explicitly. A migration that has been applied and rolled back has a non-NULL `rolled_back_at`. This provides audit history.
+
+**Canary Migrations:** Apply the migration to a small percentage of data first. For example, backfill only orders from the last 7 days, validate, then expand to the full table. This catches data-dependent bugs early.
+
+### Engine Differences
+
+MySQL commits DDL implicitly. A migration with `ALTER TABLE` followed by `UPDATE` cannot be rolled back atomically. If the `UPDATE` fails, the `ALTER TABLE` is already permanent. This makes forward-only migrations even more important in MySQL -- you cannot rely on transactional rollback.
+
+MySQL's `binlog` can help recover data after a bad migration by replaying events, but this requires point-in-time recovery infrastructure and is not a substitute for a planned rollback strategy.
+
+### Real-World Case Studies
+
+A fintech company deployed a data migration that normalized phone numbers from 12 different formats into E.164. The migration passed in staging but corrupted 2% of phone numbers in production due to locale-specific formats not present in the test dataset. Because they used forward-only migrations with a separate verification step, they detected the issue before the contract phase. They deployed a new forward migration that re-processed the corrupted rows using an improved normalization function. If they had used a `down` migration instead, rolling back would have lost the 98% of correctly normalized numbers.
+
+## Source
+
+- [PostgreSQL DDL Transactions](https://www.postgresql.org/docs/current/ddl.html)
+- Sadalage, P. & Fowler, M. "Refactoring Databases" (2006)
+- [Flyway Migrations](https://flywaydb.org/documentation/concepts/migrations)
+
+## Process
+
+1. Classify the migration as schema-only, data-only, or mixed. Split mixed migrations into separate files.
+2. Write a verification query that proves the migration succeeded.
+3. For data migrations, implement batched backfill with progress tracking.
+4. Test the rollback path in a staging environment before deploying to production.
+
+## 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-zero-downtime-migration, db-expand-contract, db-acid-properties, db-isolation-levels
+
+## Success Criteria
+
+- Schema and data migrations are in separate migration files, never mixed.
+- Every data migration has a verification query that proves correctness before proceeding.
+- Forward-only migrations are preferred; `down` migrations that destroy data are avoided.
+- Rollback paths are tested in staging before production deployment.

package/dist/agents/skills/claude-code/db-migration-rollback/skill.yaml

@@ -0,0 +1,40 @@
+name: db-migration-rollback
+version: '1.0.0'
+description: Forward-only vs reversible migrations, data backfill safety, and blue-green schema 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-zero-downtime-migration
+  - db-expand-contract
+  - db-acid-properties
+  - db-isolation-levels
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - migration-rollback
+  - forward-only
+  - reversible-migration
+  - backfill
+  - blue-green
+  - schema-versioning
+  - data-migration
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/ddl.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/db-mvcc/SKILL.md

@@ -0,0 +1,191 @@
+# MVCC (Multi-Version Concurrency Control)
+
+> MVCC allows readers and writers to operate concurrently without blocking each other by maintaining multiple versions of each row, with visibility determined by transaction snapshots.
+
+## When to Use
+
+- Understanding why PostgreSQL does not block reads during writes
+- Debugging table bloat or unexpected disk space growth
+- Tuning autovacuum for high-churn tables
+- Understanding `xmin`/`xmax` system columns in query results
+- Diagnosing "transaction ID wraparound" warnings in PostgreSQL logs
+- Investigating slow sequential scans caused by dead tuple accumulation
+
+## Instructions
+
+### Key Concepts
+
+**1. How MVCC Works**
+
+Every row in PostgreSQL has hidden system columns: `xmin` (the transaction ID that created the row version) and `xmax` (the transaction ID that deleted or updated it). An UPDATE does not modify a row in place -- it creates a new row version and marks the old one as dead by setting its `xmax`.
+
+```sql
+-- Observe MVCC in action
+CREATE TABLE demo (id int, val text);
+INSERT INTO demo VALUES (1, 'original');
+
+SELECT xmin, xmax, * FROM demo;
+--  xmin | xmax | id |   val
+-- ------+------+----+----------
+--   100 |    0 |  1 | original
+```
+
+**2. Snapshot Visibility**
+
+A transaction takes a snapshot of active transaction IDs when it begins (or at each statement, depending on isolation level). A row version is visible if: `xmin` is from a committed transaction that committed before the snapshot, AND `xmax` is either zero (not deleted), from an aborted transaction, or from a transaction that committed after the snapshot.
+
+**3. Dead Tuples and Bloat**
+
+Old row versions are not immediately removed. They accumulate as "dead tuples." This causes table bloat -- wasted disk space that degrades sequential scan performance and wastes I/O.
+
+```sql
+-- Check dead tuple count
+SELECT relname, n_live_tup, n_dead_tup,
+       ROUND(n_dead_tup::numeric / NULLIF(n_live_tup, 0) * 100, 1) AS dead_pct
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+**4. VACUUM**
+
+Reclaims space from dead tuples. `VACUUM` marks the space as reusable for future inserts (but does not return it to the OS). `VACUUM FULL` rewrites the entire table to compact it, but requires an ACCESS EXCLUSIVE lock.
+
+```sql
+-- Standard vacuum (non-blocking)
+VACUUM VERBOSE demo;
+-- INFO: "demo": removed 1500 dead row versions, 850 pages remain
+
+-- Full vacuum (blocks all access -- avoid during business hours)
+VACUUM FULL demo;
+```
+
+**5. Transaction ID Wraparound**
+
+Transaction IDs are 32-bit unsigned integers (~4.2 billion). After approximately 2 billion transactions, wraparound can cause all data to appear to be "in the future" and become invisible. Autovacuum's freeze process prevents this by marking old tuples as "frozen" (visible to all future transactions).
+
+### Worked Example
+
+Demonstrating MVCC tuple versioning:
+
+```sql
+-- Session A                           -- Session B
+BEGIN;
+INSERT INTO demo VALUES (2, 'v1');
+COMMIT;
+
+SELECT xmin, xmax, * FROM demo
+  WHERE id = 2;
+-- xmin=200, xmax=0, val='v1'
+
+BEGIN;                                 BEGIN;
+                                       UPDATE demo SET val = 'v2'
+                                         WHERE id = 2;
+                                       COMMIT;
+
+-- Session A still sees 'v1' if using
+-- Repeatable Read (snapshot frozen)
+
+SELECT xmin, xmax, * FROM demo
+  WHERE id = 2;
+-- Under Read Committed: xmin=201, val='v2'
+-- Under Repeatable Read: xmin=200, val='v1'
+COMMIT;
+
+-- Check dead tuples accumulated
+SELECT n_dead_tup FROM pg_stat_user_tables
+  WHERE relname = 'demo';
+-- n_dead_tup = 1 (the old 'v1' version)
+
+VACUUM VERBOSE demo;
+-- Reclaims the dead tuple
+```
+
+### Anti-Patterns
+
+1. **Disabling autovacuum.** Dead tuples accumulate without bound, table bloat grows indefinitely, and eventually transaction ID wraparound makes all data invisible. Never disable autovacuum globally. If a specific table has issues, tune its settings rather than disabling.
+
+2. **Long-running transactions holding snapshots.** A transaction that stays open for hours prevents VACUUM from reclaiming any tuples created after that transaction's snapshot -- even in other tables. Monitor `pg_stat_activity` for `idle in transaction` sessions.
+
+3. **High-churn UPDATE patterns without monitoring bloat.** Tables receiving millions of updates per day can bloat to 10x their actual data size if autovacuum cannot keep pace with the default settings.
+
+4. **Using `VACUUM FULL` in production during business hours.** Requires ACCESS EXCLUSIVE lock, blocking all queries on the table for the duration. Use `pg_repack` for online compaction instead.
+
+### PostgreSQL Specifics
+
+**Autovacuum thresholds:** Vacuum triggers when dead tuples exceed `autovacuum_vacuum_threshold` (default 50) + `autovacuum_vacuum_scale_factor` (default 0.2) \* table row count. For a 1 million row table, vacuum triggers at 200,050 dead tuples.
+
+**Per-table tuning for high-churn tables:**
+
+```sql
+ALTER TABLE hot_table SET (
+  autovacuum_vacuum_scale_factor = 0.01,  -- 1% instead of 20%
+  autovacuum_vacuum_cost_delay = 2        -- 2ms instead of 20ms (faster vacuum)
+);
+```
+
+**Monitoring commands:**
+
+- `SELECT n_dead_tup, last_vacuum, last_autovacuum FROM pg_stat_user_tables;`
+- `SELECT age(relfrozenxid) FROM pg_class WHERE relname = 'tablename';` -- distance to wraparound
+- `pg_bloat_check` extension for comprehensive bloat detection
+
+## Details
+
+### Advanced Topics
+
+**HOT (Heap-Only Tuples):** If an UPDATE does not change any indexed columns, PostgreSQL can chain the new version to the old one without updating indexes. This significantly reduces bloat and index maintenance overhead. The `fillfactor` storage parameter (default 100) can be lowered to leave room for HOT updates:
+
+```sql
+ALTER TABLE frequently_updated SET (fillfactor = 80);
+-- 20% of each page reserved for HOT updates
+```
+
+**Transaction ID wraparound prevention:** Monitor `age(relfrozenxid)` for all tables. When it approaches 2 billion, PostgreSQL forces an aggressive autovacuum. If this emergency vacuum cannot complete (e.g., due to long-running transactions), the database shuts down to prevent data loss.
+
+```sql
+-- Find tables closest to wraparound
+SELECT relname, age(relfrozenxid) AS xid_age
+FROM pg_class
+WHERE relkind = 'r'
+ORDER BY age(relfrozenxid) DESC
+LIMIT 10;
+```
+
+**`pg_repack`:** Extension that performs online table compaction without ACCESS EXCLUSIVE lock (unlike `VACUUM FULL`). Safe for production use during business hours.
+
+### Engine Differences
+
+MySQL InnoDB also uses MVCC but implements it differently. InnoDB stores undo information in a separate **undo log** (rollback segment) rather than keeping old row versions in the table heap. The current version is always in the table; older versions are reconstructed from undo records.
+
+InnoDB's **purge thread** automatically cleans old undo records -- there is no equivalent of PostgreSQL's VACUUM. This means InnoDB does not suffer from table-level bloat in the same way. However, undo log bloat is possible with long-running transactions (the undo tablespace grows and is not reclaimed until the transaction completes).
+
+InnoDB does not have transaction ID wraparound concerns because it uses 48-bit transaction IDs with a different visibility mechanism.
+
+### Real-World Case Studies
+
+A high-traffic analytics platform had a 200GB event tracking table that grew to 1.8TB over three months. Investigation revealed massive bloat: the table received 5 million small updates per hour (status changes on event records), but autovacuum with default settings could not keep pace. Dead tuples accumulated faster than vacuum could remove them. Tuning `autovacuum_vacuum_scale_factor` to 0.01 and `autovacuum_vacuum_cost_delay` to 2ms for that specific table allowed vacuum to run more aggressively. After a one-time `pg_repack` to reclaim the existing bloat, the table stabilized at 230GB with ongoing bloat below 15%.
+
+## Source
+
+- [PostgreSQL MVCC Introduction](https://www.postgresql.org/docs/current/mvcc-intro.html)
+- [PostgreSQL Routine Vacuuming](https://www.postgresql.org/docs/current/routine-vacuuming.html)
+
+## Process
+
+1. Understand that MVCC creates dead tuples on every UPDATE and DELETE -- this is normal, not a problem unless vacuum falls behind.
+2. Monitor dead tuple counts and bloat ratios for high-churn tables using `pg_stat_user_tables`.
+3. Tune autovacuum thresholds per-table for tables with update rates that exceed the defaults, and use `pg_repack` for online compaction when needed.
+
+## 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-isolation-levels, db-read-phenomena, db-acid-in-practice, db-pessimistic-locking, db-optimistic-locking, db-deadlock-prevention
+
+## Success Criteria
+
+- Autovacuum enabled and monitored for all tables (never globally disabled)
+- High-churn tables have per-table autovacuum settings tuned for their update rate
+- Dead tuple counts and bloat ratios tracked in monitoring dashboards
+- No tables approaching transaction ID wraparound (age(relfrozenxid) < 500 million)

package/dist/agents/skills/claude-code/db-mvcc/skill.yaml

@@ -0,0 +1,45 @@
+name: db-mvcc
+version: '1.0.0'
+description: Multi-version concurrency control, snapshot isolation, tuple visibility, and vacuum/bloat management
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-isolation-levels
+  - db-read-phenomena
+  - db-acid-in-practice
+  - db-pessimistic-locking
+  - db-optimistic-locking
+  - db-deadlock-prevention
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - MVCC
+  - multi-version-concurrency-control
+  - snapshot-isolation
+  - vacuum
+  - autovacuum
+  - bloat
+  - xmin
+  - xmax
+  - tuple-visibility
+  - dead-tuples
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/mvcc-intro.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/db-nested-sets/SKILL.md

@@ -0,0 +1,171 @@
+# Nested Sets
+
+> Encoding hierarchy position with left/right boundary numbers for O(1) subtree and ancestor queries at the cost of expensive writes.
+
+## When to Use
+
+- Read-heavy hierarchies that rarely change (product category taxonomies, geographic region trees)
+- Organizational hierarchies updated quarterly or less frequently
+- Reporting that needs subtree aggregation without recursion
+- Hierarchies rebuilt in batch (nightly import, weekly sync) where write cost is amortized
+
+## Instructions
+
+### Key Concepts
+
+Each node stores `lft` and `rgt` values assigned via modified preorder tree traversal (MPTT). The numbering works by walking the tree depth-first, incrementing a counter on each "visit" -- once when entering a node (lft) and once when leaving (rgt):
+
+```sql
+CREATE TABLE categories (
+  id   serial PRIMARY KEY,
+  name varchar NOT NULL,
+  lft  int NOT NULL,
+  rgt  int NOT NULL
+);
+
+CREATE INDEX idx_categories_lft_rgt ON categories (lft, rgt);
+```
+
+**Key queries become simple range checks:**
+
+| Query               | SQL                                 |
+| ------------------- | ----------------------------------- |
+| Subtree of node X   | `WHERE lft BETWEEN X.lft AND X.rgt` |
+| Ancestors of node X | `WHERE lft < X.lft AND rgt > X.rgt` |
+| Leaf nodes          | `WHERE rgt = lft + 1`               |
+| Subtree size        | `(rgt - lft - 1) / 2`               |
+| Is A ancestor of B? | `A.lft < B.lft AND A.rgt > B.rgt`   |
+
+No recursion, no JOINs -- all hierarchy queries reduce to range comparisons on two indexed columns.
+
+**The cost:** Inserts require updating all nodes with `lft` or `rgt` >= the insertion point. This is O(n) writes per insertion. Deletes similarly require renumbering.
+
+### Worked Example
+
+A 3-level product taxonomy with MPTT numbering:
+
+```
+Electronics (1, 14)
+  Computers (2, 7)
+    Laptops (3, 4)
+    Desktops (5, 6)
+  Phones (8, 11)
+    Smartphones (9, 10)
+  Accessories (12, 13)
+```
+
+**All subcategories of Electronics (lft=1, rgt=14):**
+
+```sql
+SELECT * FROM categories
+WHERE lft BETWEEN 1 AND 14
+ORDER BY lft;
+-- Returns all 7 nodes, no recursion needed
+```
+
+**All ancestors of Smartphones (lft=9, rgt=10):**
+
+```sql
+SELECT * FROM categories
+WHERE lft < 9 AND rgt > 10
+ORDER BY lft;
+-- Returns: Electronics (1,14), Phones (8,11)
+```
+
+**Inserting "Tablets" under Electronics after Phones (rgt=11):**
+
+```sql
+BEGIN;
+
+-- Make room: shift all nodes to the right of insertion point
+UPDATE categories SET rgt = rgt + 2 WHERE rgt > 11;
+UPDATE categories SET lft = lft + 2 WHERE lft > 11;
+
+-- Insert the new node
+INSERT INTO categories (name, lft, rgt) VALUES ('Tablets', 12, 13);
+
+COMMIT;
+```
+
+This updates O(n) rows to insert a single node. On a table with 50K categories, this means potentially updating tens of thousands of rows for one insert.
+
+### Anti-Patterns
+
+1. **Using nested sets for frequently changing hierarchies.** Every insert, delete, or move touches O(n) rows. Use adjacency list or closure table instead.
+2. **Not wrapping modifications in transactions.** Partial renumbering corrupts the tree -- `lft`/`rgt` invariants break and all queries return wrong results.
+3. **Not indexing `(lft, rgt)`.** The entire point of nested sets is fast range queries. Without the composite index, the benefit disappears.
+4. **Mixing adjacency list queries with nested sets without maintaining both.** If you need parent_id for writes, store it alongside lft/rgt and maintain both.
+5. **Using nested sets for trees deeper than a few thousand nodes.** The renumbering cost scales with total tree size, not subtree size.
+
+### PostgreSQL Specifics
+
+**Composite index** for subtree queries:
+
+```sql
+CREATE INDEX idx_categories_lft_rgt ON categories (lft, rgt);
+```
+
+**Locking during modifications** to prevent concurrent renumbering conflicts:
+
+```sql
+-- Option 1: Row-level locks on affected rows
+SELECT * FROM categories WHERE lft > 11 FOR UPDATE;
+
+-- Option 2: Advisory lock for serializing all tree modifications
+SELECT pg_advisory_xact_lock(hashtext('categories_tree'));
+```
+
+Advisory locks are lighter-weight than row locks when modifications are infrequent. The lock is released automatically at transaction end.
+
+**Constraint enforcement:**
+
+```sql
+ALTER TABLE categories ADD CONSTRAINT valid_bounds CHECK (lft < rgt);
+ALTER TABLE categories ADD CONSTRAINT positive_bounds CHECK (lft > 0 AND rgt > 0);
+```
+
+## Details
+
+### Advanced Topics
+
+**Gap-based numbering:** Leave gaps between lft/rgt values (e.g., increment by 100 instead of 1). This allows some inserts without renumbering -- the new node fits in the gap. When gaps are exhausted, perform a full renumbering in batch. Reduces average write cost at the expense of occasional expensive rebuilds.
+
+**Hybrid adjacency list + nested sets:** Store both `parent_id` and `lft/rgt`. Use adjacency list for writes (update parent_id, O(1)), rebuild nested set numbers in batch. Use nested sets for reads (subtree queries without recursion). This is the most practical approach for hierarchies that change moderately.
+
+**Nested intervals:** Use rational numbers (fractions) instead of integers for lft/rgt. New nodes can always be inserted between existing values without renumbering. Adds mathematical complexity but eliminates the O(n) write cost entirely.
+
+### Engine Differences
+
+MySQL nested sets work identically at the SQL level -- the same queries, same indexing strategy.
+
+MySQL's default transaction isolation (REPEATABLE READ) provides stronger consistency guarantees during renumbering than PostgreSQL's default (READ COMMITTED). Concurrent readers in MySQL see a consistent snapshot even during renumbering. However, explicit locking is still recommended in both engines to prevent concurrent writers from corrupting the tree.
+
+MySQL lacks advisory locks. Use `GET_LOCK('categories_tree', 10)` (named lock with 10-second timeout) as the equivalent of PostgreSQL's `pg_advisory_xact_lock()`. Note that `GET_LOCK` is session-scoped, not transaction-scoped -- release explicitly with `RELEASE_LOCK()`.
+
+### Real-World Case Studies
+
+**Retail product catalog with 50K categories, updated weekly via batch import.** The category tree changes every Monday when the merchandising team uploads a new CSV. Nested sets enabled "all products in Electronics and subcategories" aggregation in 2ms versus 45ms with recursive CTE on the same data. The weekly batch rebuild (full renumbering of all 50K nodes) takes 3 seconds -- entirely acceptable for a once-per-week operation. During the rebuild, the previous tree remains queryable via a blue-green table swap pattern.
+
+## Source
+
+- [Joe Celko -- Trees and Hierarchies in SQL](https://www.amazon.com/dp/1558609202)
+- [Wikipedia -- Nested Set Model](https://en.wikipedia.org/wiki/Nested_set_model)
+
+## Process
+
+1. Read the key concepts to understand MPTT numbering and the read/write tradeoff.
+2. Apply nested sets only for hierarchies with high read-to-write ratios.
+3. Verify that all modifications are wrapped in transactions and that subtree queries use the composite `(lft, rgt)` index.
+
+## 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-adjacency-list, db-closure-table, db-hierarchical-data
+
+## Success Criteria
+
+- Nested sets are used only for read-heavy, write-rare hierarchies.
+- All tree modifications are wrapped in transactions with appropriate locking.
+- Composite index on `(lft, rgt)` is present for range queries.
+- The tree is validated after batch operations to confirm `lft`/`rgt` invariants hold.