@yawlabs/postgres-mcp 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-14
+
+### Added
+- New `pg_readonly` tool. Always runs inside `BEGIN READ ONLY` regardless of
+  `ALLOW_WRITES`, so postgres itself rejects any write attempt. The point is
+  to give hosts that gate tools individually (Claude Code permissions,
+  mcp.hosting per-tool toggles) a stable always-safe target to auto-allow,
+  independent of how the server is configured. Same input shape as `pg_query`
+  (`sql` + `params`).
+- New "Configuring access" README section walking through the recommended
+  least-privileged-role posture: `CREATE ROLE mcp_reader ... GRANT
+  pg_read_all_data` for read-only agents, and a `mcp_writer` example with
+  table-level grants for scoped writes. The role is the primary access
+  control; `ALLOW_WRITES` is positioned as secondary belt-and-braces.
+
+### Changed
+- `pg_query` description leads with role-based access control. `ALLOW_WRITES`
+  is now framed as a secondary gate, with the role in `DATABASE_URL` as the
+  authoritative one. No behavior change.
+- README "Why this one?" read-only bullet expanded: `pg_query` continues to
+  default to read-only via `BEGIN READ ONLY`, and `pg_readonly` is the new
+  unconditional read tool. Configuration table and troubleshooting entry
+  for `ALLOW_WRITES` updated to point at the Configuring access section.
+
 ## [0.5.3] - 2026-05-14
 
 ### Security
@@ -322,7 +346,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   writes executed by `EXPLAIN ANALYZE`. Previously the write ran inside a
   `BEGIN; ... COMMIT` transaction, so `pg_explain { analyze: true, sql:
   "INSERT ..." }` would actually insert the row. Now writes run inside a
-  `BEGIN; ... ROLLBACK` transaction — the plan (with real row counts and
+  `BEGIN; ... ROLLBACK` transaction - the plan (with real row counts and
   timing) comes back but the mutation is rolled back. This matches the user
   expectation when asking for a plan, and the tool description has been
   updated to reflect it.
@@ -354,7 +378,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `pg_list_roles` with `includeSystem: false` (the default) now actually
   excludes built-in `pg_*` roles. The previous `LIKE 'pg\_%' ESCAPE '\\'`
   filter ended up as SQL `ESCAPE '\\'` (two backslashes), which Postgres
-  rejects since `ESCAPE` requires a single character — so the whole filter
+  rejects since `ESCAPE` requires a single character - so the whole filter
   was silently being dropped. Replaced with `starts_with(rolname, 'pg_')`.
 - `pg_describe_table` foreign-key `columns` and `foreign_columns` are now
   proper JSON arrays. They were previously returned as the raw postgres
@@ -378,11 +402,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.3.0] - 2026-04-22
 
 ### Added
-- `pg_list_views` — list views and materialized views with SQL definitions.
-- `pg_list_functions` — list functions, procedures, and aggregates with signatures.
-- `pg_list_extensions` — list installed extensions (pgvector, postgis, etc.) with versions.
-- `pg_search_columns` — find columns by name pattern across all user schemas.
-- `pg_top_queries` — top N queries by total/mean execution time from
+- `pg_list_views` - list views and materialized views with SQL definitions.
+- `pg_list_functions` - list functions, procedures, and aggregates with signatures.
+- `pg_list_extensions` - list installed extensions (pgvector, postgis, etc.) with versions.
+- `pg_search_columns` - find columns by name pattern across all user schemas.
+- `pg_top_queries` - top N queries by total/mean execution time from
   `pg_stat_statements`. Detects extension version and picks the right column
   names (v1.8+ uses `total_exec_time`, older uses `total_time`). Returns clear
   setup instructions if the extension is not installed.
@@ -404,23 +428,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   tool against a real Postgres instance. Gated on `POSTGRES_MCP_INTEGRATION=1`
   so local `npm test` stays fast with no DB required. CI runs it on Linux via
   a `postgres:16` service container with `pg_stat_statements` preloaded.
-- `pg_inspect_locks` — show current blocking locks (blocked PID, blocker PID,
+- `pg_inspect_locks` - show current blocking locks (blocked PID, blocker PID,
   relation, lock type, both queries). First tool to reach for when a session
   hangs or the app feels stuck.
-- `pg_list_roles` — database roles with login/superuser/createdb/createrole
+- `pg_list_roles` - database roles with login/superuser/createdb/createrole
   flags and inherited group memberships.
-- `pg_table_privileges` — who has SELECT/INSERT/UPDATE/DELETE/etc. on a table,
+- `pg_table_privileges` - who has SELECT/INSERT/UPDATE/DELETE/etc. on a table,
   or on all tables in a schema. Useful for pre-migration audits.
-- `pg_seq_scan_tables` — tables with heavy sequential scans relative to index
+- `pg_seq_scan_tables` - tables with heavy sequential scans relative to index
   scans. Missing-index candidates.
-- `pg_unused_indexes` — non-unique, non-primary indexes with low/zero scan
+- `pg_unused_indexes` - non-unique, non-primary indexes with low/zero scan
   counts. Drop candidates (each unused index costs write amplification).
-- `pg_kill` — cancel a running query or terminate a backend by PID. Requires
+- `pg_kill` - cancel a running query or terminate a backend by PID. Requires
   `ALLOW_WRITES=1` since it changes session state. Distinguishes `cancel`
   (SIGINT-equivalent, graceful) from `terminate` (SIGTERM, forceful).
-- `pg_table_bloat` — estimate dead tuples and vacuum-candidate tables from
+- `pg_table_bloat` - estimate dead tuples and vacuum-candidate tables from
   `pg_stat_user_tables`. No extensions required.
-- `pg_replication_status` — replication slots, connected replicas with lag,
+- `pg_replication_status` - replication slots, connected replicas with lag,
   and current WAL position. Returns empty arrays on a standalone DB rather
   than erroring, so it's safe to call unconditionally.
 - New "What can an agent do with this?" README section with concrete example
@@ -452,12 +476,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Initial release.
 
 ### Added
-- `pg_query` — run SQL with read-only-by-default safety. Writes opt in via `ALLOW_WRITES=1`.
-- `pg_list_schemas` — list non-system schemas.
-- `pg_list_tables` — list tables (and optionally views) with estimated row counts.
-- `pg_describe_table` — columns, PK, FKs, indexes.
-- `pg_explain` — `EXPLAIN` / `EXPLAIN ANALYZE` with text or JSON output.
-- `pg_health` — server version, db size, connections, active queries, table count.
+- `pg_query` - run SQL with read-only-by-default safety. Writes opt in via `ALLOW_WRITES=1`.
+- `pg_list_schemas` - list non-system schemas.
+- `pg_list_tables` - list tables (and optionally views) with estimated row counts.
+- `pg_describe_table` - columns, PK, FKs, indexes.
+- `pg_explain` - `EXPLAIN` / `EXPLAIN ANALYZE` with text or JSON output.
+- `pg_health` - server version, db size, connections, active queries, table count.
 - Single-file bundled distribution (zero runtime deps) for fast `npx` cold starts.
 - Result row truncation at `POSTGRES_MAX_ROWS` (default 1000).
 - Parameterized queries via `params` on `pg_query` and `pg_explain`.

package/README.md

@@ -3,37 +3,42 @@
 [![npm version](https://img.shields.io/npm/v/@yawlabs/postgres-mcp)](https://www.npmjs.com/package/@yawlabs/postgres-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-**Query a PostgreSQL database from Claude Code, Cursor, and any MCP client.** Read-only by default — writes opt in via a single env var — so an agent can't silently drop your tables.
+**Query a PostgreSQL database from Claude Code, Cursor, and any MCP client.** Read-only by default - writes opt in via a single env var - so an agent can't silently drop your tables.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
+[![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=Postgres&command=npx&args=-y%2C%40yawlabs%2Fpostgres-mcp&description=Query%20PostgreSQL%20-%20schema%20introspection%2C%20EXPLAIN%20plans%2C%20health%20diagnostics%2C%20read-only%20by%20default&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fpostgres-mcp)
+
+One click adds this to your [mcp.hosting](https://mcp.hosting) account so it syncs to every MCP client you use. Or install manually below.
+
 ## Backstory
 
-Anthropic's reference Postgres MCP server, `@modelcontextprotocol/server-postgres`, was [archived in May 2025](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/postgres) and [marked deprecated on npm](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres) in July 2025. Anthropic has not shipped a replacement. Despite the deprecation, the last published version (v0.6.2) is still pulled ~20,000 times per week — a lot of agents are pointed at an unmaintained package.
+Anthropic's reference Postgres MCP server, `@modelcontextprotocol/server-postgres`, was [archived in May 2025](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/postgres) and [marked deprecated on npm](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres) in July 2025. Anthropic has not shipped a replacement. Despite the deprecation, the last published version (v0.6.2) is still pulled ~20,000 times per week - a lot of agents are pointed at an unmaintained package.
 
 That unmaintained package also has a known, [publicly documented stacked-query SQL injection](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (Datadog Security Labs) that bypasses its `BEGIN READ ONLY` wrapper with input like `COMMIT; DROP SCHEMA public CASCADE;`. It has never been patched at npm.
 
 A handful of community forks have appeared, but each fills a narrow slice:
 
-- [`@zeddotdev/postgres-context-server`](https://www.npmjs.com/package/@zeddotdev/postgres-context-server) — Zed's fork, primarily a security patch on the original shape.
-- **Postgres MCP Pro** (Crystal DBA) — focused on index tuning and hypothetical-index / buffer-cache diagnostics.
-- **AWS Labs Postgres MCP** — tied to Aurora / RDS Data API + Secrets Manager.
+- [`@zeddotdev/postgres-context-server`](https://www.npmjs.com/package/@zeddotdev/postgres-context-server) - Zed's fork, primarily a security patch on the original shape.
+- **Postgres MCP Pro** (Crystal DBA) - focused on index tuning and hypothetical-index / buffer-cache diagnostics.
+- **AWS Labs Postgres MCP** - tied to Aurora / RDS Data API + Secrets Manager.
 
 None of them position themselves as a general-purpose daily driver you'd hand to Claude Code or Cursor against an arbitrary Postgres: modern introspection, perf helpers, role/privilege awareness, and a write-safety posture out of the box. That's the gap `@yawlabs/postgres-mcp` fills.
 
 ## Why this one?
 
-- **Read-only by default** — user SQL runs in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes. Opt in with `ALLOW_WRITES=1`.
-- **Extended query protocol for all user SQL** — `pg_query` sends user input with `queryMode: 'extended'`, which restricts each request to a single statement. This closes the [stacked-query injection class](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (`COMMIT; DROP SCHEMA x CASCADE;`) that defeated the reference server's `BEGIN READ ONLY` wrapper. Integration test asserts the rejection.
-- **Parameterized queries** — `pg_query` takes a `params` array for `$1`, `$2`, etc. No string-interpolated SQL in our code path.
-- **Written from scratch, actively maintained** — not a fork of the deprecated code. Unit + integration tests (`npm test`, `npm run test:integration`) run against a real Postgres; releases cut via `release.sh`.
-- **Schema introspection built in** — `pg_list_schemas`, `pg_list_tables`, `pg_describe_table` return columns, primary keys, foreign keys, and indexes without the agent having to remember `pg_catalog` joins.
-- **`EXPLAIN` as a first-class tool** — text or JSON format, with optional `ANALYZE`. ANALYZE for non-SELECT statements requires `ALLOW_WRITES=1` and always rolls back, so the plan is real but the write doesn't persist.
-- **Perf diagnostics the deprecated server never had** — `pg_top_queries` (from `pg_stat_statements`), `pg_seq_scan_tables`, `pg_unused_indexes`, `pg_table_bloat`, `pg_inspect_locks`, `pg_replication_status`. Answer "why is this slow?" in one tool call.
-- **Health snapshot** — `pg_health` returns version, db size, connection counts, and the 10 longest-running active queries in one call.
-- **Role and privilege awareness** — `pg_list_roles` and `pg_table_privileges` for the common "who can touch what?" questions.
-- **Instant startup** — ships as a single bundled file with zero runtime dependencies. No multi-minute `node_modules` install on every `npx` cold start.
-- **Result truncation** — large result sets are capped at `POSTGRES_MAX_ROWS` (default 1000) with a `truncated: true` flag, so a stray `SELECT * FROM events` doesn't blow out the model context.
+- **Read-only by default, with an unconditional read-only tool too** - `pg_query` runs user SQL in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes; opt in to writes with `ALLOW_WRITES=1`. `pg_readonly` is a separate tool that stays read-only regardless of `ALLOW_WRITES`, so hosts that gate tools individually (Claude Code permissions, mcp.hosting) can safely auto-allow it.
+- **Role-based access as the primary control** - the recommended posture is to use a least-privileged postgres role in `DATABASE_URL` (e.g. one with `GRANT pg_read_all_data`); postgres itself then enforces the boundary, no env var needed. See [Configuring access](#configuring-access).
+- **Extended query protocol for all user SQL** - `pg_query` sends user input with `queryMode: 'extended'`, which restricts each request to a single statement. This closes the [stacked-query injection class](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (`COMMIT; DROP SCHEMA x CASCADE;`) that defeated the reference server's `BEGIN READ ONLY` wrapper. Integration test asserts the rejection.
+- **Parameterized queries** - `pg_query` takes a `params` array for `$1`, `$2`, etc. No string-interpolated SQL in our code path.
+- **Written from scratch, actively maintained** - not a fork of the deprecated code. Unit + integration tests (`npm test`, `npm run test:integration`) run against a real Postgres; releases cut via `release.sh`.
+- **Schema introspection built in** - `pg_list_schemas`, `pg_list_tables`, `pg_describe_table` return columns, primary keys, foreign keys, and indexes without the agent having to remember `pg_catalog` joins.
+- **`EXPLAIN` as a first-class tool** - text or JSON format, with optional `ANALYZE`. ANALYZE for non-SELECT statements requires `ALLOW_WRITES=1` and always rolls back, so the plan is real but the write doesn't persist.
+- **Perf diagnostics the deprecated server never had** - `pg_top_queries` (from `pg_stat_statements`), `pg_seq_scan_tables`, `pg_unused_indexes`, `pg_table_bloat`, `pg_inspect_locks`, `pg_replication_status`. Answer "why is this slow?" in one tool call.
+- **Health snapshot** - `pg_health` returns version, db size, connection counts, and the 10 longest-running active queries in one call.
+- **Role and privilege awareness** - `pg_list_roles` and `pg_table_privileges` for the common "who can touch what?" questions.
+- **Instant startup** - ships as a single bundled file with zero runtime dependencies. No multi-minute `node_modules` install on every `npx` cold start.
+- **Result truncation** - large result sets are capped at `POSTGRES_MAX_ROWS` (default 1000) with a `truncated: true` flag, so a stray `SELECT * FROM events` doesn't blow out the model context.
 
 ## Quick start
 
@@ -88,7 +93,52 @@ Read-only is the default. If you want the agent to be able to `INSERT`, `UPDATE`
 }
 ```
 
-Prefer scoping this to dev/test databases — for production, leave writes off and use migration tools out-of-band.
+Prefer scoping this to dev/test databases - for production, leave writes off and use migration tools out-of-band.
+
+## Configuring access
+
+The role in `DATABASE_URL` is the primary access control. Postgres has had a battle-tested permission system for 30 years; lean on it instead of relying on `ALLOW_WRITES` alone. A least-privileged role makes writes server-rejected no matter what tools or env vars are configured.
+
+**Read-only agent (recommended default):**
+
+```sql
+CREATE ROLE mcp_reader LOGIN PASSWORD 'change-me';
+GRANT CONNECT ON DATABASE your_db TO mcp_reader;
+GRANT USAGE ON SCHEMA public TO mcp_reader;
+GRANT pg_read_all_data TO mcp_reader;
+```
+
+Point `DATABASE_URL` at `mcp_reader`. Postgres rejects every write, every DDL, every privilege change - regardless of `ALLOW_WRITES`. No app-level guard to bypass; the database is the boundary.
+
+**Scoped write agent (dev/test or narrow production use):**
+
+```sql
+CREATE ROLE mcp_writer LOGIN PASSWORD 'change-me';
+GRANT CONNECT ON DATABASE your_db TO mcp_writer;
+GRANT USAGE ON SCHEMA public TO mcp_writer;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO mcp_writer;
+GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_writer;
+-- DDL not granted -- the agent can change data but not schema.
+```
+
+Set `ALLOW_WRITES=1` so `pg_query` will issue writes, and rely on the role to keep the agent away from DDL and other schemas.
+
+**Per-tool gating in the host:**
+
+Tools split cleanly across two authority classes:
+
+- **Auto-allow:** `pg_readonly` (server-side `BEGIN READ ONLY`, unconditional), plus the introspection tools (`pg_list_*`, `pg_describe_table`, `pg_search_columns`, `pg_explain` without ANALYZE-of-write, `pg_health`, `pg_inspect_locks`, `pg_table_bloat`, `pg_unused_indexes`, `pg_top_queries`, `pg_replication_status`, `pg_advisor`, `pg_table_privileges`, `pg_list_roles`).
+- **Always prompt:** `pg_query` (can write when the role allows it), `pg_kill` (changes session state).
+
+Claude Code's `permissions` block and mcp.hosting's per-tool toggle both honor this split.
+
+**`ALLOW_WRITES` as defense-in-depth:**
+
+`ALLOW_WRITES` is a secondary belt-and-braces gate. Useful when:
+- You're on a managed database where creating a second role is awkward (some Supabase/Neon plans).
+- You want a single role that can write, but want the MCP server to refuse writes anyway during normal operation.
+
+Otherwise, configure the role and stop relying on `ALLOW_WRITES`.
 
 ## What can an agent do with this?
 
@@ -103,7 +153,7 @@ Once connected, the agent picks tools automatically based on what you ask. A few
 
 The bigger leverage is multi-tool reasoning. A few real workflows:
 
-- **Unstick a hung app.** `pg_inspect_locks` returns blocked PID + blocking PID + the offending query, then `pg_kill` (`ALLOW_WRITES=1` required) cancels the blocker. The agent can run both in one turn — it's the fastest path from "the app is frozen" to "back up."
+- **Unstick a hung app.** `pg_inspect_locks` returns blocked PID + blocking PID + the offending query, then `pg_kill` (`ALLOW_WRITES=1` required) cancels the blocker. The agent can run both in one turn - it's the fastest path from "the app is frozen" to "back up."
 - **Chase a slow page.** `pg_top_queries` ranks the worst queries, `pg_explain` with `analyze: true` shows the plan for the top hit, `pg_seq_scan_tables` and `pg_unused_indexes` say whether the answer is "add an index here" or "drop a dead one there."
 - **Oncall triage.** `pg_health` checks connectivity + active-query count + database size; `pg_inspect_locks` and `pg_replication_status` confirm whether contention or replication lag is in play before paging the on-call DBA.
 
@@ -111,7 +161,8 @@ The bigger leverage is multi-tool reasoning. A few real workflows:
 
 | Tool | Description |
 |------|-------------|
-| `pg_query` | Run a SQL query. Read-only by default; writes require `ALLOW_WRITES=1`. Supports parameterized queries via `params`. Result fields include `dataTypeName` (e.g. `int4`, `jsonb`) alongside `dataTypeID`. |
+| `pg_readonly` | Run a SQL statement guaranteed read-only - always inside `BEGIN READ ONLY`, regardless of `ALLOW_WRITES`. The recommended tool for read access; safe for hosts to auto-allow. |
+| `pg_query` | Run a SQL query. Writes gated by the role in `DATABASE_URL` first, `ALLOW_WRITES` second. Supports parameterized queries via `params`. Result fields include `dataTypeName` (e.g. `int4`, `jsonb`) alongside `dataTypeID`. |
 | `pg_list_schemas` | List non-system schemas. |
 | `pg_list_tables` | List tables (and optionally views) in a schema with estimated row counts. Paginated via `limit`/`offset`. |
 | `pg_describe_table` | Kind, columns, PK, outgoing FKs, incoming FKs (`referenced_by`), CHECK / UNIQUE / EXCLUDE constraints, indexes, and partition parent/children for a relation. |
@@ -122,12 +173,12 @@ The bigger leverage is multi-tool reasoning. A few real workflows:
 | `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. Optional `hypothetical_indexes` (requires the [HypoPG](https://github.com/HypoPG/hypopg) extension) lets you ask "what would the plan be with these indexes?" without creating them on disk. |
 | `pg_health` | Server version, database size, connection count, active queries, table count. |
 | `pg_top_queries` | Top N queries by total/mean execution time. Requires the `pg_stat_statements` extension. |
-| `pg_seq_scan_tables` | Tables with heavy sequential scans — missing-index candidates. |
-| `pg_unused_indexes` | Non-unique, non-primary indexes with low scan counts — drop candidates. |
+| `pg_seq_scan_tables` | Tables with heavy sequential scans - missing-index candidates. |
+| `pg_unused_indexes` | Non-unique, non-primary indexes with low scan counts - drop candidates. |
 | `pg_inspect_locks` | Who is blocking whom right now (blocked PID, blocker PID, lock type, queries). |
 | `pg_list_roles` | Database roles with login/superuser/createdb flags and group memberships. |
 | `pg_table_privileges` | Who has SELECT/INSERT/UPDATE/DELETE/etc. on a table or whole schema. |
-| `pg_table_bloat` | Tables with high dead-tuple ratios — VACUUM candidates. |
+| `pg_table_bloat` | Tables with high dead-tuple ratios - VACUUM candidates. |
 | `pg_replication_status` | Replication slots, connected replicas, and current WAL position. |
 | `pg_advisor` | Rolled-up DBA lints in one call: sequence-exhaustion candidates, tables without a primary key, and (configurable) public tables with RLS disabled. The "what should I be looking at?" starting point. |
 | `pg_kill` | Cancel a running query or terminate a backend connection. Requires `ALLOW_WRITES=1`. |
@@ -139,7 +190,7 @@ All env vars are read from the MCP server's environment:
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `DATABASE_URL` | (required) | PostgreSQL connection string. |
-| `ALLOW_WRITES` | unset | Set to `1` or `true` to allow DML/DDL via `pg_query` and `pg_explain` ANALYZE of writes. |
+| `ALLOW_WRITES` | unset | Secondary write gate for `pg_query` and `pg_explain` ANALYZE-of-writes. Set to `1` or `true` to lift the `BEGIN READ ONLY` wrapper. The role in `DATABASE_URL` is the primary control - see [Configuring access](#configuring-access). Does not affect `pg_readonly`, which is unconditional. |
 | `POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-statement timeout. |
 | `POSTGRES_CONNECTION_TIMEOUT_MS` | `10000` | TCP connect timeout. Without this, a dead host hangs until the OS gives up (~2 minutes). |
 | `POSTGRES_MAX_ROWS` | `1000` | Cap on rows returned by `pg_query`. |
@@ -171,19 +222,19 @@ This disables certificate chain verification only -- the TCP connection is still
 
 ## Troubleshooting
 
-**`DATABASE_URL is not set`** — Your MCP client is launching the server without the env var. On Windows especially, env vars set in bash / PowerShell profiles are not inherited by MCP servers launched via `cmd`. Put `DATABASE_URL` directly in the `env` block of `.mcp.json`.
+**`DATABASE_URL is not set`** - Your MCP client is launching the server without the env var. On Windows especially, env vars set in bash / PowerShell profiles are not inherited by MCP servers launched via `cmd`. Put `DATABASE_URL` directly in the `env` block of `.mcp.json`.
 
-**`password authentication failed`** — Check the username, password, and that the user has `CONNECT` privilege on the database. URL-encode special characters in the password (`@` → `%40`, `#` → `%23`, `/` → `%2F`).
+**`password authentication failed`** - Check the username, password, and that the user has `CONNECT` privilege on the database. URL-encode special characters in the password (`@` → `%40`, `#` → `%23`, `/` → `%2F`).
 
-**`SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`** — The password in your connection string is empty or became `null` after URL decoding. Re-check your connection string.
+**`SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`** - The password in your connection string is empty or became `null` after URL decoding. Re-check your connection string.
 
-**`canceling statement due to statement timeout`** — A single query exceeded `POSTGRES_STATEMENT_TIMEOUT_MS` (default 30s). Increase it, narrow the query with `WHERE`, or add an index. This is working as designed -- the timeout exists so a runaway query cannot hang the agent.
+**`canceling statement due to statement timeout`** - A single query exceeded `POSTGRES_STATEMENT_TIMEOUT_MS` (default 30s). Increase it, narrow the query with `WHERE`, or add an index. This is working as designed -- the timeout exists so a runaway query cannot hang the agent.
 
-**`Write blocked: this server is in read-only mode`** — You asked the agent to write but `ALLOW_WRITES` is not set. Add `ALLOW_WRITES=1` to the `env` block of `.mcp.json` and restart your MCP client. Only do this for dev/test DBs.
+**`Write blocked: this server is in read-only mode`** - You asked the agent to write via `pg_query` but `ALLOW_WRITES` is not set. Either add `ALLOW_WRITES=1` to the `env` block of `.mcp.json` and restart your MCP client (dev/test DBs), or - cleaner for production - use a role with `INSERT/UPDATE/DELETE` grants in `DATABASE_URL` and keep `ALLOW_WRITES` unset. See [Configuring access](#configuring-access). Note that `pg_readonly` always rejects writes; if you want writes, the call has to go through `pg_query`.
 
-**Connection pool exhaustion with PgBouncer transaction mode or pglite-socket** — These backends don't support concurrent queries on a single connection. Set `POSTGRES_POOL_MAX=1` in the env block.
+**Connection pool exhaustion with PgBouncer transaction mode or pglite-socket** - These backends don't support concurrent queries on a single connection. Set `POSTGRES_POOL_MAX=1` in the env block.
 
-**First query is slow, subsequent queries are fast** — Expected. The pg driver lazily establishes the first connection; subsequent queries reuse the pool.
+**First query is slow, subsequent queries are fast** - Expected. The pg driver lazily establishes the first connection; subsequent queries reuse the pool.
 
 ## Development
 

package/dist/index.js

@@ -36350,7 +36350,7 @@ async function shutdown() {
 var adminTools = [
   {
     name: "pg_inspect_locks",
-    description: "Show current lock contention: which sessions are blocked and who is blocking them. Returns blocked PID, blocking PID, lock types, relation being contested, and the queries involved. Use this first when a tool call hangs or the app feels stuck \u2014 it's the fastest way to identify a long-held transaction holding a lock.",
+    description: "Show current lock contention: which sessions are blocked and who is blocking them. Returns blocked PID, blocking PID, lock types, relation being contested, and the queries involved. Use this first when a tool call hangs or the app feels stuck - it's the fastest way to identify a long-held transaction holding a lock.",
     annotations: {
       title: "Inspect blocking locks",
       readOnlyHint: true,
@@ -36469,7 +36469,7 @@ var adminTools = [
   },
   {
     name: "pg_kill",
-    description: "Cancel a running query (SIGINT-equivalent) or terminate a backend connection (SIGTERM-equivalent) by PID. Find the PID via `pg_health` active_queries or `pg_inspect_locks`. Requires ALLOW_WRITES=1 since this changes database session state. The role in DATABASE_URL must have permission \u2014 cancelling another user's query needs the `pg_signal_backend` role or superuser. Cancel is graceful; terminate is forceful.",
+    description: "Cancel a running query (SIGINT-equivalent) or terminate a backend connection (SIGTERM-equivalent) by PID. Find the PID via `pg_health` active_queries or `pg_inspect_locks`. Requires ALLOW_WRITES=1 since this changes database session state. The role in DATABASE_URL must have permission - cancelling another user's query needs the `pg_signal_backend` role or superuser. Cancel is graceful; terminate is forceful.",
     annotations: {
       title: "Cancel or terminate a backend",
       readOnlyHint: false,
@@ -36499,7 +36499,7 @@ var adminTools = [
           pid,
           mode,
           signaled,
-          note: signaled ? `Sent ${mode === "terminate" ? "SIGTERM" : "SIGINT"} to backend ${pid}.` : `Signal returned false \u2014 PID ${pid} may not exist, may already be gone, or the current role lacks permission.`
+          note: signaled ? `Sent ${mode === "terminate" ? "SIGTERM" : "SIGINT"} to backend ${pid}.` : `Signal returned false - PID ${pid} may not exist, may already be gone, or the current role lacks permission.`
         }
       };
     }
@@ -36654,7 +36654,7 @@ var adminTools = [
   },
   {
     name: "pg_table_bloat",
-    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM. Cheap \u2014 uses `pg_stat_user_tables`, no extensions required.",
+    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM. Cheap - uses `pg_stat_user_tables`, no extensions required.",
     annotations: {
       title: "Estimate table bloat",
       readOnlyHint: true,
@@ -36664,7 +36664,7 @@ var adminTools = [
     },
     inputSchema: external_exports.object({
       schema: external_exports.string().min(1).max(63).optional().describe("Limit to one schema. If omitted, all user schemas are included."),
-      minDeadRatio: external_exports.number().min(0).max(1).default(0.1).describe("Minimum dead-tuple fraction to include \u2014 dead / (live + dead). Default 0.1 = 10%."),
+      minDeadRatio: external_exports.number().min(0).max(1).default(0.1).describe("Minimum dead-tuple fraction to include - dead / (live + dead). Default 0.1 = 10%."),
       limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
     }),
     handler: async (input) => {
@@ -36755,7 +36755,7 @@ function buildHypopgHooks(indexes) {
 var explainTools = [
   {
     name: "pg_explain",
-    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE \u2014 for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement). Set `hypothetical_indexes` to a list of `{table, columns, using?}` to ask the planner 'what would the plan be if these indexes existed?' -- requires the HypoPG extension (`CREATE EXTENSION hypopg`). The hypothetical indexes are torn down at the end of the call, never touching real disk.",
+    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE - for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement). Set `hypothetical_indexes` to a list of `{table, columns, using?}` to ask the planner 'what would the plan be if these indexes existed?' -- requires the HypoPG extension (`CREATE EXTENSION hypopg`). The hypothetical indexes are torn down at the end of the call, never touching real disk.",
     annotations: {
       title: "Explain query plan",
       readOnlyHint: false,
@@ -36800,7 +36800,7 @@ var explainTools = [
         if (!check2.data?.[0]?.installed) {
           return {
             ok: false,
-            error: "hypothetical_indexes requires the HypoPG extension. Install with `CREATE EXTENSION hypopg;` (a superuser-equivalent role usually). HypoPG is read-only at the disk level \u2014 it lives entirely in shared memory."
+            error: "hypothetical_indexes requires the HypoPG extension. Install with `CREATE EXTENSION hypopg;` (a superuser-equivalent role usually). HypoPG is read-only at the disk level - it lives entirely in shared memory."
           };
         }
       }
@@ -36904,13 +36904,32 @@ var healthTools = [
 
 // src/tools/query.ts
 var queryTools = [
+  {
+    name: "pg_readonly",
+    description: "Run a SQL statement guaranteed read-only. Always executes inside a `BEGIN READ ONLY` transaction regardless of `ALLOW_WRITES`, so postgres itself rejects any write attempt. Use this whenever the goal is to read - SELECT, EXPLAIN, SHOW, VALUES, WITH ... SELECT, etc. Hosts that gate tools individually (Claude Code permissions, mcp.hosting) can safely auto-allow this one. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
+    annotations: {
+      title: "Run read-only SQL",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      sql: external_exports.string().min(1).max(1e6).describe("The SQL statement to execute. Hard cap of 1 MB."),
+      params: external_exports.array(paramValue).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL.")
+    }),
+    handler: async (input) => {
+      const { sql, params } = input;
+      return runReadOnly(sql, params ?? []);
+    }
+  },
   {
     name: "pg_query",
-    description: "Run a SQL query against the configured PostgreSQL database. Read-only by default (query runs in a READ ONLY transaction). Set ALLOW_WRITES=1 in the MCP server env to enable DML/DDL. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Dates and UUIDs can be passed as ISO strings. Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
+    description: "Run a SQL query against the configured PostgreSQL database. Writes are gated by the role in `DATABASE_URL` first and `ALLOW_WRITES` second: a role created with `GRANT pg_read_all_data` makes writes server-rejected regardless of `ALLOW_WRITES`, and is the recommended way to scope agent access. `ALLOW_WRITES=1` is a secondary belt-and-braces gate - useful for managed databases where creating a second role is awkward. For read-only access where you want the guarantee in the tool name, prefer `pg_readonly`. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Dates and UUIDs can be passed as ISO strings. Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
     annotations: {
       title: "Run SQL query",
       readOnlyHint: false,
-      // conditionally destructive based on ALLOW_WRITES
+      // conditionally destructive based on role + ALLOW_WRITES
       destructiveHint: true,
       idempotentHint: false,
       openWorldHint: true
@@ -36958,7 +36977,7 @@ var schemaTools = [
   },
   {
     name: "pg_list_tables",
-    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; approximate \u2014 0 until ANALYZE runs). Paginate via `limit`/`offset` on very large schemas.",
+    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; approximate - 0 until ANALYZE runs). Paginate via `limit`/`offset` on very large schemas.",
     annotations: {
       title: "List tables in a schema",
       readOnlyHint: true,
@@ -37413,7 +37432,7 @@ var statsTools = [
   },
   {
     name: "pg_seq_scan_tables",
-    description: "Tables with high sequential-scan counts relative to index scans \u2014 the first place to look for missing-index candidates. Returns seq_scans, idx_scans, live tuples, and the ratio. A high ratio on a large table usually means a query is reading the whole table where an index would suffice. Pair with `pg_top_queries` to find which query is doing it.",
+    description: "Tables with high sequential-scan counts relative to index scans - the first place to look for missing-index candidates. Returns seq_scans, idx_scans, live tuples, and the ratio. A high ratio on a large table usually means a query is reading the whole table where an index would suffice. Pair with `pg_top_queries` to find which query is doing it.",
     annotations: {
       title: "Find tables with heavy sequential scans",
       readOnlyHint: true,
@@ -37454,7 +37473,7 @@ var statsTools = [
   },
   {
     name: "pg_unused_indexes",
-    description: "Indexes that have never been scanned or have very low usage. Each unused index costs write amplification (every INSERT/UPDATE maintains it) and disk space. Excludes primary keys and unique constraints (which are load-bearing even with zero scans). Use this before adding new indexes \u2014 sometimes the fix is to drop a dead one.",
+    description: "Indexes that have never been scanned or have very low usage. Each unused index costs write amplification (every INSERT/UPDATE maintains it) and disk space. Excludes primary keys and unique constraints (which are load-bearing even with zero scans). Use this before adding new indexes - sometimes the fix is to drop a dead one.",
     annotations: {
       title: "Find unused indexes",
       readOnlyHint: true,
@@ -37510,7 +37529,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.5.3" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.6.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.5.3",
-  "description": "PostgreSQL MCP server — query, schema introspection, explain, and health checks for AI assistants",
+  "version": "0.6.0",
+  "description": "PostgreSQL MCP server - query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
   "repository": {