retrieve_migrations

Retrieve detailed information about Supabase database migrations, including version, name, and SQL statements. Use filters for pagination, name patterns, and query inclusion with this low-risk read tool.

Instructions

Retrieve a list of all migrations a user has from Supabase.

Returns a list of migrations with the following information:

Version (timestamp)
Name
SQL statements (if requested)
Statement count
Version type (named or numbered)

Parameters:

limit: Maximum number of migrations to return (default: 50, max: 100)
offset: Number of migrations to skip for pagination (default: 0)
name_pattern: Optional pattern to filter migrations by name. Uses SQL ILIKE pattern matching (case-insensitive). The pattern is automatically wrapped with '%' wildcards, so "users" will match "create_users_table", "add_email_to_users", etc. To search for an exact match, use the complete name.
include_full_queries: Whether to include the full SQL statements in the result (default: false)

SAFETY: This is a low-risk read operation that can be executed in SAFE mode.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`include_full_queries`	No
`limit`	No
`name_pattern`	No
`offset`	No

Implementation Reference

supabase_mcp/core/feature_manager.py:121-134 (handler)

Core handler implementing the retrieve_migrations tool logic: generates SQL query for migrations using query_manager and executes it.

async def retrieve_migrations(
    self,
    container: "ServicesContainer",
    limit: int = 50,
    offset: int = 0,
    name_pattern: str = "",
    include_full_queries: bool = False,
) -> QueryResult:
    """Retrieve a list of all migrations a user has from Supabase."""
    query_manager = container.query_manager
    query = query_manager.get_migrations_query(
        limit=limit, offset=offset, name_pattern=name_pattern, include_full_queries=include_full_queries
    )
    return await query_manager.handle_query(query)

supabase_mcp/tools/registry.py:57-78 (registration)

Registers the retrieve_migrations tool with the MCP server using @mcp.tool decorator, defines input schema and description, delegates execution to feature_manager.

@mcp.tool(description=tool_manager.get_description(ToolName.RETRIEVE_MIGRATIONS))  # type: ignore
async def retrieve_migrations(
    limit: int = 50,
    offset: int = 0,
    name_pattern: str = "",
    include_full_queries: bool = False,
) -> QueryResult:
    """Retrieve a list of all migrations a user has from Supabase.

    SAFETY: This is a low-risk read operation that can be executed in SAFE mode.
    """

    result = await feature_manager.execute_tool(
        ToolName.RETRIEVE_MIGRATIONS,
        services_container=services_container,
        limit=limit,
        offset=offset,
        name_pattern=name_pattern,
        include_full_queries=include_full_queries,
    )
    return QueryResult.model_validate(result)

supabase_mcp/tools/registry.py:57-78 (schema)

Defines the input schema (parameters with types and defaults) and output type (QueryResult) for the retrieve_migrations tool.

@mcp.tool(description=tool_manager.get_description(ToolName.RETRIEVE_MIGRATIONS))  # type: ignore
async def retrieve_migrations(
    limit: int = 50,
    offset: int = 0,
    name_pattern: str = "",
    include_full_queries: bool = False,
) -> QueryResult:
    """Retrieve a list of all migrations a user has from Supabase.

    SAFETY: This is a low-risk read operation that can be executed in SAFE mode.
    """

    result = await feature_manager.execute_tool(
        ToolName.RETRIEVE_MIGRATIONS,
        services_container=services_container,
        limit=limit,
        offset=offset,
        name_pattern=name_pattern,
        include_full_queries=include_full_queries,
    )
    return QueryResult.model_validate(result)

supabase_mcp/tools/manager.py:19-19 (helper)
Defines the ToolName.RETRIEVE_MIGRATIONS constant used throughout for referencing the tool.
```
RETRIEVE_MIGRATIONS = "retrieve_migrations"
```

Supabase MCP Server