Skip to main content
Glama

db_migrate

Idempotent

Run explicit SQL schema migrations for SQL-mode projects. New projects use declared data: define tables and access rules in db/schema.ts and deploy raw source; db_migrate does not create their tables. docs({ topic: 'declared-data', section: 'declare-a-table-and-use-it' }) has a complete example. Managed projects refuse DDL with SCHEMA_LOCKED and apply no SQL.

For SQL-mode projects, CREATE TABLE, ALTER TABLE, CREATE INDEX and DROP are supported; multiple statements may be separated by ;. Explicit preview targeting changes only that preview database. Developer-only — app-user JWTs are rejected.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "sql": "<sql>"
    },
    "name": "db_migrate"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesDDL statements separated by semicolons.
draftNoAlias for the preview target flag.
targetNoDatabase target. Preview requires preview_session_id (or draft_id).
previewNoExplicit preview target flag. Cannot be combined with a production target.
draft_idNoAlias for preview_session_id.
preview_idNoOptional expected preview candidate release id.
productionNoExplicit production target flag. Cannot be combined with a preview target.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
preview_session_idNoIdentifier for an active preview session's isolated database.
candidate_release_idNoAlias for preview_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds genuinely valuable behavior beyond the annotations: SCHEMA_LOCKED refusal for managed projects, developer-only auth, preview isolation, and multi-statement support. However it conflicts with the supplied annotations — it advertises DROP support while destructiveHint=false claims additive-only behavior, and DDL like CREATE TABLE is not naturally idempotent despite idempotentHint=true. An agent trusting the annotations over the prose could run a destructive DROP believing the tool is non-destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight paragraphs: the first front-loads the scope and the primary exclusion (declared data), the second enumerates supported DDL, statement separation, preview isolation, and auth restrictions. Every sentence carries new information; the pointer to docs for a full example replaces what would otherwise be a long example block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with no output schema, the description covers project-type gating, auth requirements, error behavior (SCHEMA_LOCKED), statement handling, and preview isolation — the main things an agent needs to call it correctly. What it omits is any indication of what a successful call returns (affected statements, applied migration ids, error surface for partial failures).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining that multiple statements may be separated by `;` and that explicit preview targeting affects only the preview database, which clarifies the semantics of the target/preview parameter cluster. It does not, however, explain the preview_id vs preview_session_id distinction, which is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Run explicit SQL schema migrations') and immediately scopes it to SQL-mode projects, explicitly excluding declared-data (new) and managed projects. An agent knows exactly what this tool does and what it will not do without consulting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: new projects should define tables in `db/schema.ts` and use the docs tool (`declared-data` topic), not this tool; managed projects refuse DDL with SCHEMA_LOCKED. It also names the caller requirement ('developer-only — app-user JWTs are rejected') and explains that explicit preview targeting only touches that preview database, which covers when-to-use and when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources