apply_migration
Execute SQL migration scripts within transactions to update self-hosted Supabase databases, tracking applied migrations in the schema_migrations table.
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 |
|---|---|---|---|
| version | Yes | The migration version string (e.g., '20240101120000'). | |
| name | No | An optional descriptive name for the migration. | |
| sql | Yes | The SQL DDL content of the migration. |
Implementation Reference
- src/tools/apply_migration.ts:38-77 (handler)The execute handler function that applies the provided SQL migration using a direct PG client within a transaction and records the migration 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:6-11 (schema)Zod input schema and type for the apply_migration tool, defining version, optional name, and sql parameters.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>;
- src/tools/apply_migration.ts:14-18 (schema)Zod output schema for the apply_migration tool, including success boolean, version, and optional message.const ApplyMigrationOutputSchema = z.object({ success: z.boolean(), version: z.string(), message: z.string().optional(), });
- src/tools/apply_migration.ts:32-78 (registration)Export of the applyMigrationTool object, defining the tool name, description, schemas, and execute handler.export const applyMigrationTool = { name: 'apply_migration', description: 'Applies a SQL migration script and records it in the supabase_migrations.schema_migrations table within a transaction.', inputSchema: ApplyMigrationInputSchema, mcpInputSchema: mcpInputSchema, outputSchema: ApplyMigrationOutputSchema, 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/index.ts:103-103 (registration)Registration of the apply_migration tool in the availableTools object used by the MCP server.[applyMigrationTool.name]: applyMigrationTool as AppTool,