Supabase Postgres Best Practices

8 steps · start to finish.

1. 1
   Step 1

   Environment Setup

   ▶

   # Verify required tools
   command -v psql >/dev/null 2>&1 && echo "psql present" || echo "psql not found (analysis will use provided SQL files)"
   
   # Create output directories
   mkdir -p /app/results
   
   # Verify input parameters
   if [ -z "$TARGET_SCHEMA" ] && [ -z "$SQL_INPUT" ]; then
     echo "WARNING: No target schema specified. Using interactive mode."
   fi
   
   echo "=== Environment ready ==="
   echo "Results dir: /app/results"
   echo "Postgres Best Practices version: 1.1.1 (Supabase, January 2026)"
   

2. 2
   Step 2

   Load and Index the Best Practices Rules

   ▶

   Load the 8-category rule framework from the Supabase Postgres Best Practices skill.

3. 3
   Step 3

   Analyze Query Performance (CRITICAL — Priority 1)

   ▶

   Apply `query-*` rules to identify missing indexes, suboptimal index usage, and query patterns.

4. 4
   Step 4

   Analyze Connection Management (CRITICAL — Priority 2)

   ▶

   Apply `conn-*` rules to review pooling configuration, connection limits, and prepared statement handling.

5. 5
   Step 5

   Analyze Security & RLS (CRITICAL — Priority 3)

   ▶

   Apply `security-*` rules to verify Row-Level Security policies are correctly configured.

6. 6
   Step 6

   Analyze Lower-Priority Categories (Priorities 4–8)

   ▶

   Apply remaining rule categories in priority order. Write each category's findings to its designated output file (see REQUIRED OUTPUT FILES).

7. 7
   Step 7

   Iterate on Errors (max 3 rounds)

   ▶

   If any output file from Steps 3–6 is empty or contains only placeholder text after agent execution:

8. 8
   Step 8

   Write Validation Report

   ▶

   Write `/app/results/validation_report.json` with all stage results: