jorgex-stack 1.0.1 → 1.0.3

package/stack/skills/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 = 'user@example.com' 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 = 'user@example.com' 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 = 'user@example.com' 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 = 'user@example.com' 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/stack/skills/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/stack/skills/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)

package/stack/skills/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md

@@ -1,59 +1,59 @@
----
-title: Index Foreign Key Columns
-impact: HIGH
-impactDescription: 10-100x faster JOINs and CASCADE operations
-tags: foreign-key, indexes, joins, schema
----
-
-## Index Foreign Key Columns
-
-Postgres does not automatically index foreign key columns. Missing indexes cause slow JOINs and CASCADE operations.
-
-**Incorrect (unindexed foreign key):**
-
-```sql
-create table orders (
-  id bigint generated always as identity primary key,
-  customer_id bigint references customers(id) on delete cascade,
-  total numeric(10,2)
-);
-
--- No index on customer_id!
--- JOINs and ON DELETE CASCADE both require full table scan
-select * from orders where customer_id = 123;  -- Seq Scan
-delete from customers where id = 123;          -- Locks table, scans all orders
-```
-
-**Correct (indexed foreign key):**
-
-```sql
-create table orders (
-  id bigint generated always as identity primary key,
-  customer_id bigint references customers(id) on delete cascade,
-  total numeric(10,2)
-);
-
--- Always index the FK column
-create index orders_customer_id_idx on orders (customer_id);
-
--- Now JOINs and cascades are fast
-select * from orders where customer_id = 123;  -- Index Scan
-delete from customers where id = 123;          -- Uses index, fast cascade
-```
-
-Find missing FK indexes:
-
-```sql
-select
-  conrelid::regclass as table_name,
-  a.attname as fk_column
-from pg_constraint c
-join pg_attribute a on a.attrelid = c.conrelid and a.attnum = any(c.conkey)
-where c.contype = 'f'
-  and not exists (
-    select 1 from pg_index i
-    where i.indrelid = c.conrelid and a.attnum = any(i.indkey)
-  );
-```
-
-Reference: [Foreign Keys](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-FK)
+---
+title: Index Foreign Key Columns
+impact: HIGH
+impactDescription: 10-100x faster JOINs and CASCADE operations
+tags: foreign-key, indexes, joins, schema
+---
+
+## Index Foreign Key Columns
+
+Postgres does not automatically index foreign key columns. Missing indexes cause slow JOINs and CASCADE operations.
+
+**Incorrect (unindexed foreign key):**
+
+```sql
+create table orders (
+  id bigint generated always as identity primary key,
+  customer_id bigint references customers(id) on delete cascade,
+  total numeric(10,2)
+);
+
+-- No index on customer_id!
+-- JOINs and ON DELETE CASCADE both require full table scan
+select * from orders where customer_id = 123;  -- Seq Scan
+delete from customers where id = 123;          -- Locks table, scans all orders
+```
+
+**Correct (indexed foreign key):**
+
+```sql
+create table orders (
+  id bigint generated always as identity primary key,
+  customer_id bigint references customers(id) on delete cascade,
+  total numeric(10,2)
+);
+
+-- Always index the FK column
+create index orders_customer_id_idx on orders (customer_id);
+
+-- Now JOINs and cascades are fast
+select * from orders where customer_id = 123;  -- Index Scan
+delete from customers where id = 123;          -- Uses index, fast cascade
+```
+
+Find missing FK indexes:
+
+```sql
+select
+  conrelid::regclass as table_name,
+  a.attname as fk_column
+from pg_constraint c
+join pg_attribute a on a.attrelid = c.conrelid and a.attnum = any(c.conkey)
+where c.contype = 'f'
+  and not exists (
+    select 1 from pg_index i
+    where i.indrelid = c.conrelid and a.attnum = any(i.indkey)
+  );
+```
+
+Reference: [Foreign Keys](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-FK)

package/stack/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md

@@ -1,55 +1,55 @@
----
-title: Use Lowercase Identifiers for Compatibility
-impact: MEDIUM
-impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
-tags: naming, identifiers, case-sensitivity, schema, conventions
----
-
-## Use Lowercase Identifiers for Compatibility
-
-PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
-
-**Incorrect (mixed-case identifiers):**
-
-```sql
--- Quoted identifiers preserve case but require quotes everywhere
-CREATE TABLE "Users" (
-  "userId" bigint PRIMARY KEY,
-  "firstName" text,
-  "lastName" text
-);
-
--- Must always quote or queries fail
-SELECT "firstName" FROM "Users" WHERE "userId" = 1;
-
--- This fails - Users becomes users without quotes
-SELECT firstName FROM Users;
--- ERROR: relation "users" does not exist
-```
-
-**Correct (lowercase snake_case):**
-
-```sql
--- Unquoted lowercase identifiers are portable and tool-friendly
-CREATE TABLE users (
-  user_id bigint PRIMARY KEY,
-  first_name text,
-  last_name text
-);
-
--- Works without quotes, recognized by all tools
-SELECT first_name FROM users WHERE user_id = 1;
-```
-
-Common sources of mixed-case identifiers:
-
-```sql
--- ORMs often generate quoted camelCase - configure them to use snake_case
--- Migrations from other databases may preserve original casing
--- Some GUI tools quote identifiers by default - disable this
-
--- If stuck with mixed-case, create views as a compatibility layer
-CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
-```
-
-Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)
+---
+title: Use Lowercase Identifiers for Compatibility
+impact: MEDIUM
+impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
+tags: naming, identifiers, case-sensitivity, schema, conventions
+---
+
+## Use Lowercase Identifiers for Compatibility
+
+PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
+
+**Incorrect (mixed-case identifiers):**
+
+```sql
+-- Quoted identifiers preserve case but require quotes everywhere
+CREATE TABLE "Users" (
+  "userId" bigint PRIMARY KEY,
+  "firstName" text,
+  "lastName" text
+);
+
+-- Must always quote or queries fail
+SELECT "firstName" FROM "Users" WHERE "userId" = 1;
+
+-- This fails - Users becomes users without quotes
+SELECT firstName FROM Users;
+-- ERROR: relation "users" does not exist
+```
+
+**Correct (lowercase snake_case):**
+
+```sql
+-- Unquoted lowercase identifiers are portable and tool-friendly
+CREATE TABLE users (
+  user_id bigint PRIMARY KEY,
+  first_name text,
+  last_name text
+);
+
+-- Works without quotes, recognized by all tools
+SELECT first_name FROM users WHERE user_id = 1;
+```
+
+Common sources of mixed-case identifiers:
+
+```sql
+-- ORMs often generate quoted camelCase - configure them to use snake_case
+-- Migrations from other databases may preserve original casing
+-- Some GUI tools quote identifiers by default - disable this
+
+-- If stuck with mixed-case, create views as a compatibility layer
+CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
+```
+
+Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)