Skip to main content
Glama

db_dump

Read-onlyIdempotent

Full SQL dump of the project's database — schema (CREATE TABLE / INDEX / TRIGGER) + every row as INSERT statements. The output is standard SQL you can pipe into any SQL database client to restore, or migrate to Postgres via pgloader.

Returns the raw .sql file as a string. One call gives you the complete raw SQL database's schema and rows to take anywhere. A project that keeps its tables in the managed database has no raw SQL database to dump (RAW_DATABASE_NOT_READY); its managed rows are read with db_browse (plane: "managed") and their schema and row counts with db_describe.

Table access declarations and sensitive-column marks are platform policy, not SQL. Their labels travel as comment lines in the SQL preamble and, parsed, as excluded_security_policy.policies (labels only, never applied by a SQL restore); a warning appears only when the list is non-empty. policies: [] on a successful capture means no table-access declarations were found in this capture — it does not establish that access is safe or preserve your application's authorization, and member join definitions and handler authorization are outside that list. After restoring, redeploy db/schema.ts (access rules are set there and take effect on deploy), then verify with db_scope_list.

excluded_security_policy.capture (v1) is the capture receipt, carrying identity, hashes and times only: canonical project_id and database_id (the top-level project_id echoes your reference), sql_sha256 / schema_sha256 / policy_sha256, and policy_observed_at, data_observation_started_at, data_observation_completed_at, binding_checked_at. The hashes detect changed bytes against metadata you retain; they are not a signature, not provenance, and not a cross-store snapshot. Matching binding checks before and after mean the same project, owner and database were observed; they do not exclude a change in between. When capture metadata is present but malformed, or its SQL or policy hash does not match, this tool returns DUMP_INTEGRITY_UNCONFIRMED (502) and no SQL. An absent capture (an older API during a rolling release) means no capture-integrity evidence; the informational policy labels may still be present.

Refusals, never a partial file: DATABASE_NOT_INITIALIZED (409 — the dump never creates a database), DUMP_SOURCE_CHANGED (409), DUMP_SCHEMA_CHANGED (409), DUMP_POLICY_INVALID (422), DUMP_UNSUPPORTED_SCHEMA (422), DUMP_ROW_LIMIT_EXCEEDED (413, above 1,000,000 rows in a table — no truncation and no streaming export; narrow with db_export_csv filters), DUMP_CAPTURE_LIMIT_EXCEEDED (413), DUMP_POLICY_UNAVAILABLE (503), DUMP_CAPTURE_UNCONFIRMED (503), DUMP_SCHEMA_UNAVAILABLE (503), PROJECT_ACCESS_DENIED (403).

Example:

{ "project_id": "my-saas" }
// Returns the full .sql as text — write it to disk and you're portable.

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>"
    },
    "name": "db_dump"
  }
}

Input Schema

NameRequiredDescriptionDefault
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).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations only declare readOnlyHint/idempotent, and the description adds a great deal on top: the return is a raw .sql string, refusals are all-or-nothing with no partial file, integrity failures return DUMP_INTEGRITY_UNCONFIRMED with no SQL, and policy labels are informational only and never applied by a restore. It also discloses the row cap (1,000,000, no truncation/streaming) and the meaning of an absent capture receipt. The only reason it isn't a 5 is that the hash/binding prose, while accurate, is dense enough to be hard to act on.

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

Conciseness3/5

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

It is front-loaded and well-organized into purpose, capture receipt, refusals, and example, but for a one-parameter read tool the body is very long. The paragraph on sql_sha256/schema_sha256/policy_sha256 and binding timestamps is disproportionately heavy for selection or invocation decisions.

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

Completeness5/5

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

With no output schema and a single parameter, the description supplies what an agent would otherwise lack: return format, the complete refusal taxonomy with HTTP codes, the managed-vs-raw distinction, and the post-restore deployment step. Nothing needed to call it correctly or interpret a failure appears to be missing.

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

Parameters3/5

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

Schema coverage is 100% and the single project_id parameter is fully documented in the schema, so baseline is 3. The description adds only marginal semantics — that the top-level echo reflects your reference and that slug-style IDs work in the example ('my-saas').

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?

The opening sentence names a specific verb and resource and enumerates contents: 'Full SQL dump of the project's database — schema (CREATE TABLE / INDEX / TRIGGER) + every row as INSERT statements.' It also carves out the sibling case explicitly, noting that managed-database projects have no raw SQL database and that db_browse (plane: "managed") / db_describe serve those rows and schemas instead.

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?

It states both when to use it (portable, restorable raw SQL capture) and when not to (managed-plane projects get RAW_DATABASE_NOT_READY and should use db_browse / db_describe). It further routes oversized cases to db_export_csv filters and prescribes post-restore steps of redeploying db/schema.ts then verifying with db_scope_list.

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