> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Postgres SQL Tool

> Execute SQL queries on your Postgres database with automatic safety limits

## What it does

The Postgres SQL tool lets your agents run SQL queries directly on your PostgreSQL database. Perfect for data analysis, reporting, and retrieving specific information from your database.

<Note>
  **Requires Postgres Integration**: You need to set up a [Postgres integration](/integrations/postgres) before agents can use this tool.
</Note>

## Key features

* Execute any SQL query (SELECT, INSERT, UPDATE, DELETE)
* Results are truncated to a 30,000-token budget, so a wide query returns as many whole rows as fit
* Clean, structured results that agents can easily parse
* Built-in error handling for common SQL issues

## Parameters

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `query`   | string | Yes      | The SQL query to execute |

There is no row-count parameter. If you need a specific number of rows, put `LIMIT` in the
query itself.

## Common use cases

### Data analysis

```sql theme={null}
SELECT 
  DATE_TRUNC('month', order_date) as month,
  COUNT(*) as total_orders,
  SUM(total_amount) as revenue
FROM orders 
WHERE order_date >= '2024-01-01'
GROUP BY month
ORDER BY month DESC;
```

### User lookups

```sql theme={null}
SELECT user_id, email, last_login, account_status
FROM users 
WHERE email = 'user@example.com';
```

### Performance monitoring

```sql theme={null}
SELECT COUNT(*) as active_sessions
FROM pg_stat_activity 
WHERE state = 'active';
```

## Security best practices

* Use read-only database users when possible
* Avoid querying sensitive data (passwords, API keys, PII)
* Use WHERE clauses to limit data exposure
* Monitor agent queries regularly

## Troubleshooting

**"Could not connect to database"**

* Check that your Postgres integration is configured and connected
* Verify database server is running and accessible

**"Permission denied for table"**

* Ensure your database user has SELECT permissions
* Check that the table exists and is accessible

**"Syntax error"**

* Validate your SQL syntax
* Check table and column names for typos

## Related tools

* **Semantic Search Postgres** (`semantic_search_pg`) - Search using natural language
* **Keyword Search Postgres** (`keyword_search_pg`) - Full-text search across content

## Tool Metadata

* **Name**: `postgres_sql`
* **Display Name**: Postgres SQL
* **Description**: Execute a SQL query on Postgres
* **Required Integration**: [Postgres](/integrations/postgres)
* **Result limit**: 30,000 tokens; rows past the budget are dropped and the response is flagged as truncated