Skip to main content
PostgresTools enable an Agent to interact with a PostgreSQL database.

​
Prerequisites

The following example requires the psycopg and openai libraries. 
uv pip install -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

​
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

NameTypeDefaultDescription
connectionOptional[PgConnection[DictRow]]NoneOptional existing psycopg connection object.
db_nameOptional[str]NoneOptional name of the database to connect to.
userOptional[str]NoneOptional username for database authentication.
passwordOptional[str]NoneOptional password for database authentication.
hostOptional[str]NoneOptional host for the database connection.
portOptional[int]NoneOptional port for the database connection.
table_schemastrpublicSchema name to search for tables.

​
Toolkit Functions

FunctionDescription
show_tablesRetrieves and displays a list of tables in the database. Returns the list of tables.
describe_tableDescribes 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_tableSummarizes 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_queryInspects 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_pathExports 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_queryExecutes 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