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

# PostgreSQL

> Run queries on PostgreSQL

## Overview

The PostgreSQL tool allows you to run SQL queries on a PostgreSQL database.

## Key Features

* `POSTGRES_RUN_QUERY`
  * Run a SQL query on a PostgreSQL database. Supports SELECT, INSERT, UPDATE, DELETE, and other SQL statements.
  * Inputs: `connection` (a PostgreSQL connection secret) and `query` (the SQL to run).
  * Retrieve results in a structured format (columns and rows).

## Authentication

Create a `POSTGRES` secret with your connection details and pass it as the `connection` input:

* **Host**: Hostname of the PostgreSQL server (required).
* **Port**: Port number. Defaults to `5432` if omitted.
* **Database**: Name of the database to connect to.
* **User**: Username to connect with.
* **Password**: Password for the user.
* **SSL**: Whether to use SSL. Enabled by default; set to `false` (or `disable`) to turn it off. The legacy `sslmode` field is also accepted.

**Note**: Treat credentials as sensitive information and never commit them to public repositories.

### SSL behavior

SSL is enabled by default and server certificates are not strictly verified. If the initial SSL connection fails and SSL was not explicitly disabled, the tool automatically retries without SSL (the server may not support it).

## Usage Examples

### Example: Run PostgreSQL Query

```yaml theme={null}
- id: run_query
  input:
    - name: connection
      value: "{{secrets.MY_POSTGRES_SECRET}}"
    - name: query
      value: "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10;"
  tool: POSTGRES_RUN_QUERY
```

### Example: Query and Summarize with an LLM

```yaml theme={null}
- id: fetch_orders
  input:
    - name: connection
      value: "{{secrets.MY_POSTGRES_SECRET}}"
    - name: query
      value: "SELECT status, COUNT(*) AS count FROM orders GROUP BY status;"
  tool: POSTGRES_RUN_QUERY

- id: summarize
  tool: OPENAI_INVOKE
  input:
    - name: prompt
      value: |
        Summarize the following order status breakdown for a weekly report.

        Columns: {{steps.fetch_orders.result.columns}}
        Rows: {{steps.fetch_orders.result.rows}}
```

## Notes

* **Timeouts**: The connection attempt times out after 10 seconds, and each statement times out after 30 seconds.
* **Not read-only**: Write statements (INSERT, UPDATE, DELETE, DDL) are executed as-is. Use a database user with appropriately scoped privileges.
* **Result serialization**: Non-primitive values are converted to strings — dates become ISO 8601 strings, binary (`bytea`) values become hex strings, and JSON/array/object values are serialized as JSON strings.
* **Non-row-returning statements**: Queries that return no result set (e.g., plain `INSERT` without `RETURNING`) return empty `columns` and `rows`.