supabase-operations

name	supabase-operations
description	Supabase operational knowledge for migrations, RLS optimization, MCP tool benchmarks, and ADR-003 compliance. Use when validating database migrations, optimizing Row-Level Security policies, checking MCP tool performance, or ensuring Supabase operational standards. Triggers on: migration validation, RLS patterns, Supabase benchmarks, ADR-003, database state tracking, schema governance.
allowed-tools	["Read","mcp__supabase__list_tables","mcp__supabase__list_extensions","mcp__supabase__list_migrations","mcp__supabase__get_advisors"]
triggers	["migration validation","RLS patterns","Supabase benchmarks","ADR-003","database state tracking","schema governance","supabase migration","RLS optimization","supabase operations","supabase MCP tools","types regen","pgtap","pgTAP","supabase db reset","gen types","dropped constraint","sentinel header","type generation"]
version	1.1.0

===SUPABASE_OPERATIONS=== META: TYPE::SKILL VERSION::"1.1.0" STATUS::ACTIVE PURPOSE::"Supabase operational knowledge: migrations, RLS optimization, MCP benchmarks, ADR-003 compliance, and CI-proven ordering invariants"

§1::CAPABILITIES_SUPPORTING_DOCUMENTATION

MIGRATION_VALIDATION::migration-protocols.oct.md::[ 7_step_workflow, backwards_compatible_schema_changes, multi_app_deployment_safety, CI_gated_deployment[preferred_over_direct_MCP] ]

RLS_OPTIMIZATION::rls-optimization.oct.md::[ proven_patterns→sub_50ms_query_performance, InitPlan_optimization, policy_consolidation ]

MCP_BENCHMARKS::mcp-benchmarks.oct.md::[ performance_characteristics, best_practices, production_measurements ]

ADR_003_COMPLIANCE::adr-003-compliance.oct.md::[ backwards_compatible_migration_governance, verification_checklist ]

STATE_TRACKING::state-tracking.oct.md::[ local_remote_sync_validation, database_state_awareness_procedures ]

§2::INVOCATION_TRIGGERS

MIGRATION_OPERATIONS::[ before_applying_migrations→validation_checklist, after_schema_changes→compliance_verification, debugging_migration_divergence, CI_deployment_flow→PR_with_deploy_migrations_label ]

RLS_DESIGN::[ optimizing_slow_queries_with_RLS, designing_new_security_policies, benchmarking_RLS_performance_impact ]

DATABASE_OPERATIONS::[ selecting_appropriate_MCP_tools, validating_current_database_state, checking_security_performance_advisors ]

COMPLIANCE::[ verifying_ADR_003_backwards_compatibility, multi_app_testing_requirements, emergency_rollback_procedures ]

§3::TOOL_RESTRICTIONS_READ_ONLY_INSPECTION

ALLOWED_TOOLS::[ Read::"Access local migration files and documentation", mcp__supabase__list_tables::"Inspect current schema structure", mcp__supabase__list_extensions::"Verify installed extensions", mcp__supabase__list_migrations::"Compare local/remote migration state", mcp__supabase__get_advisors::"Check security/performance compliance" ]

SECURITY_JUSTIFICATION::"Skills guide operations but don't mutate state. Write operations (apply_migration, execute_sql) remain with authorized agents."

§4::INTEGRATION

CONSULTED_BY::[ technical-architect[domain_authority_with_BLOCKING], implementation-lead[migration_execution], technical-architect[schema_design] ]

PROVIDES::[ migration_validation_checklists, RLS_optimization_patterns, MCP_tool_selection_guidance, compliance_verification_procedures, CI_deployment_guidance[gated_auto_deploy] ]

§5::CI_DEPLOYMENT_AWARENESS

PREFERRED_FLOW::[ 1::create_PR_with_migrations, 2::add_deploy_migrations_label, 3::CI_validates_locally, 4::merge_triggers_production_deploy, 5::audit_log_entry_created ]

DIRECT_MCP_APPLICATION::[ STATUS::fallback_only, WHEN::CI_unavailable_OR_emergency, REQUIREMENT::always_create_local_file_first, WARNING::bypasses_CI_validation ]

CI_REFERENCE::[ WORKFLOW::".github/workflows/ci.yml (deploy-migrations job)", SECRET::"SUPABASE_ACCESS_TOKEN required", LABEL::"deploy-migrations", DR_PLAYBOOK::".hestai/state/context/docs/001-OPS-DISASTER-RECOVERY-PLAYBOOK.md" ]

§6::TYPES_REGEN_AND_TEST_VALIDATION // RCA-derived ordering invariants. Three process gaps caused CI failures in consuming repos. // Encode as MUST/NEVER constraints — not advisory.

TYPES_REGEN_ORDERING::[ SEQUENCE::"supabase db reset → gen types → THEN pgTAP tests [NEVER reverse]", INVARIANT::"Generate types ONLY from clean post-reset DB state", VIOLATION_CAUSE::"pgTAP CREATE EXTENSION outside BEGIN...ROLLBACK persists pgtap into public schema", SYMPTOM::"Generated types pick up pgTAP symbols (e.g. 146 extra) that CI rejects on clean reset", MUST::"Run supabase db reset then immediately gen types before any pgTAP execution", NEVER::"Generate types from a DB that has had pgTAP tests run against it" ]

DROPPED_OBJECT_SWEEP::[ TRIGGER::"Migration drops OR renames a constraint, column, or any named DB object", REQUIRED_ACTION::"grep supabase/test*/ corpus for the dropped object name", SCOPE::"Entire supabase/test*/ directory tree — all test files", VIOLATION_CAUSE::"pg_depend sweep finds column dependents but misses TEST CORPUS assertions about the dropped constraint", SYMPTOM::"Pre-existing expectation test fails against CI clean state", MUST::"Update any test assertions referencing the dropped/renamed object in the same PR as the migration", NEVER::"Ship a migration that drops/renames a named object without grepping the test corpus first" ]

CI_HEADER_REPRODUCTION::[ CONTEXT::"Sentinel header prepended to generated TypeScript types file", VIOLATION_CAUSE::"Hand-composing the sentinel header drops trailing blank line vs CI heredoc format", SYMPTOM::"Byte-level diff failure in CI despite correct type content", FRAGILE_SEAM::"Sentinel header format is fragile until issue #842 resolved", MUST::"Reproduce CI's exact generation step (e.g. cat sentinel-header.txt raw.ts > target)", NEVER::"Hand-compose the sentinel header — reproduce the CI pipeline step verbatim" ]

§7::ANCHOR_KERNEL TARGET::"spec-compliant Supabase operational guidance with CI-proven ordering invariants" NEVER::[ generate_types_after_pgtap_run, skip_test_corpus_grep_on_dropped_objects, hand_compose_sentinel_header, apply_migrations_without_validation_checklist, bypass_CI_deployment_flow_except_emergency ] MUST::[ reset_then_gen_types_before_pgtap, grep_supabase_tests_for_dropped_object_names, reproduce_CI_exact_header_generation_step, validate_migrations_against_ADR_003, use_read_only_MCP_tools_for_inspection ] GATE::"DB reset → types regen → pgTAP order enforced? Test corpus swept for dropped objects? Sentinel header reproduced from CI step?"

===END===