🚀 Supabase AI Context Bridge

Let any AI understand your database instantly. No more copy-pasting schemas or explaining table relationships.

The Problem

Every time you ask ChatGPT, Claude, or any AI to help with SQL queries, you waste time:

• Copy-pasting table schemas
• Explaining relationships
• Fixing queries that reference non-existent columns
• Re-explaining your database structure in every new chat

The Solution

Supabase AI Context Bridge automatically:

• 📊 Introspects your entire database schema
• 📝 Generates AI-friendly documentation
• 🔍 Validates queries before execution
• 💉 Injects context directly into AI chats
• 🛡️ Works in read-only mode for safety

Quick Start (2 minutes)

1. Install CLI

npm install -g @supabase-ai/bridge
# or
npx @supabase-ai/bridge

2. Connect to Your Database

# Using Supabase credentials
supabase-ai connect \
  --url https://xxx.supabase.co \
  --key your-anon-key

# Or using direct Postgres connection
supabase-ai connect \
  --db-url postgresql://user:pass@host:5432/dbname

3. Generate Context for AI

# Generate and copy to clipboard
supabase-ai context --copy

# Or save to file
supabase-ai context -o schema.md

4. Paste into Any AI Chat

Now paste the context into ChatGPT, Claude, Cursor, or any AI tool and start asking questions!

Features

🎯 CLI Tool

# Test connection
supabase-ai connect

# Generate schema documentation
supabase-ai schema --format markdown

# Generate AI context (auto-truncated)
supabase-ai context --max-length 10000

# Validate SQL queries
supabase-ai validate "DELETE FROM users WHERE active = false"
# Output: ⚠️ WARNING: DELETE without WHERE clause will affect ALL rows!

# Save queries for later
supabase-ai validate "SELECT * FROM orders WHERE total > 1000" --save high-value
supabase-ai run high-value

# View query history
supabase-ai history
supabase-ai history --saved  # Show only saved queries

# Generate AI prompts with context
supabase-ai prompt -t write --task "find inactive users"
supabase-ai prompt -t optimize -q "SELECT * FROM products WHERE id IN (SELECT product_id FROM orders)"
supabase-ai prompt -t debug -q "YOUR_QUERY" -e "column does not exist"
supabase-ai prompt --list  # See all templates

# Initialize config file
supabase-ai init

🌐 Browser Extension

Install the extension to inject database context with one click:

1. Load /extension folder in Chrome/Edge as unpacked extension
2. Enter your Supabase credentials
3. Click "Add DB Context" button on any AI chat
4. Or use keyboard shortcut: Ctrl+Shift+D

Works on:

• ChatGPT (chat.openai.com)
• Claude (claude.ai)
• Google Gemini (gemini.google.com)

📚 Node.js Library

import { 
  SupabaseConnection, 
  SupabaseIntrospector, 
  ContextGenerator,
  QueryValidator 
} from '@supabase-ai/bridge';

// Connect
const connection = new SupabaseConnection({
  supabaseUrl: 'https://xxx.supabase.co',
  supabaseAnonKey: 'your-key'
});
await connection.connect();

// Get schema
const introspector = new SupabaseIntrospector(connection);
const schema = await introspector.getSchema();

// Generate context
const generator = new ContextGenerator();
const context = generator.generateContext(schema, {
  format: 'markdown',
  maxLength: 10000
});

// Validate queries
const validator = new QueryValidator(schema);
const result = validator.validate('SELECT * FROM users');
console.log(result); 
// { valid: true, warnings: [], affectedTables: ['users'] }

Example Output

# Database Schema

## Tables

### public.users
| Column | Type | Nullable | Default |
|--------|------|----------|---------|
| id | uuid | NO | gen_random_uuid() |
| email | text | NO | - |
| username | text | NO | - |
| created_at | timestamptz | NO | now() |

**Primary Key:** id

### public.posts
| Column | Type | Nullable | Default |
|--------|------|----------|---------|
| id | bigint | NO | - |
| user_id | uuid | NO | - |
| title | text | NO | - |
| content | text | YES | - |
| published | boolean | NO | false |

**Foreign Keys:**
- user_id → users.id

Configuration

Create .supabase-ai.json in your project:

{
  "supabaseUrl": "https://xxx.supabase.co",
  "supabaseAnonKey": "your-anon-key",
  "databaseUrl": "postgresql://...",
  "options": {
    "includeIndexes": false,
    "includeFunctions": false,
    "includePolicies": true,
    "maxContextLength": 10000
  }
}

Or use environment variables:

export SUPABASE_URL=https://xxx.supabase.co
export SUPABASE_ANON_KEY=your-anon-key
export DATABASE_URL=postgresql://...

Use Cases

1. Writing Complex Queries

"Given my schema above, write a query to find all users who haven't posted in 30 days"

2. Debugging Errors

"This query returns an error: [paste query]. Based on my schema, what's wrong?"

3. Data Modeling

"Should I add an index on posts.user_id based on my current schema?"

4. Migration Planning

"How should I add a 'comments' table that relates to both users and posts?"

Safety Features

• 🔒 Read-only by default - No accidental data modifications
• ✅ Query validation - Catches errors before execution
• ⚠️ Warning system - Alerts for dangerous operations
• 🛡️ SQL injection detection - Identifies risky patterns

Roadmap

• [ ] Support for more databases (MySQL, MongoDB)
• [ ] Real-time schema sync
• [ ] Query execution sandbox
• [ ] Team collaboration features
• [ ] VS Code extension
• [ ] Cursor IDE integration

License

MIT

Contributing

PRs welcome! Check out our contributing guide.

Built with ❤️ for developers tired of explaining their database to AI