Existing issues
Affected area
Local development
Problem to solve
When building apps with AI-native IDEs and agents (like Cursor, Antigravity, or Claude Code), feeding accurate database context to the model is highly inefficient. Currently, we have two approaches, both presenting major friction:
supabase db dump --schema-only: This outputs raw DDL SQL full of system boilerplate (SET search_path, internal triggers, extension details, etc.). For a standard database, this adds 10k–20k tokens of pure noise, causing the LLM to experience "lost in the middle" context issues and hallucinate columns.- Model Context Protocol (MCP): Live DB tool-calling is great, but it's non-deterministic. If an agent thinks it remembers a table structure from a previous prompt, it often skips running the tool and relies on stale state. Also, granting a live database connection via MCP to external or frontend contractors presents clear security isolation risks.
Manually maintaining static, sliced text files of specific tables and decrypted RLS logic to save tokens is highly redundant and leads to immediate configuration drift as migrations evolve.
i am doing this manually by keeping .md file about the database in the codebase and was just referencing those particular files via the @ tags in the ai chat when doing development inside the ide
i was maintaining those files by copy pasting each command that i have ran in the supabase dashboard sql editor in those md files and it was a bit of bottleneck as i used ai primarily in browser to get the supabase queries that i was going to run for my project as they were upto date [higher logical reasoning and thinking capabilities and turn by turn chat experience as well] and had a better prompt orchestration i feel [personally for the database setup] as well as connected to the internet to get to know the recent changes in the particular type of development i was doing so i copied those response queries there and pasted those in sql editor in the dashboard and then in the md file which i was feeding to the ai by referencing @authentication.md , @order.md so i thought of making this role based as well as multiple files will be there which the ai can reference when we are working on a particular table[s] and rls policies.
Proposed solution
Introduce a subcommand or flag within the next-gen TypeScript CLI (apps/cli) that exports a compressed, declarative Markdown snapshot of the schema, explicitly scoped to a target PostgreSQL role (e.g., authenticated, anon).
Proposed UX
supabase gen ai-context --role=authenticated --output=.ai/schema.md
in the ide we get similar kind of structure
.ai/
├── roles/
│ └── authenticated.md # Global RLS summary for this role
└── tables/
├── profiles.md # Isolated schema + RLS for profiles table
└── orders.md # Isolated schema + RLS for orders table
or multiple files grouped according to a module entirely like profile users orders in one single .md file instead for a quick reference as well
Core Mechanics
Catalog Filtering: Under the hood, the handler queries pg_catalog.pg_class and pg_catalog.pg_policy (using has_table_privilege() and pg_get_policydef()) to dynamically strip out tables and security expressions the specified role has no access to.
Token Density: It converts the raw metadata into a dense, human-readable markdown file[s], stripping all system-level noise. and also seperating them in modules as well like authentication has all the tables realted to it then other modules also get seperate file easy for referencing as well
Workflow Integration: This can easily run as a post-migration step (e.g., alongside supabase db reset) or via pre-commit hooks to keep local AI agents instantly synced with schema updates.
Alternatives considered
- Raw SQL Dumps: Too token-heavy and forces the LLM to waste reasoning tokens "compiling" DDL blocks into its memory map.
- Live MCP tools: Good for core developers, but lacks the ability to sandbox schema visibility for external contributors and still token heavy and connection based.
- Manual curation: Hard/Time Consuming to maintain over time across multiple developers.
Additional context
Example of the intended highly compressed markdown output for the LLM context window:
Table: public.profiles
- Columns:
- id: uuid (Primary Key, references auth.users.id)
- username: text (Nullable)
RLS Policies (Role: authenticated)
- SELECT: Allowed if
(auth.uid() = id)
- UPDATE: Allowed if
(auth.uid() = id)
- INSERT/DELETE: Disallowed
The data fetching, formatting, and file I/O operations can be cleanly handled using Effect v4 pipelines inside the current apps/cli setup.
Existing issues
Affected area
Local development
Problem to solve
When building apps with AI-native IDEs and agents (like Cursor, Antigravity, or Claude Code), feeding accurate database context to the model is highly inefficient. Currently, we have two approaches, both presenting major friction:
supabase db dump --schema-only: This outputs raw DDL SQL full of system boilerplate (SET search_path, internal triggers, extension details, etc.). For a standard database, this adds 10k–20k tokens of pure noise, causing the LLM to experience "lost in the middle" context issues and hallucinate columns.Manually maintaining static, sliced text files of specific tables and decrypted RLS logic to save tokens is highly redundant and leads to immediate configuration drift as migrations evolve.
i am doing this manually by keeping .md file about the database in the codebase and was just referencing those particular files via the @ tags in the ai chat when doing development inside the ide
i was maintaining those files by copy pasting each command that i have ran in the supabase dashboard sql editor in those md files and it was a bit of bottleneck as i used ai primarily in browser to get the supabase queries that i was going to run for my project as they were upto date [higher logical reasoning and thinking capabilities and turn by turn chat experience as well] and had a better prompt orchestration i feel [personally for the database setup] as well as connected to the internet to get to know the recent changes in the particular type of development i was doing so i copied those response queries there and pasted those in sql editor in the dashboard and then in the md file which i was feeding to the ai by referencing @authentication.md , @order.md so i thought of making this role based as well as multiple files will be there which the ai can reference when we are working on a particular table[s] and rls policies.
Proposed solution
Introduce a subcommand or flag within the next-gen TypeScript CLI (
apps/cli) that exports a compressed, declarative Markdown snapshot of the schema, explicitly scoped to a target PostgreSQL role (e.g.,authenticated,anon).Proposed UX
supabase gen ai-context --role=authenticated --output=.ai/schema.md
in the ide we get similar kind of structure
.ai/
├── roles/
│ └── authenticated.md # Global RLS summary for this role
└── tables/
├── profiles.md # Isolated schema + RLS for profiles table
└── orders.md # Isolated schema + RLS for orders table
or multiple files grouped according to a module entirely like profile users orders in one single .md file instead for a quick reference as well
Core Mechanics
Catalog Filtering: Under the hood, the handler queries pg_catalog.pg_class and pg_catalog.pg_policy (using has_table_privilege() and pg_get_policydef()) to dynamically strip out tables and security expressions the specified role has no access to.
Token Density: It converts the raw metadata into a dense, human-readable markdown file[s], stripping all system-level noise. and also seperating them in modules as well like authentication has all the tables realted to it then other modules also get seperate file easy for referencing as well
Workflow Integration: This can easily run as a post-migration step (e.g., alongside supabase db reset) or via pre-commit hooks to keep local AI agents instantly synced with schema updates.
Alternatives considered
Additional context
Example of the intended highly compressed markdown output for the LLM context window:
Table: public.profiles
RLS Policies (Role: authenticated)
(auth.uid() = id)(auth.uid() = id)The data fetching, formatting, and file I/O operations can be cleanly handled using Effect v4 pipelines inside the current apps/cli setup.