@oriro/orirocli 0.1.9 → 0.1.11

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

@@ -1,40 +1,40 @@
----
-title: Use Covering Indexes to Avoid Table Lookups
-impact: MEDIUM-HIGH
-impactDescription: 2-5x faster queries by eliminating heap fetches
-tags: indexes, covering-index, include, index-only-scan
----
-
-## Use Covering Indexes to Avoid Table Lookups
-
-Covering indexes include all columns needed by a query, enabling index-only scans that skip the table entirely.
-
-**Incorrect (index scan + heap fetch):**
-
-```sql
-create index users_email_idx on users (email);
-
--- Must fetch name and created_at from table heap
-select email, name, created_at from users where email = '<email>';
-```
-
-**Correct (index-only scan with INCLUDE):**
-
-```sql
--- Include non-searchable columns in the index
-create index users_email_idx on users (email) include (name, created_at);
-
--- All columns served from index, no table access needed
-select email, name, created_at from users where email = '<email>';
-```
-
-Use INCLUDE for columns you SELECT but don't filter on:
-
-```sql
--- Searching by status, but also need customer_id and total
-create index orders_status_idx on orders (status) include (customer_id, total);
-
-select status, customer_id, total from orders where status = 'shipped';
-```
-
-Reference: [Index-Only Scans](https://www.postgresql.org/docs/current/indexes-index-only-scans.html)
+---
+title: Use Covering Indexes to Avoid Table Lookups
+impact: MEDIUM-HIGH
+impactDescription: 2-5x faster queries by eliminating heap fetches
+tags: indexes, covering-index, include, index-only-scan
+---
+
+## Use Covering Indexes to Avoid Table Lookups
+
+Covering indexes include all columns needed by a query, enabling index-only scans that skip the table entirely.
+
+**Incorrect (index scan + heap fetch):**
+
+```sql
+create index users_email_idx on users (email);
+
+-- Must fetch name and created_at from table heap
+select email, name, created_at from users where email = '<email>';
+```
+
+**Correct (index-only scan with INCLUDE):**
+
+```sql
+-- Include non-searchable columns in the index
+create index users_email_idx on users (email) include (name, created_at);
+
+-- All columns served from index, no table access needed
+select email, name, created_at from users where email = '<email>';
+```
+
+Use INCLUDE for columns you SELECT but don't filter on:
+
+```sql
+-- Searching by status, but also need customer_id and total
+create index orders_status_idx on orders (status) include (customer_id, total);
+
+select status, customer_id, total from orders where status = 'shipped';
+```
+
+Reference: [Index-Only Scans](https://www.postgresql.org/docs/current/indexes-index-only-scans.html)

package/skills/craft/supabase-postgres-best-practices/references/query-index-types.md

@@ -1,48 +1,48 @@
----
-title: Choose the Right Index Type for Your Data
-impact: HIGH
-impactDescription: 10-100x improvement with correct index type
-tags: indexes, btree, gin, gist, brin, hash, index-types
----
-
-## Choose the Right Index Type for Your Data
-
-Different index types excel at different query patterns. The default B-tree isn't always optimal.
-
-**Incorrect (B-tree for JSONB containment):**
-
-```sql
--- B-tree cannot optimize containment operators
-create index products_attrs_idx on products (attributes);
-select * from products where attributes @> '{"color": "red"}';
--- Full table scan - B-tree doesn't support @> operator
-```
-
-**Correct (GIN for JSONB):**
-
-```sql
--- GIN supports @>, ?, ?&, ?| operators
-create index products_attrs_idx on products using gin (attributes);
-select * from products where attributes @> '{"color": "red"}';
-```
-
-Index type guide:
-
-```sql
--- B-tree (default): =, <, >, BETWEEN, IN, IS NULL
-create index users_created_idx on users (created_at);
-
--- GIN: arrays, JSONB, full-text search
-create index posts_tags_idx on posts using gin (tags);
-
--- GiST: geometric data, range types, nearest-neighbor (KNN) queries
-create index locations_idx on places using gist (location);
-
--- BRIN: large time-series tables (10-100x smaller)
-create index events_time_idx on events using brin (created_at);
-
--- Hash: equality-only (slightly faster than B-tree for =)
-create index sessions_token_idx on sessions using hash (token);
-```
-
-Reference: [Index Types](https://www.postgresql.org/docs/current/indexes-types.html)
+---
+title: Choose the Right Index Type for Your Data
+impact: HIGH
+impactDescription: 10-100x improvement with correct index type
+tags: indexes, btree, gin, gist, brin, hash, index-types
+---
+
+## Choose the Right Index Type for Your Data
+
+Different index types excel at different query patterns. The default B-tree isn't always optimal.
+
+**Incorrect (B-tree for JSONB containment):**
+
+```sql
+-- B-tree cannot optimize containment operators
+create index products_attrs_idx on products (attributes);
+select * from products where attributes @> '{"color": "red"}';
+-- Full table scan - B-tree doesn't support @> operator
+```
+
+**Correct (GIN for JSONB):**
+
+```sql
+-- GIN supports @>, ?, ?&, ?| operators
+create index products_attrs_idx on products using gin (attributes);
+select * from products where attributes @> '{"color": "red"}';
+```
+
+Index type guide:
+
+```sql
+-- B-tree (default): =, <, >, BETWEEN, IN, IS NULL
+create index users_created_idx on users (created_at);
+
+-- GIN: arrays, JSONB, full-text search
+create index posts_tags_idx on posts using gin (tags);
+
+-- GiST: geometric data, range types, nearest-neighbor (KNN) queries
+create index locations_idx on places using gist (location);
+
+-- BRIN: large time-series tables (10-100x smaller)
+create index events_time_idx on events using brin (created_at);
+
+-- Hash: equality-only (slightly faster than B-tree for =)
+create index sessions_token_idx on sessions using hash (token);
+```
+
+Reference: [Index Types](https://www.postgresql.org/docs/current/indexes-types.html)

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

@@ -1,43 +1,43 @@
----
-title: Add Indexes on WHERE and JOIN Columns
-impact: CRITICAL
-impactDescription: 100-1000x faster queries on large tables
-tags: indexes, performance, sequential-scan, query-optimization
----
-
-## Add Indexes on WHERE and JOIN Columns
-
-Queries filtering or joining on unindexed columns cause full table scans, which become exponentially slower as tables grow.
-
-**Incorrect (sequential scan on large table):**
-
-```sql
--- No index on customer_id causes full table scan
-select * from orders where customer_id = 123;
-
--- EXPLAIN shows: Seq Scan on orders (cost=0.00..25000.00 rows=100 width=85)
-```
-
-**Correct (index scan):**
-
-```sql
--- Create index on frequently filtered column
-create index orders_customer_id_idx on orders (customer_id);
-
-select * from orders where customer_id = 123;
-
--- EXPLAIN shows: Index Scan using orders_customer_id_idx (cost=0.42..8.44 rows=100 width=85)
-```
-
-For JOIN columns, always index the foreign key side:
-
-```sql
--- Index the referencing column
-create index orders_customer_id_idx on orders (customer_id);
-
-select c.name, o.total
-from customers c
-join orders o on o.customer_id = c.id;
-```
-
-Reference: [Query Optimization](https://supabase.com/docs/guides/database/query-optimization)
+---
+title: Add Indexes on WHERE and JOIN Columns
+impact: CRITICAL
+impactDescription: 100-1000x faster queries on large tables
+tags: indexes, performance, sequential-scan, query-optimization
+---
+
+## Add Indexes on WHERE and JOIN Columns
+
+Queries filtering or joining on unindexed columns cause full table scans, which become exponentially slower as tables grow.
+
+**Incorrect (sequential scan on large table):**
+
+```sql
+-- No index on customer_id causes full table scan
+select * from orders where customer_id = 123;
+
+-- EXPLAIN shows: Seq Scan on orders (cost=0.00..25000.00 rows=100 width=85)
+```
+
+**Correct (index scan):**
+
+```sql
+-- Create index on frequently filtered column
+create index orders_customer_id_idx on orders (customer_id);
+
+select * from orders where customer_id = 123;
+
+-- EXPLAIN shows: Index Scan using orders_customer_id_idx (cost=0.42..8.44 rows=100 width=85)
+```
+
+For JOIN columns, always index the foreign key side:
+
+```sql
+-- Index the referencing column
+create index orders_customer_id_idx on orders (customer_id);
+
+select c.name, o.total
+from customers c
+join orders o on o.customer_id = c.id;
+```
+
+Reference: [Query Optimization](https://supabase.com/docs/guides/database/query-optimization)

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

@@ -1,45 +1,45 @@
----
-title: Use Partial Indexes for Filtered Queries
-impact: HIGH
-impactDescription: 5-20x smaller indexes, faster writes and queries
-tags: indexes, partial-index, query-optimization, storage
----
-
-## Use Partial Indexes for Filtered Queries
-
-Partial indexes only include rows matching a WHERE condition, making them smaller and faster when queries consistently filter on the same condition.
-
-**Incorrect (full index includes irrelevant rows):**
-
-```sql
--- Index includes all rows, even soft-deleted ones
-create index users_email_idx on users (email);
-
--- Query always filters active users
-select * from users where email = '<email>' and deleted_at is null;
-```
-
-**Correct (partial index matches query filter):**
-
-```sql
--- Index only includes active users
-create index users_active_email_idx on users (email)
-where deleted_at is null;
-
--- Query uses the smaller, faster index
-select * from users where email = '<email>' and deleted_at is null;
-```
-
-Common use cases for partial indexes:
-
-```sql
--- Only pending orders (status rarely changes once completed)
-create index orders_pending_idx on orders (created_at)
-where status = 'pending';
-
--- Only non-null values
-create index products_sku_idx on products (sku)
-where sku is not null;
-```
-
-Reference: [Partial Indexes](https://www.postgresql.org/docs/current/indexes-partial.html)
+---
+title: Use Partial Indexes for Filtered Queries
+impact: HIGH
+impactDescription: 5-20x smaller indexes, faster writes and queries
+tags: indexes, partial-index, query-optimization, storage
+---
+
+## Use Partial Indexes for Filtered Queries
+
+Partial indexes only include rows matching a WHERE condition, making them smaller and faster when queries consistently filter on the same condition.
+
+**Incorrect (full index includes irrelevant rows):**
+
+```sql
+-- Index includes all rows, even soft-deleted ones
+create index users_email_idx on users (email);
+
+-- Query always filters active users
+select * from users where email = '<email>' and deleted_at is null;
+```
+
+**Correct (partial index matches query filter):**
+
+```sql
+-- Index only includes active users
+create index users_active_email_idx on users (email)
+where deleted_at is null;
+
+-- Query uses the smaller, faster index
+select * from users where email = '<email>' and deleted_at is null;
+```
+
+Common use cases for partial indexes:
+
+```sql
+-- Only pending orders (status rarely changes once completed)
+create index orders_pending_idx on orders (created_at)
+where status = 'pending';
+
+-- Only non-null values
+create index products_sku_idx on products (sku)
+where sku is not null;
+```
+
+Reference: [Partial Indexes](https://www.postgresql.org/docs/current/indexes-partial.html)

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

@@ -1,80 +1,80 @@
----
-title: Add Constraints Safely in Migrations
-impact: HIGH
-impactDescription: Prevents migration failures and enables idempotent schema changes
-tags: constraints, migrations, schema, alter-table
----
-
-## Add Constraints Safely in Migrations
-
-PostgreSQL does not support `ADD CONSTRAINT IF NOT EXISTS`. Migrations using this syntax will fail.
-
-**Incorrect (causes syntax error):**
-
-```sql
--- ERROR: syntax error at or near "not" (SQLSTATE 42601)
-alter table public.profiles
-add constraint if not exists profiles_birthchart_id_unique unique (birthchart_id);
-```
-
-**Correct (idempotent constraint creation):**
-
-```sql
--- Use DO block to check before adding
-do $$
-begin
-  if not exists (
-    select 1 from pg_constraint
-    where conname = 'profiles_birthchart_id_unique'
-    and conrelid = 'public.profiles'::regclass
-  ) then
-    alter table public.profiles
-    add constraint profiles_birthchart_id_unique unique (birthchart_id);
-  end if;
-end $$;
-```
-
-For all constraint types:
-
-```sql
--- Check constraints
-do $$
-begin
-  if not exists (
-    select 1 from pg_constraint
-    where conname = 'check_age_positive'
-  ) then
-    alter table users add constraint check_age_positive check (age > 0);
-  end if;
-end $$;
-
--- Foreign keys
-do $$
-begin
-  if not exists (
-    select 1 from pg_constraint
-    where conname = 'profiles_birthchart_id_fkey'
-  ) then
-    alter table profiles
-    add constraint profiles_birthchart_id_fkey
-    foreign key (birthchart_id) references birthcharts(id);
-  end if;
-end $$;
-```
-
-Check if constraint exists:
-
-```sql
--- Query to check constraint existence
-select conname, contype, pg_get_constraintdef(oid)
-from pg_constraint
-where conrelid = 'public.profiles'::regclass;
-
--- contype values:
--- 'p' = PRIMARY KEY
--- 'f' = FOREIGN KEY
--- 'u' = UNIQUE
--- 'c' = CHECK
-```
-
-Reference: [Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html)
+---
+title: Add Constraints Safely in Migrations
+impact: HIGH
+impactDescription: Prevents migration failures and enables idempotent schema changes
+tags: constraints, migrations, schema, alter-table
+---
+
+## Add Constraints Safely in Migrations
+
+PostgreSQL does not support `ADD CONSTRAINT IF NOT EXISTS`. Migrations using this syntax will fail.
+
+**Incorrect (causes syntax error):**
+
+```sql
+-- ERROR: syntax error at or near "not" (SQLSTATE 42601)
+alter table public.profiles
+add constraint if not exists profiles_birthchart_id_unique unique (birthchart_id);
+```
+
+**Correct (idempotent constraint creation):**
+
+```sql
+-- Use DO block to check before adding
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+    where conname = 'profiles_birthchart_id_unique'
+    and conrelid = 'public.profiles'::regclass
+  ) then
+    alter table public.profiles
+    add constraint profiles_birthchart_id_unique unique (birthchart_id);
+  end if;
+end $$;
+```
+
+For all constraint types:
+
+```sql
+-- Check constraints
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+    where conname = 'check_age_positive'
+  ) then
+    alter table users add constraint check_age_positive check (age > 0);
+  end if;
+end $$;
+
+-- Foreign keys
+do $$
+begin
+  if not exists (
+    select 1 from pg_constraint
+    where conname = 'profiles_birthchart_id_fkey'
+  ) then
+    alter table profiles
+    add constraint profiles_birthchart_id_fkey
+    foreign key (birthchart_id) references birthcharts(id);
+  end if;
+end $$;
+```
+
+Check if constraint exists:
+
+```sql
+-- Query to check constraint existence
+select conname, contype, pg_get_constraintdef(oid)
+from pg_constraint
+where conrelid = 'public.profiles'::regclass;
+
+-- contype values:
+-- 'p' = PRIMARY KEY
+-- 'f' = FOREIGN KEY
+-- 'u' = UNIQUE
+-- 'c' = CHECK
+```
+
+Reference: [Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html)

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

@@ -1,46 +1,46 @@
----
-title: Choose Appropriate Data Types
-impact: HIGH
-impactDescription: 50% storage reduction, faster comparisons
-tags: data-types, schema, storage, performance
----
-
-## Choose Appropriate Data Types
-
-Using the right data types reduces storage, improves query performance, and prevents bugs.
-
-**Incorrect (wrong data types):**
-
-```sql
-create table users (
-  id int,                    -- Will overflow at 2.1 billion
-  email varchar(255),        -- Unnecessary length limit
-  created_at timestamp,      -- Missing timezone info
-  is_active varchar(5),      -- String for boolean
-  price varchar(20)          -- String for numeric
-);
-```
-
-**Correct (appropriate data types):**
-
-```sql
-create table users (
-  id bigint generated always as identity primary key,  -- 9 quintillion max
-  email text,                     -- No artificial limit, same performance as varchar
-  created_at timestamptz,         -- Always store timezone-aware timestamps
-  is_active boolean default true, -- 1 byte vs variable string length
-  price numeric(10,2)             -- Exact decimal arithmetic
-);
-```
-
-Key guidelines:
-
-```sql
--- IDs: use bigint, not int (future-proofing)
--- Strings: use text, not varchar(n) unless constraint needed
--- Time: use timestamptz, not timestamp
--- Money: use numeric, not float (precision matters)
--- Enums: use text with check constraint or create enum type
-```
-
-Reference: [Data Types](https://www.postgresql.org/docs/current/datatype.html)
+---
+title: Choose Appropriate Data Types
+impact: HIGH
+impactDescription: 50% storage reduction, faster comparisons
+tags: data-types, schema, storage, performance
+---
+
+## Choose Appropriate Data Types
+
+Using the right data types reduces storage, improves query performance, and prevents bugs.
+
+**Incorrect (wrong data types):**
+
+```sql
+create table users (
+  id int,                    -- Will overflow at 2.1 billion
+  email varchar(255),        -- Unnecessary length limit
+  created_at timestamp,      -- Missing timezone info
+  is_active varchar(5),      -- String for boolean
+  price varchar(20)          -- String for numeric
+);
+```
+
+**Correct (appropriate data types):**
+
+```sql
+create table users (
+  id bigint generated always as identity primary key,  -- 9 quintillion max
+  email text,                     -- No artificial limit, same performance as varchar
+  created_at timestamptz,         -- Always store timezone-aware timestamps
+  is_active boolean default true, -- 1 byte vs variable string length
+  price numeric(10,2)             -- Exact decimal arithmetic
+);
+```
+
+Key guidelines:
+
+```sql
+-- IDs: use bigint, not int (future-proofing)
+-- Strings: use text, not varchar(n) unless constraint needed
+-- Time: use timestamptz, not timestamp
+-- Money: use numeric, not float (precision matters)
+-- Enums: use text with check constraint or create enum type
+```
+
+Reference: [Data Types](https://www.postgresql.org/docs/current/datatype.html)