Skip to main content
Glama
nerdit-ai

Nerdit

Official
by nerdit-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

dump_database

Captures an application-consistent logical dump of a Postgres or Redis database before migrations or destructive changes, storing the artifact server-side.

Instructions

Capture a logical, application-consistent dump of a managed database.

    The daemon runs the engine's own dump tool — ``pg_dump --format=custom``
    for Postgres, ``redis-cli --rdb`` for Redis — from a throwaway container
    built from the database's OWN image, against the running server. This is
    the dump to take before a migration or a destructive change: unlike the
    volume backup (``nerdit backup --volume``, no tool), it is consistent by
    the engine's rules rather than by the filesystem's.

    CUSTODY: the artifact is a server-side tar under the daemon's backups
    directory holding **every row** of ``name``; it is never served over
    HTTP and nothing but metadata comes back here — basename, size, sha256,
    engine, format, duration. Treat the basename as the handle: it is what
    ``nerdit db restore`` takes.

    RETENTION: the daemon keeps the last ``[retention].dump_keep_last``
    dumps per database (default 5) and prunes older ones on its hourly
    sweep, so a dump is not an archive. Copy one off the box if it must
    outlive that window.

    TIMEOUT: the default matches the usual MCP client read budget, not
    the route's own 900: if your client gives up first, **a longer dump still completes
    server-side and appears in ``list_database_dumps``**. So a read timeout
    here is not a failure — call ``list_database_dumps`` and take the newest
    entry. Do NOT blind-retry: this tool mints its own idempotency key per
    call, so a retry is a second real dump (and the first one may still be
    running, which answers ``409 dump.in_progress``).

    Authorization is **owner-or-admin plus token scope**: a scoped submitter
    can dump the databases it created, which is what makes this usable over
    the (submitter-capped) cloud link. Refusals you should branch on: ``409
    dump.database_not_ready`` (not running, or still doing initdb — poll
    ``list_databases`` for ``db_ready``), ``409 dump.in_progress`` (this
    database already has one running; distinct from the daemon-wide
    ``backup.in_progress``), ``409 dump.too_many_in_flight``, ``409
    dump.insufficient_disk`` (the error object carries top-level
    ``required_bytes`` / ``free_bytes``), ``422 dump.not_a_database``, and
    ``500 dump.failed``
    whose ``hint`` is the tool's own last output line. There is deliberately
    **no restore tool** — restoring replaces live data and stays on the CLI
    (``nerdit db restore``) and REST.

Input Schema

NameRequiredDescriptionDefault
nameYesName of an existing managed database (``kind=database``); an app or model row is refused.
timeout_sNoSeconds the dump tool may run server-side; omit for 300. Floored at 1 and otherwise passed straight through, so a value above the daemon's ``[services].dump_timeout_max_s`` gets the authoritative 422 ``dump.timeout_too_large`` instead of being silently clamped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: artifact custody (server-side tar, metadata only returned, never served over HTTP), retention (last N per DB pruned hourly, not an archive), per-call idempotency key semantics making retries unsafe, authorization model (owner-or-admin plus token scope), and a branchable error-code catalogue including the distinction between dump.in_progress and backup.in_progress.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence and the remainder is organized under explicit CUSTODY / RETENTION / TIMEOUT / authorization headings, so it scans well. It is long and dense, and the enumerated 409 codes push toward the verbose end, but nearly every clause carries decision-relevant information for a tool with no annotations.

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?

For a destructive-ish long-running operation with no annotations and no output schema, the description supplies everything an agent needs: the returned metadata fields (basename, size, sha256, engine, format, duration), how to use the basename with restore, retention lifetime, and the failure modes to branch on.

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 would be 3, but the description adds real meaning to timeout_s by explaining that the default matches the client read budget rather than the route's own 900s, and that a client-side timeout does not mean the server-side dump failed. Input `name` is only lightly reinforced beyond the schema, hence not a full 5.

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?

States a specific verb and resource ("Capture a logical, application-consistent dump of a managed database") and immediately names the underlying engine tooling (pg_dump custom format, redis-cli --rdb). It also distinguishes itself from the sibling volume-backup path, so an agent can tell which backup mechanism it is choosing.

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?

Explicit timing guidance: "the dump to take before a migration or a destructive change", contrasted against the filesystem-based volume backup. It also gives operative alternatives for the edge cases — on timeout call list_database_dumps rather than retrying, and restore is deliberately out of scope on the CLI/REST. When-to-use, when-not-to-retry, and the alternative path are all spelled out.

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

Deploy Server

Other Tools