@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/cursor/db-horizontal-sharding/SKILL.md

@@ -0,0 +1,228 @@
+# Horizontal Sharding
+
+> Distributing rows of a table across multiple database instances (shards) to scale beyond the capacity of a single server, with careful attention to shard key selection and cross-shard query complexity.
+
+## When to Use
+
+- A single PostgreSQL instance cannot handle the write volume or storage requirements
+- Vertical scaling (bigger hardware) has reached its practical or cost limit
+- Multi-tenant applications where tenants can be isolated to separate databases
+- Read-heavy workloads that have already exhausted read replicas
+- Planning data architecture for a system expected to grow beyond 10 TB
+
+## Instructions
+
+### Key Concepts
+
+**1. What Is Horizontal Sharding**
+
+Horizontal sharding splits a table's rows across multiple independent database instances. Each shard holds a subset of the data. The application or a routing layer determines which shard to query based on the shard key.
+
+```
+Unsharded:  [All orders in one database]
+
+Sharded:    Shard 0: orders where tenant_id % 4 = 0
+            Shard 1: orders where tenant_id % 4 = 1
+            Shard 2: orders where tenant_id % 4 = 2
+            Shard 3: orders where tenant_id % 4 = 3
+```
+
+**2. Shard Key Selection**
+
+The shard key determines data distribution. A good shard key:
+
+- Is present in every query (avoids cross-shard scatter)
+- Distributes data evenly (avoids hot shards)
+- Is immutable or rarely changes (avoids shard migration)
+- Aligns with the application's access pattern
+
+```
+Good shard keys:
+  tenant_id   -- multi-tenant SaaS (queries always filter by tenant)
+  user_id     -- social platforms (queries center on a user)
+  region      -- geographically distributed systems
+
+Bad shard keys:
+  created_at  -- all new writes go to the latest shard (hot shard)
+  status      -- highly skewed: most rows are 'active'
+  email       -- rarely used as a query filter
+```
+
+**3. Shard Routing**
+
+```python
+# Hash-based routing (application layer)
+def get_shard(tenant_id: int, num_shards: int) -> int:
+    return tenant_id % num_shards
+
+# Lookup-table routing (more flexible, supports resharding)
+# shard_map table: tenant_id -> shard_id
+def get_shard(tenant_id: int) -> int:
+    return db.query("SELECT shard_id FROM shard_map WHERE tenant_id = %s", tenant_id)
+```
+
+**4. Cross-Shard Queries**
+
+Queries that do not include the shard key must fan out to all shards:
+
+```sql
+-- Shard-local (fast): shard key in WHERE
+SELECT * FROM orders WHERE tenant_id = 42 AND status = 'pending';
+
+-- Cross-shard (slow): no shard key, must query all shards
+SELECT count(*) FROM orders WHERE status = 'pending';
+-- The routing layer sends this to every shard and aggregates results
+```
+
+Minimize cross-shard queries by colocating related data on the same shard.
+
+**5. Consistent Hashing**
+
+Simple modulo hashing (`tenant_id % N`) requires rehashing all data when adding a shard. Consistent hashing maps keys to a ring, so adding a shard only moves keys from adjacent positions:
+
+```
+Hash ring: 0 -------- 1 -------- 2 -------- 3 -------- 0
+           |  Shard A  |  Shard B  |  Shard C  |  Shard A |
+
+Adding Shard D between B and C:
+           |  Shard A  |  Shard B  | D | Shard C |  Shard A |
+-- Only keys between B and D move; all other keys stay put
+```
+
+### Worked Example
+
+Scenario: a B2B SaaS platform with 10,000 tenants needs to shard the orders table by `tenant_id`.
+
+```sql
+-- Step 1: Create shard mapping
+CREATE TABLE shard_map (
+  tenant_id INT PRIMARY KEY,
+  shard_id INT NOT NULL
+);
+
+-- Assign tenants to 4 shards using consistent hashing
+INSERT INTO shard_map (tenant_id, shard_id)
+SELECT id, consistent_hash(id, 4) FROM tenants;
+
+-- Step 2: On each shard, create the orders table
+CREATE TABLE orders (
+  id BIGSERIAL,
+  tenant_id INT NOT NULL,
+  total NUMERIC NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT now(),
+  PRIMARY KEY (tenant_id, id)
+);
+
+-- Step 3: Application routing (pseudocode)
+-- shard = lookup_shard(tenant_id)
+-- connection = get_connection(shard)
+-- connection.execute("INSERT INTO orders ...")
+
+-- Step 4: Cross-shard aggregation (admin dashboard)
+-- Fan out to all shards and merge:
+results = []
+for shard in all_shards:
+    r = shard.query("SELECT count(*), sum(total) FROM orders WHERE created_at > '2024-01-01'")
+    results.append(r)
+total_count = sum(r.count for r in results)
+total_revenue = sum(r.total for r in results)
+```
+
+Using Citus for transparent sharding in PostgreSQL:
+
+```sql
+-- Citus extension: distributed tables on PostgreSQL
+CREATE EXTENSION citus;
+
+-- Designate worker nodes
+SELECT citus_add_node('worker1', 5432);
+SELECT citus_add_node('worker2', 5432);
+
+-- Distribute the orders table by tenant_id
+SELECT create_distributed_table('orders', 'tenant_id');
+
+-- Queries route automatically:
+SELECT * FROM orders WHERE tenant_id = 42;
+-- Citus routes to the correct worker node
+```
+
+### Anti-Patterns
+
+1. **Sharding too early.** Sharding adds enormous complexity: cross-shard joins, distributed transactions, operational overhead. A single well-tuned PostgreSQL instance handles most workloads up to several TB. Exhaust vertical scaling and read replicas before sharding.
+
+2. **Choosing a shard key with high cardinality skew.** If 80% of rows have `status = 'active'`, sharding by `status` puts 80% of data on one shard. Analyze value distribution before choosing a shard key.
+
+3. **Allowing cross-shard joins in application queries.** Cross-shard joins require fetching data from multiple shards and joining in the application or routing layer. This is slow and error-prone. Colocate related tables on the same shard.
+
+4. **Not planning for resharding.** If you start with 4 shards and outgrow them, adding a 5th shard with modulo hashing requires moving ~20% of all data. Use consistent hashing or a lookup table from the start.
+
+5. **Sharding without addressing the cross-shard transaction problem.** Distributed transactions (two-phase commit) across shards are slow and complex. Design the data model so transactions stay within a single shard.
+
+### PostgreSQL Specifics
+
+- **Citus** (open-source extension): adds distributed table support to PostgreSQL. Handles shard routing, cross-shard queries, and colocation transparently. Best option for PostgreSQL-native sharding.
+- **postgres_fdw**: query remote PostgreSQL servers from a coordinator node. Useful for simple cross-shard reads but does not support distributed writes or transactions.
+- **Logical replication**: move data between shards using logical replication slots for resharding with minimal downtime.
+- **pg_dump/pg_restore with --table**: extract a single shard's data for backup or migration.
+
+## Details
+
+### Advanced Topics
+
+**Resharding Strategies:**
+
+1. **Split shard:** Take shard A's data, filter by new hash range, move half to new shard B. Use logical replication to minimize downtime.
+2. **Consistent hashing with virtual nodes:** Map each physical shard to multiple points on the hash ring. Adding a physical shard reassigns virtual nodes, moving less data.
+3. **Lookup table migration:** Update the shard_map for tenants being moved, then migrate their data. Application reads the shard_map for every request, so routing updates automatically.
+
+**Colocation:**
+
+```sql
+-- In Citus, colocate related tables so joins stay shard-local
+SELECT create_distributed_table('orders', 'tenant_id');
+SELECT create_distributed_table('order_items', 'tenant_id',
+  colocate_with => 'orders');
+
+-- This join is shard-local (fast):
+SELECT o.id, oi.product_id FROM orders o
+  JOIN order_items oi ON o.id = oi.order_id AND o.tenant_id = oi.tenant_id
+  WHERE o.tenant_id = 42;
+```
+
+**Global Tables (Reference Tables):** Small, rarely-changing tables (countries, currencies, config) are replicated to every shard so joins do not require cross-shard communication.
+
+### Engine Differences
+
+MySQL sharding is typically done via **Vitess** (YouTube's sharding middleware) or application-level routing. Vitess provides a SQL-aware proxy that routes queries based on a `vindex` (virtual index). It supports resharding, cross-shard queries, and distributed transactions. Vitess is more mature for MySQL sharding than Citus is for PostgreSQL, having been in production at YouTube since 2011.
+
+MySQL's native partitioning is single-instance only -- it does not distribute across servers. For multi-server sharding, an external solution like Vitess or ProxySQL is required.
+
+### Real-World Case Studies
+
+Notion sharded their PostgreSQL database to handle growth beyond a single instance. They sharded by `workspace_id` (their tenant key), ensuring all data for a workspace lives on the same shard. The migration from a single database to sharded architecture took 6 months. Key decisions: consistent hashing with virtual nodes for future resharding, Citus for transparent routing, and a lookup table for workspace-to-shard mapping. Cross-shard queries were eliminated by colocating all workspace-related tables. After sharding, write throughput increased 4x and they could add capacity by adding shards without downtime.
+
+## Source
+
+- [Citus Documentation](https://docs.citusdata.com/en/stable/)
+- [Vitess Documentation](https://vitess.io/docs/)
+- Kleppmann, M. "Designing Data-Intensive Applications" (2017), Chapter 6
+
+## Process
+
+1. Exhaust vertical scaling and read replicas before considering sharding.
+2. Select a shard key based on dominant query patterns and even data distribution.
+3. Implement shard routing (consistent hashing or lookup table) and colocate related tables.
+4. Plan the resharding strategy before the first shard is created.
+
+## 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-table-partitioning, db-vertical-partitioning, db-cap-theorem, db-eventual-consistency
+
+## Success Criteria
+
+- Sharding is adopted only after vertical scaling and read replicas are insufficient.
+- The shard key is present in all dominant query patterns, distributes data evenly, and is immutable.
+- Related tables are colocated on the same shard to avoid cross-shard joins.
+- A resharding strategy (consistent hashing or lookup table) is in place before the first shard is created.

package/dist/agents/skills/cursor/db-horizontal-sharding/skill.yaml

@@ -0,0 +1,40 @@
+name: db-horizontal-sharding
+version: '1.0.0'
+description: Shard key selection, cross-shard queries, resharding strategies, and consistent hashing
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-table-partitioning
+  - db-vertical-partitioning
+  - db-cap-theorem
+  - db-eventual-consistency
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - horizontal-sharding
+  - shard-key
+  - cross-shard
+  - resharding
+  - consistent-hashing
+  - citus
+  - vitess
+metadata:
+  author: community
+  upstream: docs.citusdata.com/en/stable/develop/migration.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/db-isolation-levels/SKILL.md

@@ -0,0 +1,158 @@
+# Isolation Levels
+
+> The four SQL standard isolation levels control which concurrent transaction side-effects are visible, with PostgreSQL implementing them via MVCC snapshots rather than traditional locking.
+
+## When to Use
+
+- Choosing transaction isolation for a new feature
+- Debugging phantom reads or non-repeatable reads in concurrent workloads
+- Understanding why PostgreSQL's "Read Uncommitted" behaves like Read Committed
+- Performance tuning concurrent workloads that experience serialization failures
+- Evaluating isolation requirements when migrating between PostgreSQL and MySQL
+
+## Instructions
+
+### Key Concepts
+
+**1. Read Uncommitted**
+
+Can see uncommitted changes from other transactions. PostgreSQL does not implement this level -- it silently upgrades to Read Committed. MySQL InnoDB supports it but it is rarely useful in production.
+
+**2. Read Committed (PostgreSQL default)**
+
+Each statement sees only data committed before that statement began. Different statements within the same transaction can see different committed snapshots. This is sufficient for the vast majority of web application workloads.
+
+```sql
+SET TRANSACTION ISOLATION LEVEL READ COMMITTED;
+
+BEGIN;
+SELECT balance FROM accounts WHERE id = 1;  -- sees 500
+-- Another session commits: UPDATE accounts SET balance = 400 WHERE id = 1;
+SELECT balance FROM accounts WHERE id = 1;  -- sees 400 (new commit visible)
+COMMIT;
+```
+
+**3. Repeatable Read**
+
+The transaction sees a snapshot taken at the first non-transaction-control statement. All queries within the transaction see the same snapshot. PostgreSQL raises a serialization error on write conflicts instead of blocking.
+
+```sql
+SET TRANSACTION ISOLATION LEVEL REPEATABLE READ;
+
+BEGIN;
+SELECT balance FROM accounts WHERE id = 1;  -- sees 500 (snapshot taken)
+-- Another session commits: UPDATE accounts SET balance = 400 WHERE id = 1;
+SELECT balance FROM accounts WHERE id = 1;  -- still sees 500 (snapshot unchanged)
+COMMIT;
+```
+
+**4. Serializable**
+
+Full serializable isolation via Serializable Snapshot Isolation (SSI). Transactions appear to execute one at a time. PostgreSQL detects read/write dependency cycles and aborts one transaction with `ERROR: could not serialize access`.
+
+```sql
+SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
+```
+
+### Worked Example
+
+Two-session demonstration of Read Committed vs Repeatable Read:
+
+```
+Session A (Read Committed)              Session B
+-------------------------------         ----------------------------
+BEGIN;
+SELECT balance FROM accounts
+  WHERE id = 1;
+  -- returns 500
+                                        BEGIN;
+                                        UPDATE accounts SET balance = 400
+                                          WHERE id = 1;
+                                        COMMIT;
+SELECT balance FROM accounts
+  WHERE id = 1;
+  -- returns 400 (sees B's commit)
+COMMIT;
+
+Session A (Repeatable Read)             Session B
+-------------------------------         ----------------------------
+BEGIN ISOLATION LEVEL REPEATABLE READ;
+SELECT balance FROM accounts
+  WHERE id = 1;
+  -- returns 500 (snapshot taken)
+                                        BEGIN;
+                                        UPDATE accounts SET balance = 400
+                                          WHERE id = 1;
+                                        COMMIT;
+SELECT balance FROM accounts
+  WHERE id = 1;
+  -- still returns 500 (snapshot frozen)
+UPDATE accounts SET balance = balance + 100
+  WHERE id = 1;
+  -- ERROR: could not serialize access
+  -- (row was modified after snapshot)
+COMMIT;
+```
+
+Under Repeatable Read, Session A's update fails because the row was modified after its snapshot. The application must catch this error and retry the entire transaction.
+
+### Anti-Patterns
+
+1. **Using Serializable everywhere "for safety."** Unnecessary serialization failures and retries for workloads that only need Read Committed. Most CRUD operations are safe at Read Committed.
+
+2. **Assuming Repeatable Read prevents all anomalies.** Write skew is still possible under PostgreSQL Repeatable Read. Two transactions can read overlapping data and write non-overlapping data that together violate a business constraint. See `db-read-phenomena`.
+
+3. **Not handling serialization failures.** Serializable and Repeatable Read can raise `ERROR: could not serialize access`. Application code must catch `SQLSTATE 40001` and retry the entire transaction, not just the failed statement.
+
+### PostgreSQL Specifics
+
+- PostgreSQL's Read Uncommitted is actually Read Committed -- there is no way to see uncommitted data
+- PostgreSQL uses SSI (predicate locking) for Serializable, not traditional two-phase locking
+- Set session-level defaults: `SET default_transaction_isolation = 'repeatable read';`
+- Inspect current level: `SHOW transaction_isolation;`
+- Per-transaction override: `BEGIN ISOLATION LEVEL SERIALIZABLE;`
+
+## Details
+
+### Advanced Topics
+
+**SSI Implementation:** PostgreSQL tracks SIRead locks (predicate locks) and rw-dependency edges between transactions. When a dangerous structure (a cycle of rw-dependencies) is detected, one transaction is aborted. This is optimistic -- transactions proceed without blocking, and conflicts are detected at commit time.
+
+**Performance overhead:** Serializable adds approximately 5-15% overhead in typical OLTP workloads due to predicate lock tracking. The overhead scales with the number of concurrent serializable transactions.
+
+**Monitoring:** Use `pg_stat_activity.backend_xid` and `pg_stat_activity.backend_xmin` to identify transactions holding old snapshots. Long-running transactions under Repeatable Read or Serializable prevent VACUUM from reclaiming dead tuples.
+
+### Engine Differences
+
+MySQL InnoDB defaults to **Repeatable Read** (not Read Committed like PostgreSQL). This has practical implications when migrating applications between engines.
+
+MySQL uses **gap locking** for Repeatable Read to prevent phantom inserts. PostgreSQL uses MVCC snapshots instead, which means PostgreSQL Repeatable Read does not block concurrent inserts but may raise serialization errors on write conflicts.
+
+MySQL's **Serializable** uses shared read locks on all SELECT statements, which reduces concurrency significantly compared to PostgreSQL's SSI approach. PostgreSQL's SSI is optimistic (no blocking, abort-on-conflict), while MySQL's is pessimistic (blocking reads).
+
+### Real-World Case Studies
+
+A financial reporting system ran end-of-day balance calculations under Read Committed. Reports that executed during active trading showed inconsistent totals -- a report might see some accounts with pre-trade balances and others with post-trade balances within the same query window. Switching the reporting transactions to Repeatable Read gave each report a consistent point-in-time snapshot, eliminating the inconsistencies without affecting the trading system's throughput.
+
+## Source
+
+- [PostgreSQL Transaction Isolation](https://www.postgresql.org/docs/current/transaction-iso.html)
+- Ports, D. & Grittner, K. "Serializable Snapshot Isolation in PostgreSQL" (VLDB 2012)
+
+## Process
+
+1. Identify the correctness requirements of your transaction (what anomalies are unacceptable).
+2. Select the minimum isolation level that prevents those anomalies using the phenomena matrix from `db-read-phenomena`.
+3. Implement retry logic for any transaction running at Repeatable Read or Serializable.
+
+## 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-read-phenomena, db-isolation-selection, db-acid-properties, db-mvcc, db-pessimistic-locking, prisma-transactions, drizzle-transactions
+
+## Success Criteria
+
+- Correct isolation level selected for the workload's actual requirements
+- Serialization errors handled with retry logic (catch `SQLSTATE 40001`, retry entire transaction)
+- No unnecessary use of Serializable for workloads safe at Read Committed

package/dist/agents/skills/cursor/db-isolation-levels/skill.yaml

@@ -0,0 +1,43 @@
+name: db-isolation-levels
+version: '1.0.0'
+description: Read uncommitted through serializable -- PostgreSQL's MVCC-based isolation implementation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-read-phenomena
+  - db-isolation-selection
+  - db-acid-properties
+  - db-mvcc
+  - db-pessimistic-locking
+  - prisma-transactions
+  - drizzle-transactions
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - isolation-levels
+  - read-uncommitted
+  - read-committed
+  - repeatable-read
+  - serializable
+  - MVCC
+  - transaction-isolation
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/transaction-iso.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/db-isolation-selection/SKILL.md

@@ -0,0 +1,160 @@
+# Isolation Level Selection
+
+> Selecting the right isolation level requires matching the workload's correctness requirements against the performance cost and retry complexity of stricter levels.
+
+## When to Use
+
+- Starting a new feature with transaction requirements
+- Optimizing transaction throughput by downgrading unnecessarily strict isolation
+- Debugging serialization failures that seem unnecessary
+- Deciding between isolation level upgrades and application-level locking
+- Reviewing transaction design during code review
+
+## Instructions
+
+### Key Concepts
+
+**Decision Framework**
+
+**1. Read Committed (default -- use for most workloads)**
+
+CRUD operations, form submissions, content management. Low overhead, no retry logic needed. Works for 90% of web application transactions. Only unsafe when business logic depends on re-reading the same rows within a transaction.
+
+**2. Repeatable Read**
+
+Reporting queries that must see a consistent snapshot, balance calculations, read-heavy analytics within a transaction. Adds the cost of potential serialization failures on write conflicts. Requires retry logic.
+
+**3. Serializable**
+
+Financial transfers, inventory management with complex constraints, any workflow where write skew would violate business invariants. Requires retry logic for every transaction. Expect ~5-15% throughput reduction.
+
+**4. Alternative: Explicit Locking**
+
+`SELECT FOR UPDATE` within Read Committed can prevent specific races without the full overhead of Serializable. See `db-pessimistic-locking`. Preferred when only a few rows need protection.
+
+**Decision Table**
+
+| Workload Type       | Recommended Level | Retry Required | Notes                        |
+| ------------------- | ----------------- | -------------- | ---------------------------- |
+| Simple CRUD         | Read Committed    | No             | Default, sufficient for most |
+| Form submit / save  | Read Committed    | No             | Single write, no re-reads    |
+| Report / analytics  | Repeatable Read   | Yes            | Consistent snapshot needed   |
+| Balance calculation | Repeatable Read   | Yes            | Must see consistent totals   |
+| Financial transfer  | Serializable      | Yes            | Write skew would lose money  |
+| Inventory decrement | RC + FOR UPDATE   | No             | Targeted lock, less overhead |
+| Queue processing    | RC + SKIP LOCKED  | No             | See db-pessimistic-locking   |
+
+### Worked Example
+
+E-commerce checkout -- comparing two approaches for preventing overselling:
+
+**Approach A: Serializable Isolation**
+
+```sql
+BEGIN ISOLATION LEVEL SERIALIZABLE;
+
+SELECT stock FROM products WHERE id = 42;  -- returns 3
+-- Application logic: verify stock >= requested quantity
+
+UPDATE products SET stock = stock - 1 WHERE id = 42;
+INSERT INTO orders (product_id, quantity) VALUES (42, 1);
+
+COMMIT;
+-- May raise: ERROR: could not serialize access
+-- Application must retry entire transaction
+```
+
+**Approach B: Read Committed with SELECT FOR UPDATE**
+
+```sql
+BEGIN;  -- Read Committed (default)
+
+SELECT stock FROM products WHERE id = 42 FOR UPDATE;  -- returns 3, row locked
+-- Other transactions block here until we commit
+
+UPDATE products SET stock = stock - 1 WHERE id = 42;
+INSERT INTO orders (product_id, quantity) VALUES (42, 1);
+
+COMMIT;
+-- No serialization error possible -- lock prevents conflict
+```
+
+**Trade-off analysis:** Approach B is preferred for this workload. The lock targets only the inventory row, other products are unaffected. Approach A applies serializable checking to the entire transaction including the orders insert, which is unnecessary overhead. Approach B also eliminates the need for retry logic.
+
+### Anti-Patterns
+
+1. **Setting Serializable as the database default.** All transactions pay the serialization cost, even simple reads. Set isolation per-transaction where needed instead.
+
+2. **Choosing isolation level per-table instead of per-transaction.** Isolation applies to the entire transaction, not individual tables or queries. There is no way to use Serializable for one table and Read Committed for another within the same transaction.
+
+3. **Upgrading isolation to "fix bugs" without understanding the root cause.** The bug may be in application logic, not a concurrency anomaly. Diagnose first using `db-read-phenomena` before changing isolation levels.
+
+4. **No retry loop for Repeatable Read or Serializable.** These levels raise serialization errors by design. The application must catch `SQLSTATE 40001` and retry the entire transaction with exponential backoff.
+
+### PostgreSQL Specifics
+
+- Set session default: `SET default_transaction_isolation = 'read committed';`
+- Per-transaction override: `BEGIN ISOLATION LEVEL SERIALIZABLE;`
+- Prevent snapshot-holding: `idle_in_transaction_session_timeout = '30s'` kills idle transactions
+- Monitor serialization failures: `pg_stat_database.conflicts` and application-level error counters
+- Read-only Serializable with `DEFERRABLE`: zero-abort reporting queries
+
+## Details
+
+### Advanced Topics
+
+**Retry loop pattern:**
+
+```sql
+-- Pseudocode for serializable retry
+max_retries = 3
+for attempt in range(max_retries):
+    try:
+        BEGIN ISOLATION LEVEL SERIALIZABLE;
+        -- ... transaction logic ...
+        COMMIT;
+        break  -- success
+    except SerializationFailure:
+        -- SQLSTATE 40001
+        ROLLBACK;
+        sleep(random_backoff(attempt))  -- jitter: 10ms * 2^attempt
+else:
+    raise TooManyRetries()
+```
+
+**Read-only Serializable with DEFERRABLE:** For reporting queries that need a consistent snapshot without any risk of abort, use `BEGIN ISOLATION LEVEL SERIALIZABLE READ ONLY DEFERRABLE;`. PostgreSQL may delay the start slightly to find a safe snapshot, but the transaction will never abort.
+
+**Connection pool implications:** Transaction-level isolation means the pool must not reuse connections mid-transaction. Configure pool to use transaction-level pooling (e.g., PgBouncer `pool_mode = transaction`), and ensure isolation level is set within the transaction, not at the session level.
+
+### Engine Differences
+
+MySQL defaults to **Repeatable Read**, so applications migrating from MySQL to PostgreSQL may experience different behavior at the default isolation level. MySQL's gap locking provides some phantom protection that PostgreSQL handles differently via MVCC.
+
+MySQL **Serializable** uses shared locks on all SELECT statements (pessimistic, blocking). PostgreSQL SSI is optimistic (abort-on-conflict, no blocking). This means MySQL Serializable has lower throughput but fewer retries, while PostgreSQL Serializable has higher throughput but requires retry logic.
+
+### Real-World Case Studies
+
+A SaaS platform ran all transactions at Serializable, experiencing a 15% serialization failure rate during peak hours. Profiling showed 80% of transactions were simple CRUD (user profile updates, content edits) that only needed Read Committed. Selectively downgrading CRUD transactions to Read Committed while keeping Serializable for billing and subscription workflows reduced the failure rate from 15% to 0.3% and improved p99 latency by 40%.
+
+## Source
+
+- [PostgreSQL Transaction Isolation](https://www.postgresql.org/docs/current/transaction-iso.html)
+- Kleppmann, M. "Designing Data-Intensive Applications" (2017), Chapter 7
+
+## Process
+
+1. Identify the correctness requirements: which read phenomena would violate business invariants?
+2. Select the minimum isolation level from the decision table, or use explicit locking for targeted protection.
+3. Implement retry logic for any transaction using Repeatable Read or Serializable, and monitor serialization failure rates.
+
+## 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-properties, db-optimistic-locking, db-pessimistic-locking, prisma-transactions, drizzle-transactions
+
+## Success Criteria
+
+- Isolation level chosen matches actual workload requirements (not over- or under-specified)
+- Retry logic present for every Repeatable Read and Serializable transaction
+- Serialization failure rates monitored and below acceptable thresholds

package/dist/agents/skills/cursor/db-isolation-selection/skill.yaml

@@ -0,0 +1,41 @@
+name: db-isolation-selection
+version: '1.0.0'
+description: Choosing isolation levels for specific workloads -- performance vs correctness trade-offs
+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-properties
+  - db-optimistic-locking
+  - db-pessimistic-locking
+  - prisma-transactions
+  - drizzle-transactions
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - isolation-selection
+  - workload-analysis
+  - performance-correctness
+  - retry-strategy
+  - transaction-design
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/transaction-iso.html
+state:
+  persistent: false
+  files: []
+depends_on: []