@oriro/orirocli 0.1.9 → 0.1.11

package/skills/craft/supabase-postgres-best-practices/references/_template.md

@@ -1,34 +1,34 @@
----
-title: Clear, Action-Oriented Title (e.g., "Use Partial Indexes for Filtered Queries")
-impact: MEDIUM
-impactDescription: 5-20x query speedup for filtered queries
-tags: indexes, query-optimization, performance
----
-
-## [Rule Title]
-
-[1-2 sentence explanation of the problem and why it matters. Focus on performance impact.]
-
-**Incorrect (describe the problem):**
-
-```sql
--- Comment explaining what makes this slow/problematic
-CREATE INDEX users_email_idx ON users(email);
-
-SELECT * FROM users WHERE email = '<email>' AND deleted_at IS NULL;
--- This scans deleted records unnecessarily
-```
-
-**Correct (describe the solution):**
-
-```sql
--- Comment explaining why this is better
-CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
-
-SELECT * FROM users WHERE email = '<email>' AND deleted_at IS NULL;
--- Only indexes active users, 10x smaller index, faster queries
-```
-
-[Optional: Additional context, edge cases, or trade-offs]
-
-Reference: [Postgres Docs](https://www.postgresql.org/docs/current/)
+---
+title: Clear, Action-Oriented Title (e.g., "Use Partial Indexes for Filtered Queries")
+impact: MEDIUM
+impactDescription: 5-20x query speedup for filtered queries
+tags: indexes, query-optimization, performance
+---
+
+## [Rule Title]
+
+[1-2 sentence explanation of the problem and why it matters. Focus on performance impact.]
+
+**Incorrect (describe the problem):**
+
+```sql
+-- Comment explaining what makes this slow/problematic
+CREATE INDEX users_email_idx ON users(email);
+
+SELECT * FROM users WHERE email = '<email>' AND deleted_at IS NULL;
+-- This scans deleted records unnecessarily
+```
+
+**Correct (describe the solution):**
+
+```sql
+-- Comment explaining why this is better
+CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
+
+SELECT * FROM users WHERE email = '<email>' AND deleted_at IS NULL;
+-- Only indexes active users, 10x smaller index, faster queries
+```
+
+[Optional: Additional context, edge cases, or trade-offs]
+
+Reference: [Postgres Docs](https://www.postgresql.org/docs/current/)

package/skills/craft/supabase-postgres-best-practices/references/advanced-full-text-search.md

@@ -1,55 +1,55 @@
----
-title: Use tsvector for Full-Text Search
-impact: MEDIUM
-impactDescription: 100x faster than LIKE, with ranking support
-tags: full-text-search, tsvector, gin, search
----
-
-## Use tsvector for Full-Text Search
-
-LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
-
-**Incorrect (LIKE pattern matching):**
-
-```sql
--- Cannot use index, scans all rows
-select * from articles where content like '%postgresql%';
-
--- Case-insensitive makes it worse
-select * from articles where lower(content) like '%postgresql%';
-```
-
-**Correct (full-text search with tsvector):**
-
-```sql
--- Add tsvector column and index
-alter table articles add column search_vector tsvector
-  generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
-
-create index articles_search_idx on articles using gin (search_vector);
-
--- Fast full-text search
-select * from articles
-where search_vector @@ to_tsquery('english', 'postgresql & performance');
-
--- With ranking
-select *, ts_rank(search_vector, query) as rank
-from articles, to_tsquery('english', 'postgresql') query
-where search_vector @@ query
-order by rank desc;
-```
-
-Search multiple terms:
-
-```sql
--- AND: both terms required
-to_tsquery('postgresql & performance')
-
--- OR: either term
-to_tsquery('postgresql | mysql')
-
--- Prefix matching
-to_tsquery('post:*')
-```
-
-Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)
+---
+title: Use tsvector for Full-Text Search
+impact: MEDIUM
+impactDescription: 100x faster than LIKE, with ranking support
+tags: full-text-search, tsvector, gin, search
+---
+
+## Use tsvector for Full-Text Search
+
+LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
+
+**Incorrect (LIKE pattern matching):**
+
+```sql
+-- Cannot use index, scans all rows
+select * from articles where content like '%postgresql%';
+
+-- Case-insensitive makes it worse
+select * from articles where lower(content) like '%postgresql%';
+```
+
+**Correct (full-text search with tsvector):**
+
+```sql
+-- Add tsvector column and index
+alter table articles add column search_vector tsvector
+  generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
+
+create index articles_search_idx on articles using gin (search_vector);
+
+-- Fast full-text search
+select * from articles
+where search_vector @@ to_tsquery('english', 'postgresql & performance');
+
+-- With ranking
+select *, ts_rank(search_vector, query) as rank
+from articles, to_tsquery('english', 'postgresql') query
+where search_vector @@ query
+order by rank desc;
+```
+
+Search multiple terms:
+
+```sql
+-- AND: both terms required
+to_tsquery('postgresql & performance')
+
+-- OR: either term
+to_tsquery('postgresql | mysql')
+
+-- Prefix matching
+to_tsquery('post:*')
+```
+
+Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)

package/skills/craft/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md

@@ -1,49 +1,49 @@
----
-title: Index JSONB Columns for Efficient Querying
-impact: MEDIUM
-impactDescription: 10-100x faster JSONB queries with proper indexing
-tags: jsonb, gin, indexes, json
----
-
-## Index JSONB Columns for Efficient Querying
-
-JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
-
-**Incorrect (no index on JSONB):**
-
-```sql
-create table products (
-  id bigint primary key,
-  attributes jsonb
-);
-
--- Full table scan for every query
-select * from products where attributes @> '{"color": "red"}';
-select * from products where attributes->>'brand' = 'Nike';
-```
-
-**Correct (GIN index for JSONB):**
-
-```sql
--- GIN index for containment operators (@>, ?, ?&, ?|)
-create index products_attrs_gin on products using gin (attributes);
-
--- Now containment queries use the index
-select * from products where attributes @> '{"color": "red"}';
-
--- For specific key lookups, use expression index
-create index products_brand_idx on products ((attributes->>'brand'));
-select * from products where attributes->>'brand' = 'Nike';
-```
-
-Choose the right operator class:
-
-```sql
--- jsonb_ops (default): supports all operators, larger index
-create index idx1 on products using gin (attributes);
-
--- jsonb_path_ops: only @> operator, but 2-3x smaller index
-create index idx2 on products using gin (attributes jsonb_path_ops);
-```
-
-Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)
+---
+title: Index JSONB Columns for Efficient Querying
+impact: MEDIUM
+impactDescription: 10-100x faster JSONB queries with proper indexing
+tags: jsonb, gin, indexes, json
+---
+
+## Index JSONB Columns for Efficient Querying
+
+JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
+
+**Incorrect (no index on JSONB):**
+
+```sql
+create table products (
+  id bigint primary key,
+  attributes jsonb
+);
+
+-- Full table scan for every query
+select * from products where attributes @> '{"color": "red"}';
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+**Correct (GIN index for JSONB):**
+
+```sql
+-- GIN index for containment operators (@>, ?, ?&, ?|)
+create index products_attrs_gin on products using gin (attributes);
+
+-- Now containment queries use the index
+select * from products where attributes @> '{"color": "red"}';
+
+-- For specific key lookups, use expression index
+create index products_brand_idx on products ((attributes->>'brand'));
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+Choose the right operator class:
+
+```sql
+-- jsonb_ops (default): supports all operators, larger index
+create index idx1 on products using gin (attributes);
+
+-- jsonb_path_ops: only @> operator, but 2-3x smaller index
+create index idx2 on products using gin (attributes jsonb_path_ops);
+```
+
+Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)

package/skills/craft/supabase-postgres-best-practices/references/conn-idle-timeout.md

@@ -1,46 +1,46 @@
----
-title: Configure Idle Connection Timeouts
-impact: HIGH
-impactDescription: Reclaim 30-50% of connection slots from idle clients
-tags: connections, timeout, idle, resource-management
----
-
-## Configure Idle Connection Timeouts
-
-Idle connections waste resources. Configure timeouts to automatically reclaim them.
-
-**Incorrect (connections held indefinitely):**
-
-```sql
--- No timeout configured
-show idle_in_transaction_session_timeout;  -- 0 (disabled)
-
--- Connections stay open forever, even when idle
-select pid, state, state_change, query
-from pg_stat_activity
-where state = 'idle in transaction';
--- Shows transactions idle for hours, holding locks
-```
-
-**Correct (automatic cleanup of idle connections):**
-
-```sql
--- Terminate connections idle in transaction after 30 seconds
-alter system set idle_in_transaction_session_timeout = '30s';
-
--- Terminate completely idle connections after 10 minutes
-alter system set idle_session_timeout = '10min';
-
--- Reload configuration
-select pg_reload_conf();
-```
-
-For pooled connections, configure at the pooler level:
-
-```ini
-# pgbouncer.ini
-server_idle_timeout = 60
-client_idle_timeout = 300
-```
-
-Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)
+---
+title: Configure Idle Connection Timeouts
+impact: HIGH
+impactDescription: Reclaim 30-50% of connection slots from idle clients
+tags: connections, timeout, idle, resource-management
+---
+
+## Configure Idle Connection Timeouts
+
+Idle connections waste resources. Configure timeouts to automatically reclaim them.
+
+**Incorrect (connections held indefinitely):**
+
+```sql
+-- No timeout configured
+show idle_in_transaction_session_timeout;  -- 0 (disabled)
+
+-- Connections stay open forever, even when idle
+select pid, state, state_change, query
+from pg_stat_activity
+where state = 'idle in transaction';
+-- Shows transactions idle for hours, holding locks
+```
+
+**Correct (automatic cleanup of idle connections):**
+
+```sql
+-- Terminate connections idle in transaction after 30 seconds
+alter system set idle_in_transaction_session_timeout = '30s';
+
+-- Terminate completely idle connections after 10 minutes
+alter system set idle_session_timeout = '10min';
+
+-- Reload configuration
+select pg_reload_conf();
+```
+
+For pooled connections, configure at the pooler level:
+
+```ini
+# pgbouncer.ini
+server_idle_timeout = 60
+client_idle_timeout = 300
+```
+
+Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)

package/skills/craft/supabase-postgres-best-practices/references/conn-limits.md

@@ -1,44 +1,44 @@
----
-title: Set Appropriate Connection Limits
-impact: CRITICAL
-impactDescription: Prevent database crashes and memory exhaustion
-tags: connections, max-connections, limits, stability
----
-
-## Set Appropriate Connection Limits
-
-Too many connections exhaust memory and degrade performance. Set limits based on available resources.
-
-**Incorrect (unlimited or excessive connections):**
-
-```sql
--- Default max_connections = 100, but often increased blindly
-show max_connections;  -- 500 (way too high for 4GB RAM)
-
--- Each connection uses 1-3MB RAM
--- 500 connections * 2MB = 1GB just for connections!
--- Out of memory errors under load
-```
-
-**Correct (calculate based on resources):**
-
-```sql
--- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
--- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
--- But practically, 100-200 is better for query performance
-
--- Recommended settings for 4GB RAM
-alter system set max_connections = 100;
-
--- Also set work_mem appropriately
--- work_mem * max_connections should not exceed 25% of RAM
-alter system set work_mem = '8MB';  -- 8MB * 100 = 800MB max
-```
-
-Monitor connection usage:
-
-```sql
-select count(*), state from pg_stat_activity group by state;
-```
-
-Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)
+---
+title: Set Appropriate Connection Limits
+impact: CRITICAL
+impactDescription: Prevent database crashes and memory exhaustion
+tags: connections, max-connections, limits, stability
+---
+
+## Set Appropriate Connection Limits
+
+Too many connections exhaust memory and degrade performance. Set limits based on available resources.
+
+**Incorrect (unlimited or excessive connections):**
+
+```sql
+-- Default max_connections = 100, but often increased blindly
+show max_connections;  -- 500 (way too high for 4GB RAM)
+
+-- Each connection uses 1-3MB RAM
+-- 500 connections * 2MB = 1GB just for connections!
+-- Out of memory errors under load
+```
+
+**Correct (calculate based on resources):**
+
+```sql
+-- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
+-- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
+-- But practically, 100-200 is better for query performance
+
+-- Recommended settings for 4GB RAM
+alter system set max_connections = 100;
+
+-- Also set work_mem appropriately
+-- work_mem * max_connections should not exceed 25% of RAM
+alter system set work_mem = '8MB';  -- 8MB * 100 = 800MB max
+```
+
+Monitor connection usage:
+
+```sql
+select count(*), state from pg_stat_activity group by state;
+```
+
+Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)

package/skills/craft/supabase-postgres-best-practices/references/conn-pooling.md

@@ -1,41 +1,41 @@
----
-title: Use Connection Pooling for All Applications
-impact: CRITICAL
-impactDescription: Handle 10-100x more concurrent users
-tags: connection-pooling, pgbouncer, performance, scalability
----
-
-## Use Connection Pooling for All Applications
-
-Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
-
-**Incorrect (new connection per request):**
-
-```sql
--- Each request creates a new connection
--- Application code: db.connect() per request
--- Result: 500 concurrent users = 500 connections = crashed database
-
--- Check current connections
-select count(*) from pg_stat_activity;  -- 487 connections!
-```
-
-**Correct (connection pooling):**
-
-```sql
--- Use a pooler like PgBouncer between app and database
--- Application connects to pooler, pooler reuses a small pool to Postgres
-
--- Configure pool_size based on: (CPU cores * 2) + spindle_count
--- Example for 4 cores: pool_size = 10
-
--- Result: 500 concurrent users share 10 actual connections
-select count(*) from pg_stat_activity;  -- 10 connections
-```
-
-Pool modes:
-
-- **Transaction mode**: connection returned after each transaction (best for most apps)
-- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
-
-Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)
+---
+title: Use Connection Pooling for All Applications
+impact: CRITICAL
+impactDescription: Handle 10-100x more concurrent users
+tags: connection-pooling, pgbouncer, performance, scalability
+---
+
+## Use Connection Pooling for All Applications
+
+Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
+
+**Incorrect (new connection per request):**
+
+```sql
+-- Each request creates a new connection
+-- Application code: db.connect() per request
+-- Result: 500 concurrent users = 500 connections = crashed database
+
+-- Check current connections
+select count(*) from pg_stat_activity;  -- 487 connections!
+```
+
+**Correct (connection pooling):**
+
+```sql
+-- Use a pooler like PgBouncer between app and database
+-- Application connects to pooler, pooler reuses a small pool to Postgres
+
+-- Configure pool_size based on: (CPU cores * 2) + spindle_count
+-- Example for 4 cores: pool_size = 10
+
+-- Result: 500 concurrent users share 10 actual connections
+select count(*) from pg_stat_activity;  -- 10 connections
+```
+
+Pool modes:
+
+- **Transaction mode**: connection returned after each transaction (best for most apps)
+- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
+
+Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)

package/skills/craft/supabase-postgres-best-practices/references/conn-prepared-statements.md

@@ -1,46 +1,46 @@
----
-title: Use Prepared Statements Correctly with Pooling
-impact: HIGH
-impactDescription: Avoid prepared statement conflicts in pooled environments
-tags: prepared-statements, connection-pooling, transaction-mode
----
-
-## Use Prepared Statements Correctly with Pooling
-
-Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
-
-**Incorrect (named prepared statements with transaction pooling):**
-
-```sql
--- Named prepared statement
-prepare get_user as select * from users where id = $1;
-
--- In transaction mode pooling, next request may get different connection
-execute get_user(123);
--- ERROR: prepared statement "get_user" does not exist
-```
-
-**Correct (use unnamed statements or session mode):**
-
-```sql
--- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
--- The query is prepared and executed in a single protocol message
-
--- Option 2: Deallocate after use in transaction mode
-prepare get_user as select * from users where id = $1;
-execute get_user(123);
-deallocate get_user;
-
--- Option 3: Use session mode pooling (port 5432 vs 6543)
--- Connection is held for entire session, prepared statements persist
-```
-
-Check your driver settings:
-
-```sql
--- Many drivers use prepared statements by default
--- Node.js pg: { prepare: false } to disable
--- JDBC: prepareThreshold=0 to disable
-```
-
-Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)
+---
+title: Use Prepared Statements Correctly with Pooling
+impact: HIGH
+impactDescription: Avoid prepared statement conflicts in pooled environments
+tags: prepared-statements, connection-pooling, transaction-mode
+---
+
+## Use Prepared Statements Correctly with Pooling
+
+Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
+
+**Incorrect (named prepared statements with transaction pooling):**
+
+```sql
+-- Named prepared statement
+prepare get_user as select * from users where id = $1;
+
+-- In transaction mode pooling, next request may get different connection
+execute get_user(123);
+-- ERROR: prepared statement "get_user" does not exist
+```
+
+**Correct (use unnamed statements or session mode):**
+
+```sql
+-- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
+-- The query is prepared and executed in a single protocol message
+
+-- Option 2: Deallocate after use in transaction mode
+prepare get_user as select * from users where id = $1;
+execute get_user(123);
+deallocate get_user;
+
+-- Option 3: Use session mode pooling (port 5432 vs 6543)
+-- Connection is held for entire session, prepared statements persist
+```
+
+Check your driver settings:
+
+```sql
+-- Many drivers use prepared statements by default
+-- Node.js pg: { prepare: false } to disable
+-- JDBC: prepareThreshold=0 to disable
+```
+
+Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)