How to Run Database Migrations with Cline via MCP

Allowing an autonomous coding agent to execute database migrations directly in an IDE introduces a severe risk of catastrophic data loss if the agent runs unvalidated DDL scripts or drops the wrong tables. The solution is not to block AI access to the database entirely, but to implement structured Model Context Protocol (MCP) connections combined with Cline's built-in approval gates.

Traditional migration workflows require developers to copy database schemas, write SQL scripts manually, and run them using local command-line tools. When developers introduce an AI assistant like Cline to speed up this process, the agent needs a way to query the database structure and execute queries. The Model Context Protocol establishes a standard, secure way to expose database tools directly to Cline. By using an MCP server, Cline can read schemas and execute SQL statements.

However, security must remain the primary consideration. Exposing database credentials to an AI model means the model can perform any action allowed by those credentials. If the database role has administrative privileges, a simple prompting error could lead to a dropped schema or leaked table data. To prevent these outcomes, developers must enforce strict credential scoping and rely on client-side safety measures, such as Cline's manual approval settings, before any statement runs.

To execute database migrations, Cline must connect to an MCP server that speaks to the target database. Developers can configure these connections in the local configuration file named cline_mcp_settings.json. By defining the server execution commands, arguments, and environment variables in this file, you establish a direct communication channel. The extension handles launching the server process in the background and querying its tools when analyzing your codebase.

Once configured, Cline gains access to a specific database toolset. The Postgres server provides tools such as list_objects and get_object_details to inspect relations, plus execute_sql to run statements. The Supabase server includes tools like list_migrations and apply_migration to manage schema states. This setup allows the assistant to understand your database architecture before drafting changes, ensuring that all proposed migrations match your current schema definitions.

{
  "mcpServers": {
    "postgres-migrations": {
      "command": "uvx",
      "args": [
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://migration_user:secure_password@localhost:5432/dev_db"
      }
    }
  }
}

{
  "mcpServers": {
    "supabase-mcp": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Once Cline is connected to the database MCP server, the migration workflow begins by drafting the schema changes. The developer directs Cline to create a new SQL migration file in the local project directory. Rather than letting the agent write directly to the database, the recommended approach is to have the agent write the migration script to a file first. This step decouples the drafting process from execution and allows for developer review.

Before applying this change, the developer must review the generated SQL file. AI agents can sometimes make assumptions about data types or trigger naming conventions that do not align with your database architecture. Manually verifying the file ensures that constraints are correct and that database defaults are set properly before execution. This verification step prevents syntax errors and logical conflicts that could disrupt your database state.

-- migrations/0001_create_profiles.sql
CREATE TABLE public.profiles (
    id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
    display_name TEXT,
    avatar_url TEXT,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()) NOT NULL
);

CREATE INDEX idx_profiles_display_name ON public.profiles(display_name);

Centralize database schemas and migration logs

A shared workspace with an MCP-ready endpoint for your agent's reads and writes, with versioning and search built in. Starts with a 14-day free trial.

Start 14-Day Trial

Applying migrations to a database requires execution tools, but running them in production presents safety concerns. Cline mitigates this risk by using built-in approval gates. Whenever Cline attempts to run a write or execute command, such as calling execute_sql or run_sql, the extension pauses. It displays the exact query to the user and requires a manual click to approve or reject the action. This gate prevents the agent from running destructive commands without human oversight.

In a team environment, managing migration scripts and DDL logs becomes a coordination challenge. While local storage works for individual developers, it fails when multiple team members or secondary agents need access. Cloud storage alternatives like Google Drive or AWS S3 can store files, but they lack optimization for agentic workflows. For example, AWS S3 requires manual bucket policy configuration and does not index documents automatically. Google Drive imposes API rate limits that frequently throttle developer agents.

Fast.io solves this coordination problem by providing persistent, shared workspaces for agentic teams. Developers can store DDL files and migration logs in a shared Fast.io workspace. The platform exposes a dedicated MCP server, allowing Cline and other agents to read and write directly to the workspace. You can learn more about configuring agent connections on the Fast.io Agent Workspace page.

When running migrations through Cline via MCP, developers frequently encounter configuration or network errors. Addressing these issues requires systematic verification of settings and connectivity.

One common issue is database connection timeouts. If your database is hosted behind a virtual private cloud (VPC) or uses strict firewall rules, the MCP server running on your local machine will fail to connect. Verify that your database provider allows connections from your local IP address. If the database is hosted on a service like Neon or Supabase, check that you are using the correct connection pooling URL and that SSL is enabled in your connection string.

Another frequent failure is permission errors. If the database role specified in DATABASE_URI does not have DDL privileges, running migrations will fail with a permission denied error. Ensure that the migration user has the necessary permissions to create tables and alter columns in the target schema. To prevent the agent from accessing sensitive production data, developers should configure separate roles: a migration role with DDL permissions for schema changes, and a read-only development role with Row Level Security (RLS) active for regular querying.

Finally, path resolution errors can cause Cline to fail to locate migration files. If Cline is running commands in a nested project folder, it may write migrations to a different folder than expected. Ensure that the project path is explicitly defined in your workspace settings and that relative paths in migration scripts match the working directory of the MCP server. Developers can find more database configuration patterns in the official Supabase documentation.