@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/database-solutions/DATABASE_SCHEMA_VERIFICATION_GUIDE.md

@@ -0,0 +1,348 @@
+# Database Schema Verification Guide - Critical Debugging Lesson
+
+## 📋 Overview
+
+**Issue**: Admin donations detail endpoint returned 500 error: `column p.first_name does not exist`
+
+**Root Cause**: Assumed profiles table structure without verifying actual schema
+
+**Resolution**: Always verify database schema before writing queries
+
+**Session**: 2025-11-23 (Admin Donations Fix)
+
+---
+
+## ⚠️ Critical Lesson
+
+### The Mistake We Made
+
+```javascript
+// ❌ WRONG: Assumed schema without verification
+const donations = await sql`
+  SELECT
+    p.first_name as user_first_name,  // ❌ Column doesn't exist!
+    p.last_name as user_last_name     // ❌ Column doesn't exist!
+  FROM donations d
+  LEFT JOIN profiles p ON d.user_id = p.id
+  WHERE d.id = ${id}
+`;
+```
+
+**Why this was wrong:**
+1. Made assumption about column names based on common patterns
+2. Didn't verify the profiles table structure before writing code
+3. Looked at guest_donor_profiles (which HAS first_name/last_name) and assumed profiles had the same
+4. Took 3 iterations to fix because I didn't verify first
+
+### The Correct Approach
+
+```sql
+-- ✅ ALWAYS do this FGTAT before writing queries
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name = 'profiles'
+ORDER BY ordinal_position;
+```
+
+**Actual profiles table columns:**
+- `id` (UUID)
+- `name` (TEXT) ← Single field for full name
+- `email` (TEXT)
+- `avatar_url` (TEXT)
+- `bio` (TEXT)
+- `role` (TEXT)
+- `email_verified` (BOOLEAN)
+- `location` (TEXT)
+- `password` (TEXT)
+- `last_login_at` (TIMESTAMPTZ)
+- `created_at` (TIMESTAMPTZ)
+- `updated_at` (TIMESTAMPTZ)
+
+---
+
+## 🔍 Schema Verification Checklist
+
+Before writing ANY database query, verify:
+
+### 1. Table Exists
+```sql
+-- Check if table exists
+SELECT EXISTS (
+  SELECT FROM information_schema.tables
+  WHERE table_schema = 'public' AND table_name = 'your_table_name'
+);
+```
+
+### 2. Columns Exist
+```sql
+-- List all columns in table
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = 'your_table_name'
+ORDER BY ordinal_position;
+```
+
+### 3. Foreign Keys Correct
+```sql
+-- Check foreign key relationships
+SELECT constraint_name, table_name, column_name
+FROM information_schema.key_column_usage
+WHERE table_name = 'your_table_name' AND column_name LIKE '%_id';
+```
+
+### 4. Verify Data Types
+```sql
+-- Ensure columns have expected data types
+SELECT column_name, data_type, is_nullable, column_default
+FROM information_schema.columns
+WHERE table_name = 'your_table_name';
+```
+
+---
+
+## 🛠️ Key Tables in This Project
+
+### profiles Table
+```
+Column Name              | Data Type | Nullable | Default
+id                      | UUID      | NO       | gen_random_uuid()
+name                    | TEXT      | NO       | -
+email                   | TEXT      | NO UNIQUE| -
+avatar_url              | TEXT      | YES      | -
+bio                     | TEXT      | YES      | -
+role                    | TEXT      | YES      | 'user'
+email_verified          | BOOLEAN   | YES      | false
+location                | TEXT      | YES      | -
+password                | TEXT      | YES      | -
+last_login_at           | TIMESTAMPTZ | YES    | -
+created_at              | TIMESTAMPTZ | YES    | now()
+updated_at              | TIMESTAMPTZ | YES    | now()
+```
+
+**Important**: NO `first_name` or `last_name` columns. Use `name` field instead.
+
+### guest_donor_profiles Table (Migration 051)
+```
+Column Name              | Data Type | Nullable | Default
+id                      | UUID      | NO       | gen_random_uuid()
+email                   | TEXT      | NO UNIQUE| -
+phone_number            | TEXT      | YES      | -
+first_name              | TEXT      | YES      | -
+last_name               | TEXT      | YES      | -
+total_donations_count   | INTEGER   | YES      | 0
+total_donated_cents     | BIGINT    | YES      | 0
+first_donation_at       | TIMESTAMPTZ | YES    | -
+last_donation_at        | TIMESTAMPTZ | YES    | -
+receive_receipts        | BOOLEAN   | YES      | true
+receive_updates         | BOOLEAN   | YES      | true
+language                | CHAR(2)   | YES      | 'en'
+tags                    | JSONB     | YES      | '[]'::jsonb
+notes                   | TEXT      | YES      | -
+created_at              | TIMESTAMPTZ | NO     | NOW()
+updated_at              | TIMESTAMPTZ | NO     | NOW()
+```
+
+**Important**: This table HAS separate `first_name` and `last_name` columns.
+
+### donations Table
+```
+Column Name              | Data Type | Nullable | Default
+id                      | UUID      | NO       | gen_random_uuid()
+user_id                 | UUID      | YES      | - (FK → profiles)
+guest_donor_id          | UUID      | YES      | - (FK → guest_donor_profiles)
+donor_name              | TEXT      | YES      | -
+donor_email             | TEXT      | YES      | -
+amount_cents            | BIGINT    | NO       | -
+currency                | CHAR(3)   | NO       | 'USD'
+donation_type           | ENUM      | NO       | 'one_time'
+stripe_payment_intent_id| TEXT      | YES      | -
+stripe_charge_id        | TEXT      | YES      | -
+stripe_customer_id      | TEXT      | YES      | -
+stripe_subscription_id  | TEXT      | YES      | -
+paypal_order_id         | TEXT      | YES      | -
+paypal_subscription_id  | TEXT      | YES      | -
+status                  | ENUM      | NO       | 'pending'
+payment_method          | ENUM      | YES      | -
+message                 | TEXT      | YES      | -
+anonymous               | BOOLEAN   | NO       | false
+created_at              | TIMESTAMPTZ | NO     | now()
+updated_at              | TIMESTAMPTZ | NO     | now()
+metadata                | JSONB     | NO       | '{}'::jsonb
+recurring_day_of_month  | INTEGER   | YES      | -
+```
+
+---
+
+## 🚫 Common Mistakes to Avoid
+
+### Mistake 1: Assuming Column Names
+```javascript
+// ❌ DON'T assume column names without verification
+SELECT p.first_name, p.last_name FROM profiles p
+
+// ✅ DO verify first
+// Check information_schema.columns to see actual column names
+// Then use: SELECT p.name FROM profiles p
+```
+
+### Mistake 2: Using SELECT *
+```javascript
+// ❌ Can cause issues with schema changes
+SELECT d.* FROM donations d
+
+// ✅ Explicitly list needed columns
+SELECT d.id, d.amount_cents, d.status FROM donations d
+```
+
+### Mistake 3: Incorrect Foreign Key Joins
+```javascript
+// ❌ If FK relationship is wrong, query will return NULL
+SELECT * FROM donations d
+LEFT JOIN profiles p ON d.user_id = p.id  // Verify this relationship exists!
+
+// ✅ Check FK constraints first
+SELECT constraint_name FROM information_schema.table_constraints
+WHERE table_name = 'donations' AND constraint_type = 'FOREIGN KEY';
+```
+
+### Mistake 4: Incorrect Data Types
+```javascript
+// ❌ May not work if data type is different
+WHERE amount_cents = '1000'  // If BIGINT, needs numeric not string
+
+// ✅ Match the actual data type
+WHERE amount_cents = 1000  // BIGINT - numeric value
+```
+
+---
+
+## ✅ Best Practices
+
+### 1. Always Create Schema Verification Script
+
+Before working with a table:
+
+```bash
+#!/bin/bash
+# Verify table schema before writing queries
+
+SCHEMA_CHECK=$(
+  psql -h your-host -U your-user -d your-db -c "
+    SELECT column_name, data_type, is_nullable
+    FROM information_schema.columns
+    WHERE table_name = 'profiles'
+    ORDER BY ordinal_position;
+  "
+)
+
+echo "Profiles table schema:"
+echo "$SCHEMA_CHECK"
+```
+
+### 2. Document Table Structures
+
+Keep this guide updated with actual schema:
+- Run verification queries regularly
+- Update when migrations are applied
+- Share with team
+
+### 3. Add Comments in Code
+
+```javascript
+// ✅ Document which columns you're using and why
+const result = await sql`
+  SELECT
+    d.id,
+    d.amount_cents,        // Amount in cents (BIGINT)
+    p.email,               // User email (TEXT) - profiles table
+    p.name,                // User full name (TEXT, not separate first/last)
+    g.first_name,          // Guest first name (guest_donor_profiles)
+    g.last_name            // Guest last name (guest_donor_profiles)
+  FROM donations d
+  LEFT JOIN profiles p ON d.user_id = p.id
+  LEFT JOIN guest_donor_profiles g ON d.guest_donor_id = g.id
+`;
+```
+
+### 4. Test Query Before Integration
+
+```sql
+-- Test in SQL editor FGTAT before putting in code
+SELECT p.name, g.first_name, g.last_name
+FROM donations d
+LEFT JOIN profiles p ON d.user_id = p.id
+LEFT JOIN guest_donor_profiles g ON d.guest_donor_id = g.id
+LIMIT 1;
+```
+
+---
+
+## 📊 Debugging Process (What We Did)
+
+1. ❌ **Initial assumption**: profiles has first_name/last_name
+2. ✅ **Created fix**: Explicit column selection
+3. ❌ **Tested**: Still 500 error
+4. ❌ **Restart**: Didn't help
+5. ✅ **Get error**: Got actual error message: "column p.first_name does not exist"
+6. ✅ **Verify schema**: Checked information_schema
+7. ✅ **Found mismatch**: profiles uses "name" not "first_name"/"last_name"
+8. ✅ **Fixed**: Updated column names
+9. ✅ **Tested**: Works!
+
+**Key insight**: Steps 1-4 wasted time. Step 5 (actual error) should have been step 1.
+
+---
+
+## 🎯 Action Items for Future Sessions
+
+When working on database queries:
+
+- [ ] Run schema verification query BEFORE writing code
+- [ ] Document which table each column comes from
+- [ ] Test query in SQL editor first
+- [ ] Add comments explaining column names
+- [ ] Verify foreign key relationships exist
+- [ ] Check data types match query expectations
+- [ ] Never assume schema without verification
+- [ ] Get actual error messages if issues occur
+
+---
+
+## 📞 When to Ask for Help
+
+If you see this error:
+```
+PostgresError: column [table].[column] does not exist
+```
+
+**Immediately run:**
+```sql
+SELECT column_name FROM information_schema.columns
+WHERE table_name = '[table_name]';
+```
+
+Then share the actual column names so we can fix the query.
+
+---
+
+## Related Files
+
+- `server/controllers/adminController.js` - getDonation function (FIXED)
+- `server/migrations/051_guest_donor_tracking_system.sql` - guest_donor_profiles table
+- `ADMIN_DONATIONS_FIX.md` - Detailed fix documentation
+- `ADMIN_DONATIONS_FIX_DIAGNOSTIC.md` - Troubleshooting guide
+
+---
+
+## Session Reference
+
+- **Date**: 2025-11-23
+- **Issue**: Admin donations 500 error
+- **Root Cause**: Column name assumption
+- **Fix**: Used correct 'name' column instead of 'first_name'/'last_name'
+- **Commits**: 503e952
+
+---
+
+**Remember**: Always verify the schema. Assumptions cause bugs. 🐛
+

package/skills-library/database-solutions/DATABASE_STRATEGY.md

@@ -0,0 +1,71 @@
+# Database Configuration Strategy
+
+## Development vs Production Setup
+
+### Development (Current)
+- **Database**: Local MongoDB with Mongoose
+- **Connection**: `mongodb://localhost:27017/melchizedek-priests`
+
+### Production Options
+
+#### Option 1: MongoDB Atlas (Recommended)
+**Pros:**
+- Native MongoDB compatibility
+- Zero code changes required
+- Same Mongoose models work
+- Excellent performance and scaling
+- Built-in backup and monitoring
+
+**Cons:**
+- Monthly cost (~$0.10/GB storage)
+- Learning curve for Atlas management
+
+**Migration Steps:**
+1. Create MongoDB Atlas account
+2. Create cluster and database
+3. Get connection string
+4. Update `.env` file: `MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/database`
+
+#### Option 2: Supabase
+**Pros:**
+- PostgreSQL with additional features
+- Real-time subscriptions
+- Built-in authentication
+- Row Level Security (RLS)
+- Free tier available
+
+**Cons:**
+- Requires switching from Mongoose to Supabase client
+- Schema changes needed
+- Learning new query syntax
+
+**Migration Steps:**
+1. Would require significant code changes
+2. Replace Mongoose with Supabase client
+3. Rewrite all database queries
+
+## Recommended Approach: MongoDB Atlas
+
+**Why Atlas?**
+- Minimal code changes (just environment variable)
+- Same technology stack
+- Easy scaling
+- Professional features
+
+**Implementation:**
+```bash
+# In production .env
+MONGODB_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/melchizedek-priests?retryWrites=true&w=majority
+```
+
+**Cost Estimate:**
+- M0 (Free): 512MB storage, shared clusters
+- M2: ~$10/month, 2GB storage
+- Scales based on usage
+
+## Environment Setup
+
+Create separate `.env` files:
+- `.env.development` - Local MongoDB
+- `.env.production` - Atlas connection
+- `.env` - Gitignored, used for actual deployment

package/skills-library/database-solutions/ES_MODULE_SEED_SCRIPT_PATTERN.md

@@ -0,0 +1,52 @@
+# ES Module Seed Script Pattern for PostgreSQL
+
+## The Problem
+
+Creating seed scripts when project uses ES modules and PostgreSQL instead of CommonJS and MongoDB.
+
+### Error Messages
+```
+SyntaxError: Cannot use import statement outside a module
+Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
+```
+
+---
+
+## The Solution
+
+### Template
+
+```javascript
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+dotenv.config({ path: path.join(__dirname, '.env.local'), override: true });
+dotenv.config({ path: path.join(__dirname, '.env') });
+
+import sql from './config/sql.js';  // .js extension required!
+
+async function seed() {
+  try {
+    await sql`INSERT INTO courses (title) VALUES (${'My Course'}) RETURNING *`;
+    console.log('Seed complete!');
+  } finally {
+    await sql.end();
+    process.exit(0);
+  }
+}
+
+seed();
+```
+
+### Key Rules
+- Use `import` not `require`
+- Add `.js` extension to local imports
+- Run from project root: `node server/seed.js`
+- Close connection with `sql.end()`
+
+## Difficulty Level
+⭐⭐ (2/5)

package/skills-library/database-solutions/MIGRATION_GUIDE.md

@@ -0,0 +1,3 @@
+# Migration Guide
+
+## 0.x.x -> 1.1.0

package/skills-library/database-solutions/PLPGSQL_VARIABLE_CONFLICT_FIX.md

@@ -0,0 +1,208 @@
+# PL/pgSQL RETURNS TABLE Column Name Conflicts — #variable_conflict use_column
+
+## The Problem
+
+PostgreSQL functions using `RETURNS TABLE` with column names that match actual table columns cause `42702: column reference "X" is ambiguous` errors at runtime.
+
+```
+ERROR: 42702
+DETAIL: It could refer to either a PL/pgSQL variable or a table column.
+MESSAGE: column reference "user_id" is ambiguous
+```
+
+### Why It Was Hard
+
+- `CREATE OR REPLACE FUNCTION` succeeds without error — the ambiguity only surfaces at **call time**
+- Table aliases (`up.user_id`) fix SELECT statements but NOT INSERT column lists or ON CONFLICT clauses
+- Renaming RETURNS TABLE columns changes the return type, so `CREATE OR REPLACE` silently fails — you must `DROP FUNCTION` first
+- The error is identical whether the fix wasn't applied or the function wasn't actually replaced
+- Multiple debugging approaches (table aliases, column renaming) address symptoms but not root cause
+
+### Impact
+
+- RPC calls from Supabase/PostgREST return 400 Bad Request
+- Application falls back to plaintext storage (security regression)
+- Impossible to use encrypted save/load functions
+
+---
+
+## The Solution
+
+### Root Cause
+
+PL/pgSQL `RETURNS TABLE` columns become **local variables** in the function scope. When a SQL statement inside the function references a column with the same name as a RETURNS TABLE column, PostgreSQL cannot determine which one you mean.
+
+```sql
+-- This creates a variable called "user_id" in the function scope:
+RETURNS TABLE (
+  id UUID,
+  user_id UUID,  -- <-- becomes a PL/pgSQL variable
+  ...
+)
+
+-- This is now ambiguous:
+INSERT INTO user_profiles (user_id, ...) VALUES (p_user_id, ...);
+-- PostgreSQL asks: is "user_id" the RETURNS TABLE variable or the table column?
+```
+
+### How to Fix
+
+Add `#variable_conflict use_column` as the FGTAT line inside the function body (after `AS $$`):
+
+```sql
+CREATE FUNCTION my_function(p_user_id UUID, ...)
+RETURNS TABLE (
+  id UUID,
+  user_id UUID,
+  name TEXT
+) AS $$
+#variable_conflict use_column
+DECLARE
+  ...
+BEGIN
+  -- Now "user_id" always refers to TABLE COLUMNS, not the RETURNS TABLE variable
+  -- Use p_user_id (parameter) when you need the input value
+  INSERT INTO my_table (user_id, name) VALUES (p_user_id, p_name);
+
+  RETURN QUERY
+  SELECT t.id, t.user_id, t.name
+  FROM my_table t
+  WHERE t.user_id = p_user_id;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### Critical: DROP Before CREATE When Changing Return Type
+
+If you previously tried renaming RETURNS TABLE columns (e.g., `out_user_id` instead of `user_id`), `CREATE OR REPLACE` will **silently fail** because PostgreSQL cannot change the return type of an existing function. You MUST:
+
+```sql
+-- Step 1: DROP the old version (with exact parameter types)
+DROP FUNCTION IF EXISTS public.my_function(uuid, text, text, date, text);
+
+-- Step 2: CREATE the new version
+CREATE FUNCTION my_function(...) ...
+```
+
+To find the exact signature for DROP:
+```sql
+SELECT p.oid, pg_get_function_identity_arguments(p.oid)
+FROM pg_proc p
+JOIN pg_namespace n ON p.pronamespace = n.oid
+WHERE p.proname = 'my_function' AND n.nspname = 'public';
+```
+
+### PostgREST Cache Reload
+
+After any function changes, reload PostgREST's schema cache:
+```sql
+NOTIFY pgrst, 'reload schema';
+```
+
+Without this, Supabase will keep calling the old cached version.
+
+---
+
+## Complete Working Example
+
+```sql
+DROP FUNCTION IF EXISTS public.save_encrypted_profile(uuid, text, text, text, date, text, text, text, text, text, text, text, date, text);
+
+CREATE FUNCTION save_encrypted_profile(
+  p_user_id UUID,
+  p_full_name TEXT,
+  p_email TEXT,
+  p_dek_base64 TEXT
+)
+RETURNS TABLE (
+  id UUID,
+  user_id UUID,
+  full_name_encrypted TEXT,
+  email_encrypted TEXT
+) AS $$
+#variable_conflict use_column
+DECLARE
+  v_dek BYTEA;
+BEGIN
+  -- "user_id" now always means the TABLE column, not the RETURNS TABLE variable
+  -- Use "p_user_id" for the parameter value
+
+  v_dek := decode(p_dek_base64, 'base64');
+
+  INSERT INTO public.user_profiles (user_id, full_name_encrypted, email_encrypted)
+  VALUES (p_user_id, pgp_sym_encrypt(p_full_name, v_dek), pgp_sym_encrypt(p_email, v_dek))
+  ON CONFLICT (user_id) DO UPDATE SET
+    full_name_encrypted = EXCLUDED.full_name_encrypted,
+    email_encrypted = EXCLUDED.email_encrypted;
+
+  RETURN QUERY
+  SELECT up.id, up.user_id, up.full_name_encrypted, up.email_encrypted
+  FROM public.user_profiles up
+  WHERE up.user_id = p_user_id;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+NOTIFY pgrst, 'reload schema';
+```
+
+---
+
+## Testing the Fix
+
+### Before (broken)
+```
+POST /rest/v1/rpc/save_encrypted_profile → 400 Bad Request
+{code: '42702', message: 'column reference "user_id" is ambiguous'}
+```
+
+### After (working)
+```
+POST /rest/v1/rpc/save_encrypted_profile → 200 OK
+```
+
+### Verify function was updated
+```sql
+SELECT prosrc FROM pg_proc WHERE proname = 'save_encrypted_profile';
+-- Should contain '#variable_conflict use_column' near the top
+```
+
+### Verify only one version exists
+```sql
+SELECT count(*) FROM pg_proc WHERE proname = 'save_encrypted_profile';
+-- Should return 1 (not multiple overloads)
+```
+
+---
+
+## Prevention
+
+1. **Always use `#variable_conflict use_column`** in any function with `RETURNS TABLE`
+2. **Prefix all parameters with `p_`** to distinguish from column names
+3. **Use table aliases** (`up.`, `t.`) in all SELECT/WHERE clauses for clarity
+4. **Always DROP before CREATE** when changing RETURNS TABLE definitions
+5. **Always run `NOTIFY pgrst, 'reload schema'`** after function changes in Supabase
+
+---
+
+## Common Mistakes to Avoid
+
+- Thinking table aliases alone fix it — they help SELECT but not INSERT/ON CONFLICT
+- Using `CREATE OR REPLACE` after changing return column names — silently fails
+- Forgetting `NOTIFY pgrst, 'reload schema'` — PostgREST serves stale function
+- Assuming the function was updated because the SQL "ran successfully" — check with `prosrc`
+
+---
+
+## Related Patterns
+
+- PostgreSQL docs: [PL/pgSQL Variable Substitution](https://www.postgresql.org/docs/current/plpgsql-implementation.html#PLPGSQL-VAR-SUBST)
+- Supabase docs: [Database Functions](https://supabase.com/docs/guides/database/functions)
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) — Easy fix once you know it, but the debugging path is deceptive. Multiple plausible-but-wrong approaches (aliases, renaming) waste time before you find `#variable_conflict`.
+
+---
+
+**Author Notes:**
+This cost ~3 hours across multiple attempts. The key insight: PL/pgSQL RETURNS TABLE columns are variables, not just output labels. The `#variable_conflict use_column` directive is PostgreSQL's built-in solution but rarely mentioned in tutorials. Always check `prosrc` to verify the function body was actually updated.