jorgex-stack 1.0.1 → 1.0.2

package/stack/skills/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/stack/skills/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/stack/skills/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/stack/skills/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/stack/skills/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)

package/stack/skills/supabase-postgres-best-practices/references/data-batch-inserts.md

@@ -1,54 +1,54 @@
----
-title: Batch INSERT Statements for Bulk Data
-impact: MEDIUM
-impactDescription: 10-50x faster bulk inserts
-tags: batch, insert, bulk, performance, copy
----
-
-## Batch INSERT Statements for Bulk Data
-
-Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
-
-**Incorrect (individual inserts):**
-
-```sql
--- Each insert is a separate transaction and round trip
-insert into events (user_id, action) values (1, 'click');
-insert into events (user_id, action) values (1, 'view');
-insert into events (user_id, action) values (2, 'click');
--- ... 1000 more individual inserts
-
--- 1000 inserts = 1000 round trips = slow
-```
-
-**Correct (batch insert):**
-
-```sql
--- Multiple rows in single statement
-insert into events (user_id, action) values
-  (1, 'click'),
-  (1, 'view'),
-  (2, 'click'),
-  -- ... up to ~1000 rows per batch
-  (999, 'view');
-
--- One round trip for 1000 rows
-```
-
-For large imports, use COPY:
-
-```sql
--- COPY is fastest for bulk loading
-copy events (user_id, action, created_at)
-from '/path/to/data.csv'
-with (format csv, header true);
-
--- Or from stdin in application
-copy events (user_id, action) from stdin with (format csv);
-1,click
-1,view
-2,click
-\.
-```
-
-Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)
+---
+title: Batch INSERT Statements for Bulk Data
+impact: MEDIUM
+impactDescription: 10-50x faster bulk inserts
+tags: batch, insert, bulk, performance, copy
+---
+
+## Batch INSERT Statements for Bulk Data
+
+Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
+
+**Incorrect (individual inserts):**
+
+```sql
+-- Each insert is a separate transaction and round trip
+insert into events (user_id, action) values (1, 'click');
+insert into events (user_id, action) values (1, 'view');
+insert into events (user_id, action) values (2, 'click');
+-- ... 1000 more individual inserts
+
+-- 1000 inserts = 1000 round trips = slow
+```
+
+**Correct (batch insert):**
+
+```sql
+-- Multiple rows in single statement
+insert into events (user_id, action) values
+  (1, 'click'),
+  (1, 'view'),
+  (2, 'click'),
+  -- ... up to ~1000 rows per batch
+  (999, 'view');
+
+-- One round trip for 1000 rows
+```
+
+For large imports, use COPY:
+
+```sql
+-- COPY is fastest for bulk loading
+copy events (user_id, action, created_at)
+from '/path/to/data.csv'
+with (format csv, header true);
+
+-- Or from stdin in application
+copy events (user_id, action) from stdin with (format csv);
+1,click
+1,view
+2,click
+\.
+```
+
+Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)

package/stack/skills/supabase-postgres-best-practices/references/data-n-plus-one.md

@@ -1,53 +1,53 @@
----
-title: Eliminate N+1 Queries with Batch Loading
-impact: MEDIUM-HIGH
-impactDescription: 10-100x fewer database round trips
-tags: n-plus-one, batch, performance, queries
----
-
-## Eliminate N+1 Queries with Batch Loading
-
-N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
-
-**Incorrect (N+1 queries):**
-
-```sql
--- First query: get all users
-select id from users where active = true;  -- Returns 100 IDs
-
--- Then N queries, one per user
-select * from orders where user_id = 1;
-select * from orders where user_id = 2;
-select * from orders where user_id = 3;
--- ... 97 more queries!
-
--- Total: 101 round trips to database
-```
-
-**Correct (single batch query):**
-
-```sql
--- Collect IDs and query once with ANY
-select * from orders where user_id = any(array[1, 2, 3, ...]);
-
--- Or use JOIN instead of loop
-select u.id, u.name, o.*
-from users u
-left join orders o on o.user_id = u.id
-where u.active = true;
-
--- Total: 1 round trip
-```
-
-Application pattern:
-
-```sql
--- Instead of looping in application code:
--- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
-
--- Pass array parameter:
-select * from orders where user_id = any($1::bigint[]);
--- Application passes: [1, 2, 3, 4, 5, ...]
-```
-
-Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)
+---
+title: Eliminate N+1 Queries with Batch Loading
+impact: MEDIUM-HIGH
+impactDescription: 10-100x fewer database round trips
+tags: n-plus-one, batch, performance, queries
+---
+
+## Eliminate N+1 Queries with Batch Loading
+
+N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
+
+**Incorrect (N+1 queries):**
+
+```sql
+-- First query: get all users
+select id from users where active = true;  -- Returns 100 IDs
+
+-- Then N queries, one per user
+select * from orders where user_id = 1;
+select * from orders where user_id = 2;
+select * from orders where user_id = 3;
+-- ... 97 more queries!
+
+-- Total: 101 round trips to database
+```
+
+**Correct (single batch query):**
+
+```sql
+-- Collect IDs and query once with ANY
+select * from orders where user_id = any(array[1, 2, 3, ...]);
+
+-- Or use JOIN instead of loop
+select u.id, u.name, o.*
+from users u
+left join orders o on o.user_id = u.id
+where u.active = true;
+
+-- Total: 1 round trip
+```
+
+Application pattern:
+
+```sql
+-- Instead of looping in application code:
+-- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
+
+-- Pass array parameter:
+select * from orders where user_id = any($1::bigint[]);
+-- Application passes: [1, 2, 3, 4, 5, ...]
+```
+
+Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)