PostgreSQL

Query and manage PostgreSQL databases

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', '[e-mail]')")
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

Error	Cause	Solution
psycopg2 not installed	Missing dependency	Run pip install psycopg2-binary
Connection refused	Database not running	Start PostgreSQL server
Authentication failed	Wrong credentials	Check username/password

Best Practices

Load credentials from the environment

Read POSTGRES_HOST, POSTGRES_USER, and POSTGRES_PASSWORD from the environment rather than hard-coding them in the tool call.

Use LIMIT on generated queries

Agent-generated SELECTs can return huge result sets. Instruct the agent to add LIMIT so results stay within the context window.

Scope agent access

Give the agent a read-only role for analytics tasks so generated SQL cannot modify data. Use a dedicated schema when writes are required.

Related Tools

MySQL

MySQL database

SQLite

SQLite database

MongoDB

NoSQL database