List configured databases with their allowed mode and yolo flag (no DSN).

Call this first: every other tool takes one of these names as its database argument. It reads only the local connections.json and opens no connection — to test whether a database actually answers, use check_database.

Returns meta and databases, one item per configured database with name, mode and yolo. Entries with fallback_ports configured also show them, plus active_port when a fallback port is currently in use.

List all tables and views in the named database.

Use this to find a table's exact name. For its columns and keys use get_table_schema; to find which table holds a column, use find_columns; for every table's columns at once, get_database_schema.

Narrow instead of listing everything: pattern keeps only names containing it (fuzzy, case-insensitive — "order" matches ORDERS, order_items). limit returns at most that many rows, so a huge database can't flood the answer.

Returns meta and tables, one item per table or view with schema, name and kind (table or view). With limit set, meta.truncated is true when more tables matched than were returned.

Get columns, types, and primary/foreign keys for a table.

For one table. For every table at once use get_database_schema; for a view, function, trigger, sequence or index definition use get_object_definition.

Returns meta, table, columns (name, type, nullable, default), primary_key and foreign_keys, plus indexes when asked for; a table that does not exist is an error.

Pass include_indexes=true to also get the table's indexes (name, its KEY columns in index order — an INCLUDE payload is not listed — whether it is unique, and its method: btree, gin, ...). Use it before writing a filter or a JOIN, or when a query is slow and you want to know what is actually indexed. Omitted by default, so the plain answer stays small.

Get the whole database's schema at once, as JSON or as a runnable SQL script.

format="json" (default): every table with columns, types, nullability, primary key, and foreign keys. format="sql": a SELF-CONTAINED DDL script that recreates the schema — tables, columns, sequences, PK/FK/UNIQUE/CHECK, indexes, trigger functions, and triggers — so running it rebuilds the structure. No extra tools needed; covers the common cases (for a byte-faithful dump use dump_schema_faithful).

Returns meta, database and generated_utc, then table_count and tables (json) or format and ddl (sql). Schema content is deterministic; meta.elapsed_ms varies. Returned inline by default; pass output_dir to instead WRITE it to {database}_schema_{UTC}.{json|sql} and get back saved_to plus a summary — recommended for large schemas too big to return inline.

Produce a byte-faithful schema dump using the database's own tool (pg_dump -s).

The most complete/runnable schema export (handles sequences, identity, partitioning, etc.) but REQUIRES the pg_dump binary on the machine running this server. Returns the DDL inline (or writes {database}_schema_{UTC}.sql when output_dir is set). If pg_dump isn't installed it returns {status: "pg_dump_not_found", message}: offer to install pg_dump for the user (see the faithful_schema_export prompt), then retry — or use get_database_schema(format="sql") which needs no extra tools.

Returns meta, status, database, generated_utc and ddl (or saved_to), or meta, status and message when pg_dump is missing or fails.

Fetch up to N rows of a table to learn its data shape.

Use it to see what real values look like before writing a query: no filter, no ordering. To fetch specific rows use execute_read_query with a WHERE clause; for more than 1000 rows use open_query_cursor and fetch_rows; to find which table holds a value use search_value. A table that does not exist is an error.

Returns meta and rows, one object per row keyed by column name, in no guaranteed order. n defaults to 10 and the answer holds at most 1000 rows: a larger n is clamped to 1000. meta.truncated is true only when n was over 1000 and was clamped; it reports that clamp, not whether the table holds more rows.

Rows arrive on the text channel only, inside the untrusted-data banner: this tool emits no structuredContent. Values render as on execute_read_query (bytea as \x hex text).

Find columns by name across all tables of one database (fuzzy, case-insensitive).

e.g. pattern "email" matches user_email, EMAIL_ADDRESS. Use this to locate where a concept lives before querying. It matches column NAMES only — to find where a data value appears use search_value; to find a table by name use list_tables. limit returns at most that many rows — set it when a broad pattern would otherwise match half the database.

Returns meta and columns, one item per matching column with schema, table, column, type and nullable; meta.truncated is true when limit cut the list.

Find WHERE a value appears across tables (fuzzy, case-insensitive substring).

Returns meta, results and truncated: one result per column containing the value, with schema, table, column, matches (a count) and samples. For speed on large databases, first narrow with list_tables/find_columns and pass a tables shortlist; otherwise it scans all non-system tables (bounded, may return partial results flagged truncated, which meta.truncated repeats).

Matches arrive on the text channel only, inside the untrusted-data banner: this tool emits no structuredContent.

Run a read-only SELECT query (enforced as a read-only transaction).

Know the schema before you query: if the exact table and column names are not already in this conversation, call get_table_schema (or list_tables / find_columns) first instead of guessing — a wrong name costs a failed round-trip. Don't re-fetch a schema you already have.

ALWAYS pass user-supplied values via params with $1/$2/... placeholders in the SQL (real driver bind parameters — no quoting/injection pitfalls), not by pasting them into the SQL string. Optional timeout_ms cancels an overrunning query.

Rows arrive on the text channel only, inside the untrusted-data banner: this tool emits no structuredContent.

Returns meta, columns and rows. There is no row cap: every row comes back in one answer, so for a large result use open_query_cursor and fetch_rows instead. A SELECT with no columns answers one empty object per row.

Result shape: columns lists every column the statement returned, but each row is keyed by name, so a repeated name (SELECT 1 AS a, 2 AS a) keeps only its last value: alias the columns to keep both. Rendering follows the server's column type: bytea arrives as \x hex text, a "char" column (relkind, contype, prokind, ...) as its character (hex when the byte is not valid UTF-8), and a "char" inside an anonymous ROW(...) as hex because the row description says only record. An array of a domain over "char" also reads as hex, because that array has its own type.

Run an INSERT/UPDATE/DELETE/DDL statement on a write-mode database.

Know the schema before you write: if the exact table and column names are not already in this conversation, call get_table_schema first instead of guessing — a wrong name wastes a whole dry-run round-trip. Don't re-fetch a schema you already have.

SAFETY — the server enforces this flow; you cannot skip it silently:

1. Call with dry_run=true (the default): the statement executes inside a transaction and is ALWAYS rolled back, returning its would-be rows_affected, or the RETURNING rows. This records a preview grant for this exact statement. RETURNING values from a dry-run are rolled back and are not the values the commit will produce (sequences advance, so generated ids differ): never quote a preview id as the real one.

2. Show the user the exact SQL and the dry-run result; ask for permission (not needed if the database has yolo enabled).

3. Call again with dry_run=false (and user_consent=true unless yolo) to commit. Commits without a prior dry-run of the identical statement are REJECTED. The preview grant expires 10 minutes after the dry-run and is consumed by the commit ATTEMPT it authorizes — including a commit that FAILS, which may still have applied server-side, so you MUST dry-run again before retrying. Running the same statement twice means previewing it twice. Pass skip_dry_run=true ONLY if the user explicitly asked to skip the preview.

Pass values via params ($1/$2/... placeholders), not pasted into the SQL.

Returns meta and rows_affected, or columns and rows for a RETURNING statement; a dry-run also carries dry_run and rolled_back.

Rows arrive on the text channel only, inside the untrusted-data banner: this tool emits no structuredContent.

Result shape: columns lists every column RETURNING named, but each row is keyed by name, so a repeated name (RETURNING id, id) keeps only its last value: alias the columns to keep both. Rendering follows the server's column type: bytea arrives as \x hex text, a "char" column (relkind, contype, prokind, ...) as its character (hex when the byte is not valid UTF-8), and a "char" inside an anonymous ROW(...) as hex because the row description says only record. An array of a domain over "char" also reads as hex, because that array has its own type. An error saying the statement ran but its rows could not be decoded means a commit is to be treated as applied: check with a read before running it again.

Show the execution plan for a read-only query (EXPLAIN; optionally ANALYZE).

Use to confirm index usage or diagnose a slow query; to see what is indexed at all, use get_table_schema with include_indexes=true. analyze=true actually runs the (read-only, validated) query to collect real timings and buffer stats, so it takes as long as the query itself: avoid it on a query you already know is very slow, and it never changes data.

EXPLAIN the query you will ACTUALLY run: a plan for bound parameters can differ from the plan for the same SQL with the values pasted in. Pass params with the $1/$2/... placeholders exactly as you would to execute_read_query (real driver binds), instead of rewriting the query with literals just to explain it. params composes with analyze=true.

Returns meta and plan, the plan's lines in order.

Cancel the statement running in server backend pid (find pids via show_activity).

Use for a stuck or runaway statement. To cap your own query's run time instead, pass timeout_ms to execute_read_query or execute_write_query.

Returns meta, pid and cancelled. Cancels the statement only — the session survives, and the cancelled statement's uncommitted work is rolled back. The request is sent at once; the statement stops at its next interrupt check, usually within moments. cancelled=false means the pid doesn't exist or you lack permission (same database user required).

Open a server-side cursor over a read-only query for batched fetching.

Use for results too large for one execute_read_query response (that tool has no row cap). Then call fetch_rows with the cursor_id until exhausted is true, and close_cursor if you stop early.

Returns meta, cursor_id (for fetch_rows/close_cursor) and database. The cursor pins one read-only connection until closed (auto-reaped after 15 idle minutes). At most 5 cursors may be open: opening a sixth is an error, so close the ones you no longer need.

Fetch the next N rows from an open cursor (see open_query_cursor).

Returns meta, rows, row_count, exhausted and cursor_closed; meta.database is null, since a cursor_id names no database. The cursor closes itself once fully drained, and also when the read fails: the error is raised and the cursor_id stops working, so re-open the query to read again. Fetch one batch at a time: a call made while another is running on the same cursor is refused, and the cursor and the running call carry on.

Rows arrive on the text channel only, inside the untrusted-data banner: this tool emits no structuredContent. Values render as on execute_read_query (bytea as \x hex text).

Close an open cursor and release its database connection. Idempotent.

Call it when you stop reading a cursor before fetch_rows reports exhausted: a drained or failed cursor closes itself, and an idle one is reaped after 15 minutes, but an open one holds a connection and one of the 5 cursor slots until then. It never stops a running statement — use cancel_query for that.

Returns meta, cursor_id, closed and was_open (false when the cursor was already closed or never existed).

Get the faithful SQL definition of a non-table object by name.

For a table's columns and keys use get_table_schema; for the whole schema as a script use get_database_schema(format="sql").

Covers views (and materialized views), functions/procedures, triggers, sequences, and indexes — produced by the database's own pg_get_*def functions. name may be schema-qualified ("public.my_view"); all matches are returned (same name in several schemas, overloaded functions).

Returns meta, object_type, name and matches, each with its schema, name, kind and definition; no match is an error.

Compare the schemas of two configured databases (tables, columns, PK/FK).

Read-only. Reports tables only in one side, and per-table column/type/default/key differences. Use to verify a migrated copy matches its source of truth; for one database's schema on its own use get_database_schema. An unknown name is an error listing the configured names.

Returns meta, database_a, database_b, only_in_a, only_in_b, changed_tables and identical; meta.database is null, since two are compared.

Find sequences lagging behind their column's max value (stale after migrations).

A behind: true sequence would hand out an id that already exists — fix with setval(). Run this after any bulk copy or logical-replication migration. By default only the problem sequences are listed, with total_sequences reporting how many were checked and skipped listing the ones that could not be probed — so behind_count: 0 means "all clear" only when skipped_count is 0. A skipped entry's reason is no_privilege (grant USAGE on the schema and SELECT on the sequence and its table) or probe_failed (the owning column is not numeric or the sequence could not be read). Pass behind_only=false for the full census; on a large schema that is one row per sequence (hundreds), so ask for it only when you need every sequence's state.

Returns meta, database, sequences, behind_count, total_sequences, skipped and skipped_count.

Approximate row counts and disk/index sizes per table, largest first.

Read-only. Uses the database's own statistics — fast, no table scans — so counts are as fresh as the last ANALYZE or autovacuum run; for an exact count run SELECT count(*) with execute_read_query. Useful for planning migration copy order and spotting anomalies; for columns and keys use get_table_schema. One row per table, so ask the narrower question instead of filtering afterwards: table for one table, min_size_bytes to skip anything smaller, limit for the top N.

Returns meta, database and tables, one item per table with schema, table, approx_rows, table_bytes, index_bytes and total_bytes, plus truncated when limit is set (true when more tables matched); meta.truncated repeats it, and is false without limit.

Show current server activity: pid, state, wait events, query/transaction age.

Sanitized by default — no user names, client addresses, or query text (pass include_query=true for query text cut to 300 characters). Answers "what is holding connections"; pair with cancel_query(pid) to kill a stuck statement.

Returns meta, database and activity, one item per server backend.

Enable/disable yolo (skip the write-consent prompt) for one database, persisted.

Call it ONLY when the user explicitly asks to turn yolo on or off — never to get past a consent prompt yourself. It is saved in connections.json, so it lasts across sessions and applies to every client using that file, and each flip is recorded in the audit log. On a read-mode database the flag is stored but has no effect: yolo can never make a read database writable, and on a write database the dry-run preview still applies.

Returns meta, database, yolo and persisted, plus audit_recorded and warning when the audit line could not be written.

A call cancelled while the write was in progress may still have been applied; list_databases shows the stored value. A result with audit_recorded: false means the flip persisted but no audit line was written.

Test connectivity for one database (or all) — returns OK or a sanitized cause.

Opens a read-only connection and closes it again; it changes nothing. Use it when a call fails with a connection error, or after starting a tunnel. When it says UNREACHABLE and the reason is unclear, run doctor for a full setup diagnosis.

Returns meta and results, one item per database with database and status (OK or UNREACHABLE; an unreachable one adds category and detail). meta.database is null when every database was checked. Reports active_port when the database answered on a fallback port — doubles as a live re-probe for tunneled connections.

Diagnose the whole setup, not just connectivity — use when something is misbehaving and check_database alone doesn't explain why.

Runs every diagnostic: stale running server processes, newer PyPI release, connections.json key typos/types, secrets exposure (permissions, git), MCP client entries pointing at dead paths, and per-database connectivity with a credential-free fallback-port identity probe.

Returns meta and findings, each with check, status (ok|warn|fail|skipped), detail and suggested_action, where suggested_action is machine-actionable: reconnect_client, upgrade_package, swap_primary_port, fix_permissions, fix_config, repair_client_config, fix_connection, install_doctor_extra, run_setup, report_bug, or none — every finding that states a remedy names one. Fix what you can; report the rest to the user verbatim. Output is sanitized — never contains DSNs, hosts, or credentials. offline=true skips the PyPI lookup.