@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/cursor/db-composite-index/SKILL.md

@@ -0,0 +1,199 @@
+# Composite Indexes
+
+> Multi-column indexes that accelerate queries filtering on column combinations, governed by the leftmost prefix rule and the ESR (Equality, Sort, Range) column ordering strategy.
+
+## When to Use
+
+- Queries filtering on multiple columns together in WHERE clauses
+- Multi-column ORDER BY optimization
+- Queries combining WHERE conditions and ORDER BY on different columns
+- Replacing multiple single-column indexes with one efficient composite
+
+## Instructions
+
+### Key Concepts
+
+A composite index stores entries sorted by multiple columns in declaration order. Think of it like a phone book sorted by (last_name, first_name) -- you can look up by last name alone, or by last name and first name together, but not by first name alone.
+
+**Syntax:**
+
+```sql
+CREATE INDEX idx_orders_status_date ON orders (status, created_at);
+```
+
+**The leftmost prefix rule.** An index on (a, b, c) supports queries on:
+
+- (a) -- uses the index
+- (a, b) -- uses the index
+- (a, b, c) -- uses the full index
+
+But NOT:
+
+- (b) alone -- cannot skip the leading column
+- (c) alone -- cannot skip leading columns
+- (b, c) -- cannot skip the leading column
+
+**The ESR rule** for column ordering -- Equality, Sort, Range:
+
+1. **Equality columns first** -- columns compared with `=`
+2. **Sort columns next** -- columns in ORDER BY
+3. **Range columns last** -- columns with `<`, `>`, `BETWEEN`
+
+This order maximizes the portion of the index the planner can use in a single scan.
+
+```sql
+-- ESR-optimized for: WHERE tenant_id = ? AND status = ? ORDER BY created_at
+CREATE INDEX idx_orders_esr ON orders (tenant_id, status, created_at);
+```
+
+### Worked Example
+
+Multi-tenant SaaS orders table with 50M rows:
+
+```sql
+CREATE TABLE orders (
+  id         SERIAL PRIMARY KEY,
+  tenant_id  INT NOT NULL,
+  status     TEXT NOT NULL,
+  total      NUMERIC(10,2) NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_orders_composite ON orders (tenant_id, status, created_at);
+```
+
+**Query 1 -- full index usage (all three columns):**
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, total FROM orders
+WHERE tenant_id = 5 AND status = 'active' AND created_at > '2024-01-01';
+```
+
+```
+Index Scan using idx_orders_composite on orders
+  (cost=0.56..1245.32 rows=4521 width=14)
+  (actual time=0.028..3.412 rows=4380 loops=1)
+  Index Cond: (tenant_id = 5 AND status = 'active' AND created_at > '2024-01-01')
+Execution Time: 3.891 ms
+```
+
+**Query 2 -- partial index usage (first column only):**
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, total FROM orders
+WHERE tenant_id = 5 AND created_at > '2024-01-01';
+```
+
+```
+Index Scan using idx_orders_composite on orders
+  (cost=0.56..8923.12 rows=45210 width=14)
+  (actual time=0.031..89.452 rows=43800 loops=1)
+  Index Cond: (tenant_id = 5)
+  Filter: (created_at > '2024-01-01')
+  Rows Removed by Filter: 6200
+```
+
+The index is used for `tenant_id` but `created_at` is applied as a filter after fetching rows, because `status` (the second column) was skipped.
+
+**Query 3 -- index not usable (skips leading column):**
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, total FROM orders
+WHERE status = 'active';
+```
+
+```
+Seq Scan on orders
+  (cost=0.00..1234567.00 rows=5000000 width=14)
+  (actual time=0.021..4521.330 rows=4980000 loops=1)
+  Filter: (status = 'active')
+```
+
+The composite index cannot be used because the query skips `tenant_id` (the leftmost column).
+
+### Anti-Patterns
+
+1. **Separate single-column indexes instead of one composite.** The planner can combine single-column indexes via Bitmap AND, but this is significantly slower than a single composite index scan. One well-designed composite outperforms multiple singles.
+
+2. **Wrong column order -- range before equality.**
+   BAD: `CREATE INDEX ON orders (created_at, tenant_id)` for `WHERE tenant_id = ? AND created_at > ?`
+   GOOD: `CREATE INDEX ON orders (tenant_id, created_at)` -- equality first, range second.
+
+3. **Too many columns.** Each additional column increases index size and write overhead with diminishing returns. Most composites should have 2-4 columns.
+
+4. **Duplicating the leading column.** If you have an index on `(tenant_id, status)`, a separate index on `(tenant_id)` alone is redundant -- the composite already supports queries on just `tenant_id`.
+
+### PostgreSQL Specifics
+
+PostgreSQL can use a composite index on (a, b) for `WHERE a = 1 ORDER BY b` without a separate sort step -- the index already produces results in the correct order.
+
+**Monitoring composite index usage:**
+
+```sql
+SELECT indexrelname, idx_scan, idx_tup_read, idx_tup_fetch
+FROM pg_stat_user_indexes
+WHERE indexrelname = 'idx_orders_composite';
+```
+
+**Index-only scans with composites.** If the composite index contains all columns in the SELECT list, PostgreSQL performs an Index Only Scan. See db-covering-index for details.
+
+## Details
+
+### Advanced Topics
+
+**Index skip scan (PostgreSQL 16+).** In some cases, PostgreSQL can skip over distinct values of the leading column, allowing the index on (a, b) to be used for queries on just (b). This is not yet as mature as Oracle's skip scan but is improving with each release.
+
+**Mixed ASC/DESC ordering.** For queries with `ORDER BY a ASC, b DESC`, create:
+
+```sql
+CREATE INDEX idx_mixed ON orders (a ASC, b DESC);
+```
+
+Without matching sort directions, PostgreSQL must perform a separate sort step.
+
+**Index size growth.** Each additional column increases the index size roughly in proportion to the column's average width. Monitor with `pg_relation_size()`.
+
+### Engine Differences
+
+MySQL InnoDB applies the same leftmost prefix rule for composite indexes. Key differences:
+
+- **No index skip scan.** MySQL cannot skip leading columns at all -- the leftmost prefix rule is strictly enforced.
+- **Index merge optimization.** MySQL may combine single-column indexes using "index merge" as an alternative to composites. This is almost always slower than a well-designed composite.
+- **Column limit.** MySQL supports up to 16 columns in a composite index (PostgreSQL allows 32).
+- **Clustered index impact.** In InnoDB, secondary composite indexes store the primary key at each leaf. This means wider primary keys inflate all secondary indexes.
+
+### Real-World Case Studies
+
+**E-commerce dashboard with 100M orders.** The dashboard query was `WHERE merchant_id = ? AND status = ? AND created_at BETWEEN ? AND ?`. The system had three separate single-column indexes on `merchant_id`, `status`, and `created_at`. The planner used Bitmap AND to combine them, taking 800ms per query.
+
+Replacing all three with one composite `(merchant_id, status, created_at)` following ESR ordering:
+
+- Query time dropped from 800ms to 5ms (160x improvement)
+- Three indexes (4.5GB total) replaced by one (1.5GB) -- saved 3GB of storage
+- Write throughput improved 12% due to maintaining one index instead of three
+
+## Source
+
+- [PostgreSQL Multicolumn Indexes](https://www.postgresql.org/docs/current/indexes-multicolumn.html)
+- [Use The Index, Luke -- Concatenated Index](https://use-the-index-luke.com/sql/where-clause/the-equals-operator/concatenated-keys)
+
+## Process
+
+1. Read the key concepts to understand the leftmost prefix rule and ESR ordering.
+2. Apply composite indexes following ESR order for your actual query patterns, consolidating single-column indexes where possible.
+3. Verify with EXPLAIN ANALYZE that the planner uses the composite index and that column ordering matches your query workload.
+
+## 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-covering-index, db-partial-index, db-explain-reading, db-scan-types
+
+## Success Criteria
+
+- Composite indexes follow ESR column ordering for the target query workload.
+- The leftmost prefix rule is respected -- no queries depend on skipping leading columns.
+- Redundant single-column indexes on leading columns are identified and removed.

package/dist/agents/skills/cursor/db-composite-index/skill.yaml

@@ -0,0 +1,41 @@
+name: db-composite-index
+version: '1.0.0'
+description: Multi-column indexes, column ordering strategy, and the leftmost prefix rule
+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-covering-index
+  - db-partial-index
+  - db-explain-reading
+  - db-scan-types
+  - prisma-performance-patterns
+  - drizzle-performance-patterns
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - composite-index
+  - multi-column-index
+  - leftmost-prefix
+  - column-ordering
+  - compound-index
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/indexes-multicolumn.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/db-connection-pooling/SKILL.md

@@ -0,0 +1,196 @@
+# Connection Pooling
+
+> External connection poolers like PgBouncer sit between the application and database, multiplexing many application connections onto fewer database connections to prevent connection exhaustion.
+
+## When to Use
+
+- Application has more processes/threads than the database can handle with direct connections
+- Seeing `FATAL: too many connections` errors in PostgreSQL logs
+- Running a microservices architecture where each service opens its own connection pool
+- Deploying to serverless environments where connection reuse is difficult
+- Tuning PgBouncer or a similar pooler for a production workload
+
+## Instructions
+
+### Key Concepts
+
+**1. Why Pool Externally**
+
+PostgreSQL forks a backend process for each connection. Each process consumes 5-10 MB of memory. At 500 connections, that is 2.5-5 GB of memory just for connection overhead, plus contention on shared resources like `ProcArrayLock`. An external pooler holds a small number of database connections (20-100) and multiplexes thousands of application connections onto them.
+
+**2. PgBouncer Pool Modes**
+
+```ini
+; pgbouncer.ini
+
+[databases]
+mydb = host=127.0.0.1 port=5432 dbname=mydb
+
+[pgbouncer]
+listen_port = 6432
+pool_mode = transaction   ; session | transaction | statement
+max_client_conn = 1000    ; max application connections to PgBouncer
+default_pool_size = 25    ; database connections per user/database pair
+reserve_pool_size = 5     ; extra connections for burst traffic
+reserve_pool_timeout = 3  ; seconds before reserve pool activates
+```
+
+**Session mode:** A database connection is assigned when the client connects and released when the client disconnects. Safest but least efficient -- almost no multiplexing benefit.
+
+**Transaction mode:** A database connection is assigned at `BEGIN` and released at `COMMIT`/`ROLLBACK`. Best balance of safety and efficiency. Most production deployments use this mode.
+
+**Statement mode:** A database connection is assigned per statement. Only works for simple, autocommit queries. Breaks multi-statement transactions.
+
+**3. Transaction Mode Limitations**
+
+In transaction mode, session-level state is lost between transactions:
+
+```sql
+-- These features BREAK in transaction mode:
+SET search_path = 'tenant_1';  -- lost after transaction ends
+PREPARE my_stmt AS SELECT ...;  -- lost after transaction ends
+LISTEN channel_name;            -- lost after transaction ends
+CREATE TEMP TABLE tmp (...);    -- lost after transaction ends
+
+-- These features WORK in transaction mode:
+BEGIN; ... COMMIT;              -- transactions work normally
+SET LOCAL search_path = '...';  -- scoped to transaction, OK
+```
+
+**4. Pool Sizing Formula**
+
+```
+default_pool_size = max_database_connections / number_of_pooler_instances
+
+Example:
+  PostgreSQL max_connections = 100
+  Reserved for superuser/monitoring = 10
+  Available for application = 90
+  PgBouncer instances = 2
+
+  default_pool_size = 90 / 2 = 45 per instance
+```
+
+The `max_client_conn` can be much larger because PgBouncer queues requests when all database connections are busy.
+
+### Worked Example
+
+A SaaS platform runs 12 microservices, each maintaining a connection pool of 20 connections. That is 240 direct connections, but the PostgreSQL instance only supports 100.
+
+```ini
+; pgbouncer.ini
+[databases]
+saasdb = host=db.internal port=5432 dbname=saasdb
+
+[pgbouncer]
+listen_port = 6432
+pool_mode = transaction
+max_client_conn = 500
+default_pool_size = 40
+reserve_pool_size = 10
+reserve_pool_timeout = 3
+server_idle_timeout = 300
+server_lifetime = 3600
+log_connections = 0
+log_disconnections = 0
+```
+
+Each microservice connects to PgBouncer on port 6432 instead of PostgreSQL on port 5432. PgBouncer maintains 40 real database connections and queues excess requests. The 12 services can open up to 500 connections to PgBouncer combined, but only 40-50 database connections are active at any time.
+
+Monitor with the PgBouncer admin console:
+
+```sql
+-- Connect to PgBouncer admin
+psql -p 6432 -U pgbouncer pgbouncer
+
+-- Check pool status
+SHOW POOLS;
+-- cl_active: application connections actively using a database connection
+-- cl_waiting: application connections waiting for a database connection
+-- sv_active: database connections processing a query
+-- sv_idle: database connections idle and available
+
+-- Check connection counts
+SHOW STATS;
+```
+
+### Anti-Patterns
+
+1. **Setting `default_pool_size` equal to `max_connections`.** This defeats the purpose of pooling. The pool size should be a fraction of max_connections, leaving room for superuser connections, monitoring, and burst capacity.
+
+2. **Using session mode with short-lived connections.** Session mode holds a database connection for the entire client session. If clients connect, run one query, and disconnect, session mode provides zero multiplexing benefit and adds latency from PgBouncer's overhead.
+
+3. **Using `PREPARE` statements in transaction mode.** Prepared statements are session-level state. In transaction mode, the next transaction may get a different backend connection where the prepared statement does not exist, causing `ERROR: prepared statement does not exist`.
+
+4. **Running PgBouncer and the application on the same host without connection limits.** If the application opens more connections than PgBouncer can queue, both PgBouncer and the application compete for the same CPU and memory. Run PgBouncer on a dedicated host or set strict `max_client_conn` limits.
+
+5. **Not monitoring `cl_waiting`.** If `cl_waiting` is consistently above zero, application connections are waiting for database connections. Either increase `default_pool_size` (if the database can handle it) or optimize query performance to release connections faster.
+
+### PostgreSQL Specifics
+
+- PostgreSQL 14+ built-in connection pooling is limited to `connection_pool_size` for parallel query workers; it does not pool client connections. External pooling is still required.
+- `pgbouncer_fdw` provides PgBouncer stats as PostgreSQL foreign tables for integration with monitoring dashboards.
+- Supabase Vibes uses PgBouncer in transaction mode by default for serverless deployments.
+- AWS RDS Proxy and Google Cloud SQL Auth Proxy provide managed pooling with IAM authentication.
+
+## Details
+
+### Advanced Topics
+
+**Application-Level vs External Pooling:** Most application frameworks include a built-in connection pool (e.g., HikariCP for Java, database/sql for Go). These manage connections within a single process. External poolers like PgBouncer manage connections across all processes. Use both: the application pool manages per-process concurrency, and PgBouncer manages database-level concurrency.
+
+**Multi-Database Pooling:**
+
+```ini
+[databases]
+db1 = host=primary.db port=5432 dbname=db1
+db2 = host=primary.db port=5432 dbname=db2
+db1_ro = host=replica.db port=5432 dbname=db1
+```
+
+Route read queries to replicas by connecting to `db1_ro` instead of `db1`.
+
+**PgBouncer Authentication:**
+
+```ini
+auth_type = scram-sha-256
+auth_file = /etc/pgbouncer/userlist.txt
+; Or delegate to PostgreSQL:
+auth_type = hba
+auth_hba_file = /etc/pgbouncer/pg_hba.conf
+```
+
+### Engine Differences
+
+MySQL's connection model differs fundamentally: MySQL uses one thread per connection rather than one process per connection. Threads are lighter-weight (typically 256KB-1MB stack per thread vs 5-10MB per PostgreSQL process). MySQL handles more concurrent connections natively, but thread contention becomes a bottleneck beyond a few thousand connections.
+
+ProxySQL serves a similar role to PgBouncer for MySQL. It supports query routing, connection multiplexing, and read-write splitting. ProxySQL uses a regex-based query routing system that is more feature-rich than PgBouncer but more complex to configure.
+
+### Real-World Case Studies
+
+A ride-sharing platform ran 200 microservices, each with a pool of 10 connections, totaling 2,000 direct database connections. PostgreSQL was spending more time managing connections than processing queries. Deploying PgBouncer in transaction mode with `default_pool_size = 80` and `max_client_conn = 5000` reduced actual database connections from 2,000 to 80. Query latency at p99 dropped from 450ms to 120ms because PostgreSQL's shared buffer management was no longer thrashing. The `cl_waiting` metric showed occasional queuing during peak hours, resolved by increasing `default_pool_size` to 100.
+
+## Source
+
+- [PgBouncer Documentation](https://www.pgbouncer.org/)
+- [PostgreSQL Connection Handling](https://www.postgresql.org/docs/current/runtime-config-connection.html)
+
+## Process
+
+1. Deploy PgBouncer between the application and PostgreSQL; start with `pool_mode = transaction`.
+2. Set `default_pool_size` to `(max_connections - reserved) / pooler_instances`.
+3. Update application connection strings to point to PgBouncer's port.
+4. Monitor `SHOW POOLS` for `cl_waiting` and `sv_idle` to tune pool sizing.
+
+## 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-connection-sizing, db-acid-in-practice, db-isolation-levels
+
+## Success Criteria
+
+- An external connection pooler (PgBouncer or equivalent) is deployed between the application and PostgreSQL.
+- Pool mode is set to `transaction` unless session-level features require `session` mode.
+- `default_pool_size` is calculated from `max_connections` and the number of pooler instances, not set arbitrarily.
+- `cl_waiting` is monitored and remains near zero during normal traffic.

package/dist/agents/skills/cursor/db-connection-pooling/skill.yaml

@@ -0,0 +1,39 @@
+name: db-connection-pooling
+version: '1.0.0'
+description: PgBouncer configuration, pool modes (session/transaction/statement), and sizing formulas
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-connection-sizing
+  - db-acid-in-practice
+  - db-isolation-levels
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - connection-pooling
+  - pgbouncer
+  - session-mode
+  - transaction-mode
+  - statement-mode
+  - pool-sizing
+  - connection-pool
+metadata:
+  author: community
+  upstream: pgbouncer.github.io/config.html
+state:
+  persistent: false
+  files: []
+depends_on: []