execute_postgresql
Execute PostgreSQL queries on Supabase databases with safety controls. Perform read, write, and schema operations, supported by transaction handling and automatic version-controlled migrations. Use UNSAFE mode for write and schema changes; confirm high-risk actions.
Instructions
Execute PostgreSQL statements against your Supabase database.
IMPORTANT: All SQL statements must end with a semicolon (;).
OPERATION TYPES AND REQUIREMENTS:
READ Operations (SELECT, EXPLAIN, etc.):
Can be executed directly without special requirements
Example: SELECT * FROM public.users LIMIT 10;
WRITE Operations (INSERT, UPDATE, DELETE):
Require UNSAFE mode (use live_dangerously('database', True) first)
Example: INSERT INTO public.users (email) VALUES ('user@example.com');
SCHEMA Operations (CREATE, ALTER, DROP):
Require UNSAFE mode (use live_dangerously('database', True) first)
Destructive operations (DROP, TRUNCATE) require additional confirmation
Example: CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);
MIGRATION HANDLING: All queries that modify the database will be automatically version controlled by the server. You can provide optional migration name, if you want to name the migration.
Respect the following format: verb_noun_detail. Be descriptive and concise.
Examples:
create_users_table
add_email_to_profiles
enable_rls_on_users
If you don't provide a migration name, the server will generate one based on the SQL statement
The system will sanitize your provided name to ensure compatibility with database systems
Migration names are prefixed with a timestamp in the format YYYYMMDDHHMMSS
SAFETY SYSTEM: Operations are categorized by risk level:
LOW RISK: Read operations (SELECT, EXPLAIN) - allowed in SAFE mode
MEDIUM RISK: Write operations (INSERT, UPDATE, DELETE) - require UNSAFE mode
HIGH RISK: Schema operations (CREATE, ALTER) - require UNSAFE mode
EXTREME RISK: Destructive operations (DROP, TRUNCATE) - require UNSAFE mode and confirmation
TRANSACTION HANDLING:
DO NOT use transaction control statements (BEGIN, COMMIT, ROLLBACK)
The database client automatically wraps queries in transactions
The SQL validator will reject queries containing transaction control statements
This ensures atomicity and provides rollback capability for data modifications
MULTIPLE STATEMENTS:
You can send multiple SQL statements in a single query
Each statement will be executed in order within the same transaction
Example: CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); INSERT INTO public.test_table (name) VALUES ('test');
CONFIRMATION FLOW FOR HIGH-RISK OPERATIONS:
High-risk operations (DROP TABLE, TRUNCATE, etc.) will be rejected with a confirmation ID
The error message will explain what happened and provide a confirmation ID
Review the risks with the user before proceeding
Use the confirm_destructive_operation tool with the provided ID to execute the operation
IMPORTANT GUIDELINES:
The database client starts in SAFE mode by default for safety
Only enable UNSAFE mode when you need to modify data or schema
Never mix READ and WRITE operations in the same transaction
For destructive operations, be prepared to confirm with the confirm_destructive_operation tool
WHEN TO USE OTHER TOOLS INSTEAD:
For Auth operations (users, authentication, etc.): Use call_auth_admin_method instead of direct SQL The Auth Admin SDK provides safer, validated methods for user management
For project configuration, functions, storage, etc.: Use send_management_api_request The Management API handles Supabase platform features that aren't directly in the database
Note: This tool operates on the PostgreSQL database only. API operations use separate safety controls.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| migration_name | No | ||
| query | Yes |
Implementation Reference
- Core handler function implementing the execute_postgresql tool logic by delegating query execution to the query_manager.
async def execute_postgresql( self, container: "ServicesContainer", query: str, migration_name: str = "" ) -> QueryResult: """Execute PostgreSQL statements against your Supabase database.""" query_manager = container.query_manager return await query_manager.handle_query(query, has_confirmation=False, migration_name=migration_name) - supabase_mcp/tools/registry.py:47-55 (registration)Registration of the execute_postgresql tool using the @mcp.tool decorator, including input schema via type annotations. Delegates to feature_manager.
@mcp.tool(description=tool_manager.get_description(ToolName.EXECUTE_POSTGRESQL)) # type: ignore async def execute_postgresql(query: str, migration_name: str = "") -> QueryResult: """Execute PostgreSQL statements against your Supabase database.""" return await feature_manager.execute_tool( ToolName.EXECUTE_POSTGRESQL, services_container=services_container, query=query, migration_name=migration_name, ) - supabase_mcp/core/feature_manager.py:75-76 (registration)Dispatch registration within FeatureManager.execute_tool method for handling ToolName.EXECUTE_POSTGRESQL.
elif tool_name == ToolName.EXECUTE_POSTGRESQL: return await self.execute_postgresql(services_container, **kwargs) - supabase_mcp/tools/manager.py:18-18 (schema)ToolName enum definition providing the string identifier for the execute_postgresql tool.
EXECUTE_POSTGRESQL = "execute_postgresql"