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

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Run query

> Execute one parameterized PostgreSQL statement and return its rows and metadata.

`runQuery` opens a fresh database connection, executes one statement, returns
the result, and closes the connection whether the query succeeds or fails.

## Example

```ts automations/query-postgres.automation.ts theme={null}
import { automation, onHttpRequest } from "automate.ax"
import { runQuery } from "automate.ax/postgres"

export default automation("Find recent pro customers", () => {
  onHttpRequest({ scope: "automation" })

  runQuery({
    sql: `
      select id, email
      from customers
      where plan = $1 and created_at >= $2
      order by created_at desc
    `,
    parameters: ["pro", new Date("2026-01-01T00:00:00Z")],
  })
})
```

## Inputs

| Input        | Type                                                | Required | Default         | Description                                         |
| ------------ | --------------------------------------------------- | -------- | --------------- | --------------------------------------------------- |
| `sql`        | `string`                                            | Yes      | —               | One non-empty SQL statement.                        |
| `parameters` | `(JsonValue \| bigint \| Date \| Uint8Array)[]`     | No       | `[]`            | Values bound to `$1`, `$2`, and later placeholders. |
| `account`    | `string \| IntegrationAccountReference<"postgres">` | No       | Project default | Connected PostgreSQL database.                      |

<Warning>
  Use parameters for untrusted values. Placeholders cannot represent table or
  column names; do not concatenate untrusted identifiers into SQL.
</Warning>

## Output

Returns a signal containing:

| Property   | Type                          | Description                                                     |
| ---------- | ----------------------------- | --------------------------------------------------------------- |
| `command`  | `string`                      | PostgreSQL command tag such as `SELECT`, `INSERT`, or `UPDATE`. |
| `rowCount` | `number \| null`              | Returned or affected row count when PostgreSQL supplies one.    |
| `rows`     | `Record<string, Encodable>[]` | Result rows keyed by returned column name.                      |
| `fields`   | `PostgresField[]`             | Metadata for returned fields.                                   |

Each field contains `name`, `columnId`, `tableId`, `dataTypeId`,
`dataTypeSize`, `dataTypeModifier`, and `format`. A new connection per action is
appropriate for independent statements; use `getPostgresClient` in a custom
action when you need a transaction, cursor, or session-level state.