Postgres Voice

The Postgres voice gives agents read access to a Postgres database, with a separate destructive execute tool for writes.

The default query tool runs every statement inside BEGIN READ ONLY, so Postgres itself rejects writes with SQLSTATE 25006 even if the connecting role has write privileges. The execute tool is the only writable surface and is marked destructive: true, so HITL-enabled runtimes gate it behind human approval before anything mutates state.

Installation

npx tutti-ai add postgres

Required permissions

permissions: ["network"]

Required environment variables

Var	Description
DATABASE_URL	Postgres connection string (POSTGRES_URL also recognised)

Add to your .env:

DATABASE_URL=postgres://user:pass@host:5432/dbname

For an extra layer of defence beyond the read-only transaction wrapper, create a dedicated read-only role:

CREATE ROLE agent_reader LOGIN PASSWORD 'strong-password';
GRANT CONNECT ON DATABASE myapp TO agent_reader;
GRANT USAGE ON SCHEMA public TO agent_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO agent_reader;

Even if an agent finds a way to bypass the voice, the role itself cannot write.

Configuration

// Default: reads DATABASE_URL / POSTGRES_URL from env
new PostgresVoice()

// Explicit options
new PostgresVoice({
  connection_string: "postgres://...",
  statement_timeout_ms: 30_000,
  max_connections: 5,
})

Option	Default	Notes
connection_string	env	Overrides DATABASE_URL / POSTGRES_URL.
statement_timeout_ms	30_000	Server-side per-statement timeout. SQLSTATE 57014 is mapped to a clear error when exceeded.
max_connections	5	Pool size. Most managed Postgres providers cap connections aggressively — keep this low.

Tool reference

Tool	Destructive	Description
query	no	Run SELECT/CTE/explain SQL inside BEGIN READ ONLY. Returns rows as a fixed-width table; truncated at max_rows (default 100, max 1000).
execute	yes	Run INSERT/UPDATE/DELETE/DDL. Returns the affected row count. Gated behind HITL.
list_schemas	no	List schemas with owner. Skips system schemas by default.
list_tables	no	List tables (and views) in a schema with approximate row counts from pg_class.reltuples.
describe_table	no	Show columns with type, nullable, default, and primary-key membership.
list_indexes	no	List indexes on a table with the full CREATE INDEX definitions.
explain	no	Run EXPLAIN (or EXPLAIN ANALYZE) inside a read-only transaction.
get_database_info	no	Server version, current database, user, on-disk size, schema/table counts.

Example

import { defineScore, AnthropicProvider } from "@tuttiai/core";
import { PostgresVoice } from "@tuttiai/postgres";

export default defineScore({
  provider: new AnthropicProvider(),
  agents: {
    analyst: {
      name: "analyst",
      model: "claude-sonnet-4-20250514",
      system_prompt:
        "You are a data analyst. The user will ask questions about the connected database. Use list_tables and describe_table before writing queries. Always parameterise values with $1, $2, ...",
      voices: [new PostgresVoice()],
      permissions: ["network"],
    },
  },
});

Run it:

tutti-ai run analyst "How many orders did we have last week broken down by status?"