apply_migration
Execute and track SQL migration scripts within a self-hosted Supabase instance. Ensures database schema updates are applied and recorded in the schema_migrations table. Requires version and SQL inputs for reliable migration management.
Instructions
Applies a SQL migration script and records it in the supabase_migrations.schema_migrations table within a transaction.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | An optional descriptive name for the migration. | |
| sql | Yes | The SQL DDL content of the migration. | |
| version | Yes | The migration version string (e.g., '20240101120000'). |
Implementation Reference
- src/tools/apply_migration.ts:38-77 (handler)The execute handler function that applies the provided SQL migration within a transaction and records the migration version in the supabase_migrations.schema_migrations table.execute: async (input: ApplyMigrationInput, context: ToolContext) => { const client = context.selfhostedClient; try { // Ensure pg is configured and available if (!client.isPgAvailable()) { throw new Error('Direct database connection (DATABASE_URL) is required for applying migrations but is not configured or available.'); } await client.executeTransactionWithPg(async (pgClient: PoolClient) => { // 1. Execute the provided migration SQL console.error(`Executing migration SQL for version ${input.version}...`); await pgClient.query(input.sql); console.error('Migration SQL executed successfully.'); // 2. Insert the record into the migrations table console.error(`Recording migration version ${input.version} in schema_migrations...`); await pgClient.query( 'INSERT INTO supabase_migrations.schema_migrations (version, name) ' + 'VALUES ($1, $2);', [input.version, input.name ?? ''] ); console.error(`Migration version ${input.version} recorded.`); }); return { success: true, version: input.version, message: `Migration ${input.version} applied successfully.`, }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); console.error(`Failed to apply migration ${input.version}:`, errorMessage); // Return a structured error response recognized by handleSqlResponse if needed, // or let the SDK handle the thrown error. // Here, we'll just rethrow to let SDK handle it. // Alternatively, return { success: false, version: input.version, message: 'Failed: ' + errorMessage }; throw new Error(`Failed to apply migration ${input.version}: ${errorMessage}`); } },
- src/tools/apply_migration.ts:5-19 (schema)Zod schemas defining the input (version, optional name, sql) and output (success, version, message) for the apply_migration tool.// Input schema const ApplyMigrationInputSchema = z.object({ version: z.string().describe("The migration version string (e.g., '20240101120000')."), name: z.string().optional().describe("An optional descriptive name for the migration."), sql: z.string().describe("The SQL DDL content of the migration."), }); type ApplyMigrationInput = z.infer<typeof ApplyMigrationInputSchema>; // Output schema const ApplyMigrationOutputSchema = z.object({ success: z.boolean(), version: z.string(), message: z.string().optional(), });
- src/index.ts:14-14 (registration)Import statement for the applyMigrationTool.import { applyMigrationTool } from './tools/apply_migration.js';
- src/index.ts:103-103 (registration)Registration of applyMigrationTool in the availableTools object used by the MCP server.[applyMigrationTool.name]: applyMigrationTool as AppTool,