@oriro/orirocli 0.1.11 → 0.1.12

package/skills/craft/supabase-postgres-best-practices/references/lock-short-transactions.md

@@ -1,50 +1,50 @@
----
-title: Keep Transactions Short to Reduce Lock Contention
-impact: MEDIUM-HIGH
-impactDescription: 3-5x throughput improvement, fewer deadlocks
-tags: transactions, locking, contention, performance
----
-
-## Keep Transactions Short to Reduce Lock Contention
-
-Long-running transactions hold locks that block other queries. Keep transactions as short as possible.
-
-**Incorrect (long transaction with external calls):**
-
-```sql
-begin;
-select * from orders where id = 1 for update;  -- Lock acquired
-
--- Application makes HTTP call to payment API (2-5 seconds)
--- Other queries on this row are blocked!
-
-update orders set status = 'paid' where id = 1;
-commit;  -- Lock held for entire duration
-```
-
-**Correct (minimal transaction scope):**
-
-```sql
--- Validate data and call APIs outside transaction
--- Application: response = await paymentAPI.charge(...)
-
--- Only hold lock for the actual update
-begin;
-update orders
-set status = 'paid', payment_id = $1
-where id = $2 and status = 'pending'
-returning *;
-commit;  -- Lock held for milliseconds
-```
-
-Use `statement_timeout` to prevent runaway transactions:
-
-```sql
--- Abort queries running longer than 30 seconds
-set statement_timeout = '30s';
-
--- Or per-session
-set local statement_timeout = '5s';
-```
-
-Reference: [Transaction Management](https://www.postgresql.org/docs/current/tutorial-transactions.html)
+---
+title: Keep Transactions Short to Reduce Lock Contention
+impact: MEDIUM-HIGH
+impactDescription: 3-5x throughput improvement, fewer deadlocks
+tags: transactions, locking, contention, performance
+---
+
+## Keep Transactions Short to Reduce Lock Contention
+
+Long-running transactions hold locks that block other queries. Keep transactions as short as possible.
+
+**Incorrect (long transaction with external calls):**
+
+```sql
+begin;
+select * from orders where id = 1 for update;  -- Lock acquired
+
+-- Application makes HTTP call to payment API (2-5 seconds)
+-- Other queries on this row are blocked!
+
+update orders set status = 'paid' where id = 1;
+commit;  -- Lock held for entire duration
+```
+
+**Correct (minimal transaction scope):**
+
+```sql
+-- Validate data and call APIs outside transaction
+-- Application: response = await paymentAPI.charge(...)
+
+-- Only hold lock for the actual update
+begin;
+update orders
+set status = 'paid', payment_id = $1
+where id = $2 and status = 'pending'
+returning *;
+commit;  -- Lock held for milliseconds
+```
+
+Use `statement_timeout` to prevent runaway transactions:
+
+```sql
+-- Abort queries running longer than 30 seconds
+set statement_timeout = '30s';
+
+-- Or per-session
+set local statement_timeout = '5s';
+```
+
+Reference: [Transaction Management](https://www.postgresql.org/docs/current/tutorial-transactions.html)

package/skills/craft/supabase-postgres-best-practices/references/lock-skip-locked.md

@@ -1,54 +1,54 @@
----
-title: Use SKIP LOCKED for Non-Blocking Queue Processing
-impact: MEDIUM-HIGH
-impactDescription: 10x throughput for worker queues
-tags: skip-locked, queue, workers, concurrency
----
-
-## Use SKIP LOCKED for Non-Blocking Queue Processing
-
-When multiple workers process a queue, SKIP LOCKED allows workers to process different rows without waiting.
-
-**Incorrect (workers block each other):**
-
-```sql
--- Worker 1 and Worker 2 both try to get next job
-begin;
-select * from jobs where status = 'pending' order by created_at limit 1 for update;
--- Worker 2 waits for Worker 1's lock to release!
-```
-
-**Correct (SKIP LOCKED for parallel processing):**
-
-```sql
--- Each worker skips locked rows and gets the next available
-begin;
-select * from jobs
-where status = 'pending'
-order by created_at
-limit 1
-for update skip locked;
-
--- Worker 1 gets job 1, Worker 2 gets job 2 (no waiting)
-
-update jobs set status = 'processing' where id = $1;
-commit;
-```
-
-Complete queue pattern:
-
-```sql
--- Atomic claim-and-update in one statement
-update jobs
-set status = 'processing', worker_id = $1, started_at = now()
-where id = (
-  select id from jobs
-  where status = 'pending'
-  order by created_at
-  limit 1
-  for update skip locked
-)
-returning *;
-```
-
-Reference: [SELECT FOR UPDATE SKIP LOCKED](https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE)
+---
+title: Use SKIP LOCKED for Non-Blocking Queue Processing
+impact: MEDIUM-HIGH
+impactDescription: 10x throughput for worker queues
+tags: skip-locked, queue, workers, concurrency
+---
+
+## Use SKIP LOCKED for Non-Blocking Queue Processing
+
+When multiple workers process a queue, SKIP LOCKED allows workers to process different rows without waiting.
+
+**Incorrect (workers block each other):**
+
+```sql
+-- Worker 1 and Worker 2 both try to get next job
+begin;
+select * from jobs where status = 'pending' order by created_at limit 1 for update;
+-- Worker 2 waits for Worker 1's lock to release!
+```
+
+**Correct (SKIP LOCKED for parallel processing):**
+
+```sql
+-- Each worker skips locked rows and gets the next available
+begin;
+select * from jobs
+where status = 'pending'
+order by created_at
+limit 1
+for update skip locked;
+
+-- Worker 1 gets job 1, Worker 2 gets job 2 (no waiting)
+
+update jobs set status = 'processing' where id = $1;
+commit;
+```
+
+Complete queue pattern:
+
+```sql
+-- Atomic claim-and-update in one statement
+update jobs
+set status = 'processing', worker_id = $1, started_at = now()
+where id = (
+  select id from jobs
+  where status = 'pending'
+  order by created_at
+  limit 1
+  for update skip locked
+)
+returning *;
+```
+
+Reference: [SELECT FOR UPDATE SKIP LOCKED](https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE)

package/skills/craft/supabase-postgres-best-practices/references/monitor-explain-analyze.md

@@ -1,45 +1,45 @@
----
-title: Use EXPLAIN ANALYZE to Diagnose Slow Queries
-impact: LOW-MEDIUM
-impactDescription: Identify exact bottlenecks in query execution
-tags: explain, analyze, diagnostics, query-plan
----
-
-## Use EXPLAIN ANALYZE to Diagnose Slow Queries
-
-EXPLAIN ANALYZE executes the query and shows actual timings, revealing the true performance bottlenecks.
-
-**Incorrect (guessing at performance issues):**
-
-```sql
--- Query is slow, but why?
-select * from orders where customer_id = 123 and status = 'pending';
--- "It must be missing an index" - but which one?
-```
-
-**Correct (use EXPLAIN ANALYZE):**
-
-```sql
-explain (analyze, buffers, format text)
-select * from orders where customer_id = 123 and status = 'pending';
-
--- Output reveals the issue:
--- Seq Scan on orders (cost=0.00..25000.00 rows=50 width=100) (actual time=0.015..450.123 rows=50 loops=1)
---   Filter: ((customer_id = 123) AND (status = 'pending'::text))
---   Rows Removed by Filter: 999950
---   Buffers: shared hit=5000 read=15000
--- Planning Time: 0.150 ms
--- Execution Time: 450.500 ms
-```
-
-Key things to look for:
-
-```sql
--- Seq Scan on large tables = missing index
--- Rows Removed by Filter = poor selectivity or missing index
--- Buffers: read >> hit = data not cached, needs more memory
--- Nested Loop with high loops = consider different join strategy
--- Sort Method: external merge = work_mem too low
-```
-
-Reference: [EXPLAIN](https://supabase.com/docs/guides/database/inspect)
+---
+title: Use EXPLAIN ANALYZE to Diagnose Slow Queries
+impact: LOW-MEDIUM
+impactDescription: Identify exact bottlenecks in query execution
+tags: explain, analyze, diagnostics, query-plan
+---
+
+## Use EXPLAIN ANALYZE to Diagnose Slow Queries
+
+EXPLAIN ANALYZE executes the query and shows actual timings, revealing the true performance bottlenecks.
+
+**Incorrect (guessing at performance issues):**
+
+```sql
+-- Query is slow, but why?
+select * from orders where customer_id = 123 and status = 'pending';
+-- "It must be missing an index" - but which one?
+```
+
+**Correct (use EXPLAIN ANALYZE):**
+
+```sql
+explain (analyze, buffers, format text)
+select * from orders where customer_id = 123 and status = 'pending';
+
+-- Output reveals the issue:
+-- Seq Scan on orders (cost=0.00..25000.00 rows=50 width=100) (actual time=0.015..450.123 rows=50 loops=1)
+--   Filter: ((customer_id = 123) AND (status = 'pending'::text))
+--   Rows Removed by Filter: 999950
+--   Buffers: shared hit=5000 read=15000
+-- Planning Time: 0.150 ms
+-- Execution Time: 450.500 ms
+```
+
+Key things to look for:
+
+```sql
+-- Seq Scan on large tables = missing index
+-- Rows Removed by Filter = poor selectivity or missing index
+-- Buffers: read >> hit = data not cached, needs more memory
+-- Nested Loop with high loops = consider different join strategy
+-- Sort Method: external merge = work_mem too low
+```
+
+Reference: [EXPLAIN](https://supabase.com/docs/guides/database/inspect)

package/skills/craft/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md

@@ -1,55 +1,55 @@
----
-title: Enable pg_stat_statements for Query Analysis
-impact: LOW-MEDIUM
-impactDescription: Identify top resource-consuming queries
-tags: pg-stat-statements, monitoring, statistics, performance
----
-
-## Enable pg_stat_statements for Query Analysis
-
-pg_stat_statements tracks execution statistics for all queries, helping identify slow and frequent queries.
-
-**Incorrect (no visibility into query patterns):**
-
-```sql
--- Database is slow, but which queries are the problem?
--- No way to know without pg_stat_statements
-```
-
-**Correct (enable and query pg_stat_statements):**
-
-```sql
--- Enable the extension
-create extension if not exists pg_stat_statements;
-
--- Find slowest queries by total time
-select
-  calls,
-  round(total_exec_time::numeric, 2) as total_time_ms,
-  round(mean_exec_time::numeric, 2) as mean_time_ms,
-  query
-from pg_stat_statements
-order by total_exec_time desc
-limit 10;
-
--- Find most frequent queries
-select calls, query
-from pg_stat_statements
-order by calls desc
-limit 10;
-
--- Reset statistics after optimization
-select pg_stat_statements_reset();
-```
-
-Key metrics to monitor:
-
-```sql
--- Queries with high mean time (candidates for optimization)
-select query, mean_exec_time, calls
-from pg_stat_statements
-where mean_exec_time > 100  -- > 100ms average
-order by mean_exec_time desc;
-```
-
-Reference: [pg_stat_statements](https://supabase.com/docs/guides/database/extensions/pg_stat_statements)
+---
+title: Enable pg_stat_statements for Query Analysis
+impact: LOW-MEDIUM
+impactDescription: Identify top resource-consuming queries
+tags: pg-stat-statements, monitoring, statistics, performance
+---
+
+## Enable pg_stat_statements for Query Analysis
+
+pg_stat_statements tracks execution statistics for all queries, helping identify slow and frequent queries.
+
+**Incorrect (no visibility into query patterns):**
+
+```sql
+-- Database is slow, but which queries are the problem?
+-- No way to know without pg_stat_statements
+```
+
+**Correct (enable and query pg_stat_statements):**
+
+```sql
+-- Enable the extension
+create extension if not exists pg_stat_statements;
+
+-- Find slowest queries by total time
+select
+  calls,
+  round(total_exec_time::numeric, 2) as total_time_ms,
+  round(mean_exec_time::numeric, 2) as mean_time_ms,
+  query
+from pg_stat_statements
+order by total_exec_time desc
+limit 10;
+
+-- Find most frequent queries
+select calls, query
+from pg_stat_statements
+order by calls desc
+limit 10;
+
+-- Reset statistics after optimization
+select pg_stat_statements_reset();
+```
+
+Key metrics to monitor:
+
+```sql
+-- Queries with high mean time (candidates for optimization)
+select query, mean_exec_time, calls
+from pg_stat_statements
+where mean_exec_time > 100  -- > 100ms average
+order by mean_exec_time desc;
+```
+
+Reference: [pg_stat_statements](https://supabase.com/docs/guides/database/extensions/pg_stat_statements)

package/skills/craft/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md

@@ -1,55 +1,55 @@
----
-title: Maintain Table Statistics with VACUUM and ANALYZE
-impact: MEDIUM
-impactDescription: 2-10x better query plans with accurate statistics
-tags: vacuum, analyze, statistics, maintenance, autovacuum
----
-
-## Maintain Table Statistics with VACUUM and ANALYZE
-
-Outdated statistics cause the query planner to make poor decisions. VACUUM reclaims space, ANALYZE updates statistics.
-
-**Incorrect (stale statistics):**
-
-```sql
--- Table has 1M rows but stats say 1000
--- Query planner chooses wrong strategy
-explain select * from orders where status = 'pending';
--- Shows: Seq Scan (because stats show small table)
--- Actually: Index Scan would be much faster
-```
-
-**Correct (maintain fresh statistics):**
-
-```sql
--- Manually analyze after large data changes
-analyze orders;
-
--- Analyze specific columns used in WHERE clauses
-analyze orders (status, created_at);
-
--- Check when tables were last analyzed
-select
-  relname,
-  last_vacuum,
-  last_autovacuum,
-  last_analyze,
-  last_autoanalyze
-from pg_stat_user_tables
-order by last_analyze nulls first;
-```
-
-Autovacuum tuning for busy tables:
-
-```sql
--- Increase frequency for high-churn tables
-alter table orders set (
-  autovacuum_vacuum_scale_factor = 0.05,     -- Vacuum at 5% dead tuples (default 20%)
-  autovacuum_analyze_scale_factor = 0.02     -- Analyze at 2% changes (default 10%)
-);
-
--- Check autovacuum status
-select * from pg_stat_progress_vacuum;
-```
-
-Reference: [VACUUM](https://supabase.com/docs/guides/database/database-size#vacuum-operations)
+---
+title: Maintain Table Statistics with VACUUM and ANALYZE
+impact: MEDIUM
+impactDescription: 2-10x better query plans with accurate statistics
+tags: vacuum, analyze, statistics, maintenance, autovacuum
+---
+
+## Maintain Table Statistics with VACUUM and ANALYZE
+
+Outdated statistics cause the query planner to make poor decisions. VACUUM reclaims space, ANALYZE updates statistics.
+
+**Incorrect (stale statistics):**
+
+```sql
+-- Table has 1M rows but stats say 1000
+-- Query planner chooses wrong strategy
+explain select * from orders where status = 'pending';
+-- Shows: Seq Scan (because stats show small table)
+-- Actually: Index Scan would be much faster
+```
+
+**Correct (maintain fresh statistics):**
+
+```sql
+-- Manually analyze after large data changes
+analyze orders;
+
+-- Analyze specific columns used in WHERE clauses
+analyze orders (status, created_at);
+
+-- Check when tables were last analyzed
+select
+  relname,
+  last_vacuum,
+  last_autovacuum,
+  last_analyze,
+  last_autoanalyze
+from pg_stat_user_tables
+order by last_analyze nulls first;
+```
+
+Autovacuum tuning for busy tables:
+
+```sql
+-- Increase frequency for high-churn tables
+alter table orders set (
+  autovacuum_vacuum_scale_factor = 0.05,     -- Vacuum at 5% dead tuples (default 20%)
+  autovacuum_analyze_scale_factor = 0.02     -- Analyze at 2% changes (default 10%)
+);
+
+-- Check autovacuum status
+select * from pg_stat_progress_vacuum;
+```
+
+Reference: [VACUUM](https://supabase.com/docs/guides/database/database-size#vacuum-operations)

package/skills/craft/supabase-postgres-best-practices/references/query-composite-indexes.md

@@ -1,44 +1,44 @@
----
-title: Create Composite Indexes for Multi-Column Queries
-impact: HIGH
-impactDescription: 5-10x faster multi-column queries
-tags: indexes, composite-index, multi-column, query-optimization
----
-
-## Create Composite Indexes for Multi-Column Queries
-
-When queries filter on multiple columns, a composite index is more efficient than separate single-column indexes.
-
-**Incorrect (separate indexes require bitmap scan):**
-
-```sql
--- Two separate indexes
-create index orders_status_idx on orders (status);
-create index orders_created_idx on orders (created_at);
-
--- Query must combine both indexes (slower)
-select * from orders where status = 'pending' and created_at > '2024-01-01';
-```
-
-**Correct (composite index):**
-
-```sql
--- Single composite index (leftmost column first for equality checks)
-create index orders_status_created_idx on orders (status, created_at);
-
--- Query uses one efficient index scan
-select * from orders where status = 'pending' and created_at > '2024-01-01';
-```
-
-**Column order matters** - place equality columns first, range columns last:
-
-```sql
--- Good: status (=) before created_at (>)
-create index idx on orders (status, created_at);
-
--- Works for: WHERE status = 'pending'
--- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
--- Does NOT work for: WHERE created_at > '2024-01-01' (leftmost prefix rule)
-```
-
-Reference: [Multicolumn Indexes](https://www.postgresql.org/docs/current/indexes-multicolumn.html)
+---
+title: Create Composite Indexes for Multi-Column Queries
+impact: HIGH
+impactDescription: 5-10x faster multi-column queries
+tags: indexes, composite-index, multi-column, query-optimization
+---
+
+## Create Composite Indexes for Multi-Column Queries
+
+When queries filter on multiple columns, a composite index is more efficient than separate single-column indexes.
+
+**Incorrect (separate indexes require bitmap scan):**
+
+```sql
+-- Two separate indexes
+create index orders_status_idx on orders (status);
+create index orders_created_idx on orders (created_at);
+
+-- Query must combine both indexes (slower)
+select * from orders where status = 'pending' and created_at > '2024-01-01';
+```
+
+**Correct (composite index):**
+
+```sql
+-- Single composite index (leftmost column first for equality checks)
+create index orders_status_created_idx on orders (status, created_at);
+
+-- Query uses one efficient index scan
+select * from orders where status = 'pending' and created_at > '2024-01-01';
+```
+
+**Column order matters** - place equality columns first, range columns last:
+
+```sql
+-- Good: status (=) before created_at (>)
+create index idx on orders (status, created_at);
+
+-- Works for: WHERE status = 'pending'
+-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
+-- Does NOT work for: WHERE created_at > '2024-01-01' (leftmost prefix rule)
+```
+
+Reference: [Multicolumn Indexes](https://www.postgresql.org/docs/current/indexes-multicolumn.html)