Flutter Query Linter

Validates Supabase queries in Flutter API files against the database schema (

database.types.ts

). Reports mismatches in table names, column names, relationships, and RPC function calls.

When to Use This Skill

DO use this skill when:

• Debugging Flutter API query failures
• Before pushing mobile app changes that modify queries
• After database schema changes to check for breaking changes
• Investigating "column does not exist" or similar errors
• Reviewing PRs that touch Flutter API files

DO NOT use this skill when:

• Writing new queries (just write them, then validate)
• The issue is clearly RLS/permissions related (not schema)
• Debugging non-query Flutter issues

---

Quick Reference

Run the Linter

# From project root
npx ts-node .claude/skills/flutter-query-lint/scripts/lint-queries.ts

Output Format

The linter produces a markdown report with:

• Errors: Invalid table/column names, missing relationships
• Warnings: RPC functions that may have issues
• Summary: Statistics on validated queries

---

Query Patterns Detected

Table Queries

.from('table_name')

Column Selections

// Simple
.select('col1, col2, col3')

// With relationships
.select('*, relation_name(col1, col2)')

// Aliased relationships
.select('alias:table_name!foreign_key(col1, col2)')

// Multiline
.select('''
  col1,
  col2,
  relation(nested_col)
''')

Filters

.eq('column', value)
.inFilter('column', ['values'])
.gte('column', value)
.lte('column', value)
.neq('column', value)

RPC Calls

.rpc('function_name')
.rpc('function_name', params: {...})

Ordering

.order('column', ascending: true)

---

Validation Rules

1. Table Existence

Checks that the table name in

.from('table')

exists in

database.types.ts

.

2. Column Existence

For each column in

.select()

,

.eq()

,

.order()

, etc., validates it exists on the target table.

Note: The linter handles:

• *

  wildcard (skipped)
• Nested relationships like

  relation(col1, col2)

• Aliased relationships like

  alias:table!fk(col1)

3. Relationship Resolution

For relationship queries like:

.select('productions(id, name)')

Validates that

productions

is either:

• A valid table name (implicit FK)
• An alias with explicit FK reference

4. RPC Function Existence

Checks

.rpc('function_name')

against

Functions

in

database.types.ts

.

---

Common Issues

Missing Column

Error: Column 'name' does not exist on table 'events'
Suggestion: Did you mean 'title'?

Fix: Update the query to use the correct column name.

Invalid Table

Error: Table 'event_participations' does not exist
Suggestion: Did you mean 'event_participants'?

Fix: Use the correct table name.

Unknown Relationship

Warning: Relationship 'venue' on 'events' cannot be validated

Note: May be valid if using implicit FK. Check manually.

Missing RPC Function

Error: RPC function 'get_user_events' does not exist

Fix: Either create the function or remove the call.

---

Integration with Development Workflow

Before Committing Mobile Changes

# Run lint before committing API changes
npx ts-node .claude/skills/flutter-query-lint/scripts/lint-queries.ts

After Schema Changes

When you modify the database schema:

1. Regenerate types:

   pnpm supabase:web:typegen

2. Run Flutter query lint to find broken queries
3. Fix any reported issues

---

Files Scanned

The linter scans:

apps/mobile/lib/modules/*/api/*.dart
apps/mobile/lib/core/data/api/*.dart

Schema Source

Validation uses:

apps/web/supabase/database.types.ts

---

Limitations

1. Dynamic queries: Cannot validate queries built dynamically at runtime
2. Computed columns: Views may have columns not in base tables
3. Complex select strings: Very complex nested selections may not parse correctly
4. RPC return types: Doesn't validate RPC parameter types or return values

---

Related Skills

• db-lint-manager: For PostgreSQL function validation
• database-migration-manager: For creating schema migrations
• flutter-development: For Flutter patterns and best practices