> ## 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.

# Execute statement

> Execute one parameterized read/write PostgreSQL statement.

`postgres.execute` executes exactly one statement in its own implicit PostgreSQL transaction. Use it for `INSERT`, `UPDATE`, `DELETE`, DDL, and other work that can change database state.

## Example

```ts automations/update-customer.automation.ts theme={null}
import { automation, onHttpRequest } from "automate.ax"
import { postgres } from "automate.ax/postgres"
import { z } from "zod"

export default automation("Activate customer", () => {
  const request = onHttpRequest({
    body: z.object({ customerId: z.string() }),
    scope: "automation",
  })

  postgres.execute({
    sql: `
      update customers
      set status = $1
      where id = $2
      returning id, status
    `,
    parameters: ["active", request.body.customerId],
  })
})
```

## Inputs

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

Use parameters for values. PostgreSQL does not accept parameters for schema, table, or column identifiers.

## Output

Returns `command`, `rowCount`, `rows`, and `fields` in the same shape as [Run query](/reference/integrations/postgres/actions/run-query). Add `RETURNING` to a mutation when you need changed rows.

## Permissions and retries

Grant the connected role only the privileges required by the statement. Common mutations need schema `USAGE`, the matching table privilege, and sequence `USAGE` for generated identifiers. DDL usually requires object ownership or schema `CREATE`.

This action is not replay-safe. If PostgreSQL accepts a mutation but the connection fails before Automate.ax receives the result, Automate.ax does not repeat the statement automatically. Use database constraints or an idempotency key in your schema when callers can retry the automation.

For several changes that must commit together, use [Run transaction](/reference/integrations/postgres/actions/run-transaction).