Postgres | Agno

PostgresTools enable an Agent to interact with a PostgreSQL database.

Prerequisites

The following example requires the psycopg and openai libraries.

uv pip install agno -U "psycopg[binary]" openai

You will also need a database. The following example uses a Postgres database running in a Docker container.

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Once the local container is ready, seed a small demonstration table:

docker exec pgvector psql -U ai -d ai -c "CREATE SCHEMA IF NOT EXISTS ai; CREATE TABLE IF NOT EXISTS ai.tool_demo_sales (id integer PRIMARY KEY, product text, revenue numeric); INSERT INTO ai.tool_demo_sales VALUES (1, 'Notebook', 120), (2, 'Pen', 45) ON CONFLICT (id) DO NOTHING;"

The sample data is for the local tutorial. To use your own database, replace the connection settings and choose an accessible populated schema.

Example

The following agent will list all tables in the database.

cookbook/91_tools/postgres_tools.py

from agno.agent import Agent
from agno.tools.postgres import PostgresTools

agent = Agent(
    tools=[
        PostgresTools(
            host="localhost",
            port=5532,
            db_name="ai",
            user="ai",
            password="ai",
            table_schema="ai",
        )
    ]
)

agent.print_response(
    "List the tables in the database and summarize one of the tables", markdown=True
)

Toolkit Params

Name	Type	Default	Description
`connection`	`Optional[PgConnection[DictRow]]`	`None`	Optional existing psycopg connection object.
`db_name`	`Optional[str]`	`None`	Optional name of the database to connect to.
`user`	`Optional[str]`	`None`	Optional username for database authentication.
`password`	`Optional[str]`	`None`	Optional password for database authentication.
`host`	`Optional[str]`	`None`	Optional host for the database connection.
`port`	`Optional[int]`	`None`	Optional port for the database connection.
`table_schema`	`str`	`public`	Schema name to search for tables.

Toolkit Functions

Function	Description
`show_tables`	Retrieves and displays a list of tables in the database. Returns the list of tables.
`describe_table`	Describes the structure of a specified table by returning its columns, data types, and nullability. Parameters include `table` (str) to specify the table name. Returns the table description.
`summarize_table`	Summarizes a table by computing aggregates such as min, max, average, standard deviation, and non-null counts for numeric columns, or unique values and average length for text columns. Parameters include `table` (str) to specify the table name. Returns the summary of the table.
`inspect_query`	Inspects an SQL query by returning the query plan using EXPLAIN. Parameters include `query` (str) to specify the SQL query. Returns the query plan.
`export_table_to_path`	Exports a specified table in CSV format to a given path. Parameters include `table` (str) to specify the table name and `path` (str) to specify where to save the file. Returns the result of the export operation.
`run_query`	Executes a read-only SQL query and returns the result. Parameters include `query` (str) to specify the SQL query. Returns the result of the query execution.

You can use include_tools or exclude_tools to modify the list of tools the agent has access to. Learn more about selecting tools.

Developer Resources

Tools