run_select

How it works

• The SQL is parsed with Postgres's own parser (pg_query). Anything other than a single SELECT or WITH is refused before it reaches the database, and the connection itself is read-only.
• Returns 50 rows by default, up to the profile's max_rows (500 unless set). has_more says when there are more.
• Runs under a statement timeout (30 seconds unless the profile sets statement_timeout_ms). timeout_ms can lower it, never raise it.
• Columns that look like personal data or secrets come back as <redacted>, and tables in deny_tables are refused.
• Pass values through params ($1, $2, …) rather than pasting them into the SQL.

Parameters

sqlstringrequired

A single SELECT or WITH statement, schema-qualify table names where possible.

connectionIdstring

Optional connection profile override — does not change session context.

countboolean

When true and has_more is true, also return total_count. Runs the query a second time, so only ask when the total matters.

databasestring

Database to use instead of the current one, on connectionId or the active connection.

formatstring

Output format: "compact" (default columnar), "json", "markdown", or "csv".

limitnumber

Maximum rows to return. Defaults to 50; capped by profile max_rows.

paramsarray

Bound parameters for $1, $2, … in `sql`. JSON values: string, number, boolean, or null.

resolve_fksboolean

When true, add __resolved suffix columns for foreign-key IDs in the result.

timeout_msnumber

Per-query statement timeout in milliseconds; capped by profile statement_timeout_ms.

What your assistant reads

The description nexql-mcp sends with the tool. It's how the assistant decides when to use it.

Run a read-only SELECT or WITH query. DML/DDL are rejected. Supports parameterized execution via `params` ($1, $2, …). Returns up to 50 rows by default; has_more says whether more exist, and total_count is included when the whole result fits (or with count: true).