> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-agui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Postgres

> The PostgresTools toolkit enables an Agent to interact with a PostgreSQL database.

**PostgresTools** enable an Agent to interact with a PostgreSQL database.

## Prerequisites

The following example requires the `psycopg2` library.

```shell theme={null}
uv pip install -U psycopg2
```

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

```shell theme={null}
docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql/data/pgdata \
  -v pgvolume:/var/lib/postgresql/data \
  -p 5532:5432 \
  --name pgvector \
  agno/pgvector:16
```

## Example

The following agent will list all tables in the database.

```python cookbook/14_tools/postgres.py theme={null}
from agno.agent import Agent
from agno.tools.postgres import PostgresTools

# Initialize PostgresTools with connection details
postgres_tools = PostgresTools(
    host="localhost",
    port=5532,
    db_name="ai",
    user="ai",
    password="ai"
)

# Create an agent with the PostgresTools
agent = Agent(tools=[postgres_tools])

# Example: Ask the agent to run a SQL query
agent.print_response("""
Please run a SQL query to get all users from the users table
who signed up in the last 30 days
""")
```

## 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](/tools/selecting-tools).

## Developer Resources

* View [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/postgres.py)