@oriro/orirocli 0.1.9 → 0.1.11

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

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

@@ -1,50 +1,50 @@
----
-title: Use Cursor-Based Pagination Instead of OFFSET
-impact: MEDIUM-HIGH
-impactDescription: Consistent O(1) performance regardless of page depth
-tags: pagination, cursor, keyset, offset, performance
----
-
-## Use Cursor-Based Pagination Instead of OFFSET
-
-OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
-
-**Incorrect (OFFSET pagination):**
-
-```sql
--- Page 1: scans 20 rows
-select * from products order by id limit 20 offset 0;
-
--- Page 100: scans 2000 rows to skip 1980
-select * from products order by id limit 20 offset 1980;
-
--- Page 10000: scans 200,000 rows!
-select * from products order by id limit 20 offset 199980;
-```
-
-**Correct (cursor/keyset pagination):**
-
-```sql
--- Page 1: get first 20
-select * from products order by id limit 20;
--- Application stores last_id = 20
-
--- Page 2: start after last ID
-select * from products where id > 20 order by id limit 20;
--- Uses index, always fast regardless of page depth
-
--- Page 10000: same speed as page 1
-select * from products where id > 199980 order by id limit 20;
-```
-
-For multi-column sorting:
-
-```sql
--- Cursor must include all sort columns
-select * from products
-where (created_at, id) > ('2024-01-15 10:00:00', 12345)
-order by created_at, id
-limit 20;
-```
-
-Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)
+---
+title: Use Cursor-Based Pagination Instead of OFFSET
+impact: MEDIUM-HIGH
+impactDescription: Consistent O(1) performance regardless of page depth
+tags: pagination, cursor, keyset, offset, performance
+---
+
+## Use Cursor-Based Pagination Instead of OFFSET
+
+OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
+
+**Incorrect (OFFSET pagination):**
+
+```sql
+-- Page 1: scans 20 rows
+select * from products order by id limit 20 offset 0;
+
+-- Page 100: scans 2000 rows to skip 1980
+select * from products order by id limit 20 offset 1980;
+
+-- Page 10000: scans 200,000 rows!
+select * from products order by id limit 20 offset 199980;
+```
+
+**Correct (cursor/keyset pagination):**
+
+```sql
+-- Page 1: get first 20
+select * from products order by id limit 20;
+-- Application stores last_id = 20
+
+-- Page 2: start after last ID
+select * from products where id > 20 order by id limit 20;
+-- Uses index, always fast regardless of page depth
+
+-- Page 10000: same speed as page 1
+select * from products where id > 199980 order by id limit 20;
+```
+
+For multi-column sorting:
+
+```sql
+-- Cursor must include all sort columns
+select * from products
+where (created_at, id) > ('2024-01-15 10:00:00', 12345)
+order by created_at, id
+limit 20;
+```
+
+Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)

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

@@ -1,50 +1,50 @@
----
-title: Use UPSERT for Insert-or-Update Operations
-impact: MEDIUM
-impactDescription: Atomic operation, eliminates race conditions
-tags: upsert, on-conflict, insert, update
----
-
-## Use UPSERT for Insert-or-Update Operations
-
-Using separate SELECT-then-INSERT/UPDATE creates race conditions. Use INSERT ... ON CONFLICT for atomic upserts.
-
-**Incorrect (check-then-insert race condition):**
-
-```sql
--- Race condition: two requests check simultaneously
-select * from settings where user_id = 123 and key = 'theme';
--- Both find nothing
-
--- Both try to insert
-insert into settings (user_id, key, value) values (123, 'theme', 'dark');
--- One succeeds, one fails with duplicate key error!
-```
-
-**Correct (atomic UPSERT):**
-
-```sql
--- Single atomic operation
-insert into settings (user_id, key, value)
-values (123, 'theme', 'dark')
-on conflict (user_id, key)
-do update set value = excluded.value, updated_at = now();
-
--- Returns the inserted/updated row
-insert into settings (user_id, key, value)
-values (123, 'theme', 'dark')
-on conflict (user_id, key)
-do update set value = excluded.value
-returning *;
-```
-
-Insert-or-ignore pattern:
-
-```sql
--- Insert only if not exists (no update)
-insert into page_views (page_id, user_id)
-values (1, 123)
-on conflict (page_id, user_id) do nothing;
-```
-
-Reference: [INSERT ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT)
+---
+title: Use UPSERT for Insert-or-Update Operations
+impact: MEDIUM
+impactDescription: Atomic operation, eliminates race conditions
+tags: upsert, on-conflict, insert, update
+---
+
+## Use UPSERT for Insert-or-Update Operations
+
+Using separate SELECT-then-INSERT/UPDATE creates race conditions. Use INSERT ... ON CONFLICT for atomic upserts.
+
+**Incorrect (check-then-insert race condition):**
+
+```sql
+-- Race condition: two requests check simultaneously
+select * from settings where user_id = 123 and key = 'theme';
+-- Both find nothing
+
+-- Both try to insert
+insert into settings (user_id, key, value) values (123, 'theme', 'dark');
+-- One succeeds, one fails with duplicate key error!
+```
+
+**Correct (atomic UPSERT):**
+
+```sql
+-- Single atomic operation
+insert into settings (user_id, key, value)
+values (123, 'theme', 'dark')
+on conflict (user_id, key)
+do update set value = excluded.value, updated_at = now();
+
+-- Returns the inserted/updated row
+insert into settings (user_id, key, value)
+values (123, 'theme', 'dark')
+on conflict (user_id, key)
+do update set value = excluded.value
+returning *;
+```
+
+Insert-or-ignore pattern:
+
+```sql
+-- Insert only if not exists (no update)
+insert into page_views (page_id, user_id)
+values (1, 123)
+on conflict (page_id, user_id) do nothing;
+```
+
+Reference: [INSERT ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT)

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

@@ -1,56 +1,56 @@
----
-title: Use Advisory Locks for Application-Level Locking
-impact: MEDIUM
-impactDescription: Efficient coordination without row-level lock overhead
-tags: advisory-locks, coordination, application-locks
----
-
-## Use Advisory Locks for Application-Level Locking
-
-Advisory locks provide application-level coordination without requiring database rows to lock.
-
-**Incorrect (creating rows just for locking):**
-
-```sql
--- Creating dummy rows to lock on
-create table resource_locks (
-  resource_name text primary key
-);
-
-insert into resource_locks values ('report_generator');
-
--- Lock by selecting the row
-select * from resource_locks where resource_name = 'report_generator' for update;
-```
-
-**Correct (advisory locks):**
-
-```sql
--- Session-level advisory lock (released on disconnect or unlock)
-select pg_advisory_lock(hashtext('report_generator'));
--- ... do exclusive work ...
-select pg_advisory_unlock(hashtext('report_generator'));
-
--- Transaction-level lock (released on commit/rollback)
-begin;
-select pg_advisory_xact_lock(hashtext('daily_report'));
--- ... do work ...
-commit;  -- Lock automatically released
-```
-
-Try-lock for non-blocking operations:
-
-```sql
--- Returns immediately with true/false instead of waiting
-select pg_try_advisory_lock(hashtext('resource_name'));
-
--- Use in application
-if (acquired) {
-  -- Do work
-  select pg_advisory_unlock(hashtext('resource_name'));
-} else {
-  -- Skip or retry later
-}
-```
-
-Reference: [Advisory Locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
+---
+title: Use Advisory Locks for Application-Level Locking
+impact: MEDIUM
+impactDescription: Efficient coordination without row-level lock overhead
+tags: advisory-locks, coordination, application-locks
+---
+
+## Use Advisory Locks for Application-Level Locking
+
+Advisory locks provide application-level coordination without requiring database rows to lock.
+
+**Incorrect (creating rows just for locking):**
+
+```sql
+-- Creating dummy rows to lock on
+create table resource_locks (
+  resource_name text primary key
+);
+
+insert into resource_locks values ('report_generator');
+
+-- Lock by selecting the row
+select * from resource_locks where resource_name = 'report_generator' for update;
+```
+
+**Correct (advisory locks):**
+
+```sql
+-- Session-level advisory lock (released on disconnect or unlock)
+select pg_advisory_lock(hashtext('report_generator'));
+-- ... do exclusive work ...
+select pg_advisory_unlock(hashtext('report_generator'));
+
+-- Transaction-level lock (released on commit/rollback)
+begin;
+select pg_advisory_xact_lock(hashtext('daily_report'));
+-- ... do work ...
+commit;  -- Lock automatically released
+```
+
+Try-lock for non-blocking operations:
+
+```sql
+-- Returns immediately with true/false instead of waiting
+select pg_try_advisory_lock(hashtext('resource_name'));
+
+-- Use in application
+if (acquired) {
+  -- Do work
+  select pg_advisory_unlock(hashtext('resource_name'));
+} else {
+  -- Skip or retry later
+}
+```
+
+Reference: [Advisory Locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)

package/skills/craft/supabase-postgres-best-practices/references/lock-deadlock-prevention.md

@@ -1,68 +1,68 @@
----
-title: Prevent Deadlocks with Consistent Lock Ordering
-impact: MEDIUM-HIGH
-impactDescription: Eliminate deadlock errors, improve reliability
-tags: deadlocks, locking, transactions, ordering
----
-
-## Prevent Deadlocks with Consistent Lock Ordering
-
-Deadlocks occur when transactions lock resources in different orders. Always
-acquire locks in a consistent order.
-
-**Incorrect (inconsistent lock ordering):**
-
-```sql
--- Transaction A                    -- Transaction B
-begin;                              begin;
-update accounts                     update accounts
-set balance = balance - 100         set balance = balance - 50
-where id = 1;                       where id = 2;  -- B locks row 2
-
-update accounts                     update accounts
-set balance = balance + 100         set balance = balance + 50
-where id = 2;  -- A waits for B     where id = 1;  -- B waits for A
-
--- DEADLOCK! Both waiting for each other
-```
-
-**Correct (lock rows in consistent order first):**
-
-```sql
--- Explicitly acquire locks in ID order before updating
-begin;
-select * from accounts where id in (1, 2) order by id for update;
-
--- Now perform updates in any order - locks already held
-update accounts set balance = balance - 100 where id = 1;
-update accounts set balance = balance + 100 where id = 2;
-commit;
-```
-
-Alternative: use a single statement to update atomically:
-
-```sql
--- Single statement acquires all locks atomically
-begin;
-update accounts
-set balance = balance + case id
-  when 1 then -100
-  when 2 then 100
-end
-where id in (1, 2);
-commit;
-```
-
-Detect deadlocks in logs:
-
-```sql
--- Check for recent deadlocks
-select * from pg_stat_database where deadlocks > 0;
-
--- Enable deadlock logging
-set log_lock_waits = on;
-set deadlock_timeout = '1s';
-```
-
-Reference:
-[Deadlocks](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-DEADLOCKS)
+---
+title: Prevent Deadlocks with Consistent Lock Ordering
+impact: MEDIUM-HIGH
+impactDescription: Eliminate deadlock errors, improve reliability
+tags: deadlocks, locking, transactions, ordering
+---
+
+## Prevent Deadlocks with Consistent Lock Ordering
+
+Deadlocks occur when transactions lock resources in different orders. Always
+acquire locks in a consistent order.
+
+**Incorrect (inconsistent lock ordering):**
+
+```sql
+-- Transaction A                    -- Transaction B
+begin;                              begin;
+update accounts                     update accounts
+set balance = balance - 100         set balance = balance - 50
+where id = 1;                       where id = 2;  -- B locks row 2
+
+update accounts                     update accounts
+set balance = balance + 100         set balance = balance + 50
+where id = 2;  -- A waits for B     where id = 1;  -- B waits for A
+
+-- DEADLOCK! Both waiting for each other
+```
+
+**Correct (lock rows in consistent order first):**
+
+```sql
+-- Explicitly acquire locks in ID order before updating
+begin;
+select * from accounts where id in (1, 2) order by id for update;
+
+-- Now perform updates in any order - locks already held
+update accounts set balance = balance - 100 where id = 1;
+update accounts set balance = balance + 100 where id = 2;
+commit;
+```
+
+Alternative: use a single statement to update atomically:
+
+```sql
+-- Single statement acquires all locks atomically
+begin;
+update accounts
+set balance = balance + case id
+  when 1 then -100
+  when 2 then 100
+end
+where id in (1, 2);
+commit;
+```
+
+Detect deadlocks in logs:
+
+```sql
+-- Check for recent deadlocks
+select * from pg_stat_database where deadlocks > 0;
+
+-- Enable deadlock logging
+set log_lock_waits = on;
+set deadlock_timeout = '1s';
+```
+
+Reference:
+[Deadlocks](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-DEADLOCKS)