Skip to main content
The PostgreSQL tool lets an agent query and manage PostgreSQL databases directly.

​
Overview

PostgreSQL tool allows you to query and manage PostgreSQL databases directly from your AI agents.

​
Installation

pip install "praisonai[tools]"

​
Environment Variables

export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DATABASE=mydb
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=your_password

​
Quick Start

1

Simple Usage

from praisonai_tools import PostgresTool

# Initialize
pg = PostgresTool(
    host="localhost",
    database="mydb",
    user="postgres",
    password="your_password"
)

# Query
results = pg.query("SELECT * FROM users LIMIT 5")
print(results)
2

With Configuration

Use the same tool with an agent — see Usage with Agent below, or pass env vars and options from the sections above.

​
How It Works

​
Usage with Agent

from praisonaiagents import Agent
from praisonai_tools import PostgresTool

pg = PostgresTool(
    host="localhost",
    database="mydb",
    user="postgres",
    password="your_password"
)

agent = Agent(
    name="DBAnalyst",
    instructions="You are a database analyst. Use PostgreSQL to query data.",
    tools=[pg]
)

response = agent.chat("Show me the top 10 customers by order count")
print(response)

​
Available Methods

​
query(sql)

Execute a SQL query. 
from praisonai_tools import PostgresTool

pg = PostgresTool(host="localhost", database="mydb", user="postgres", password="pass")

# SELECT query
results = pg.query("SELECT * FROM users WHERE active = true")

# Returns list of dictionaries
# [{"id": 1, "name": "Alice", "active": true}, ...]

​
execute(sql)

Execute a SQL statement (INSERT, UPDATE, DELETE). 
pg.execute("INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com')")
pg.execute("UPDATE users SET active = false WHERE id = 5")

​
list_tables()

List all tables in the database. 
tables = pg.list_tables()
# Returns: [{"table_name": "users"}, {"table_name": "orders"}, ...]

​
describe_table(table_name)

Get table schema. 
schema = pg.describe_table("users")
# Returns column names, types, and constraints

​
Configuration Options

pg = PostgresTool(
    host="localhost",
    port=5432,
    database="mydb",
    user="postgres",
    password="your_password",
    schema="public"
)

​
Function-Based Usage

from praisonai_tools import query_postgres, list_postgres_tables

# Quick query
results = query_postgres("SELECT * FROM users", host="localhost", database="mydb", user="postgres", password="pass")

# List tables
tables = list_postgres_tables(host="localhost", database="mydb", user="postgres", password="pass")

​
Docker Setup

docker run -d --name postgres \
    -e POSTGRES_PASSWORD=praison123 \
    -e POSTGRES_DB=praisonai \
    -p 5432:5432 \
    postgres:16

​
Error Handling

from praisonai_tools import PostgresTool

pg = PostgresTool(host="localhost", database="mydb", user="postgres", password="pass")
result = pg.query("SELECT * FROM users")

if "error" in result:
    print(f"Error: {result['error']}")
else:
    for row in result:
        print(row)

​
Common Errors

ErrorCauseSolution
psycopg2 not installedMissing dependencyRun pip install psycopg2-binary
Connection refusedDatabase not runningStart PostgreSQL server
Authentication failedWrong credentialsCheck username/password

​
Best Practices

Read POSTGRES_HOST, POSTGRES_USER, and POSTGRES_PASSWORD from the environment rather than hard-coding them in the tool call.
Agent-generated SELECTs can return huge result sets. Instruct the agent to add LIMIT so results stay within the context window.
Give the agent a read-only role for analytics tasks so generated SQL cannot modify data. Use a dedicated schema when writes are required.

MySQL

MySQL database

SQLite

SQLite database

MongoDB

NoSQL database