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

> Execute ordered parameterized PostgreSQL statements atomically.

`postgres.transaction` executes 1–100 statements on one connection between `BEGIN` and `COMMIT`. PostgreSQL rolls the complete transaction back after the first failure.

## Example

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

export default automation("Create order", () => {
  const request = onHttpRequest({
    body: z.object({
      customerId: z.string(),
      orderId: z.string(),
      quantity: z.number().int().positive(),
      sku: z.string(),
    }),
    scope: "automation",
  })

  postgres.transaction({
    statements: [
      {
        sql: "insert into orders (id, customer_id) values ($1, $2)",
        parameters: [request.body.orderId, request.body.customerId],
      },
      {
        sql: "update inventory set available = available - $1 where sku = $2",
        parameters: [request.body.quantity, request.body.sku],
      },
    ],
  })
})
```

## Inputs

| Input                          | Type                                                | Required | Default         | Description                         |
| ------------------------------ | --------------------------------------------------- | -------- | --------------- | ----------------------------------- |
| `statements`                   | `PostgresStatement[]`                               | Yes      | None            | 1–100 statements executed in order. |
| Second argument: `{ account }` | `string \| IntegrationAccountReference<"postgres">` | No       | Project default | Connected PostgreSQL database.      |

Each statement contains one non-empty `sql` string and optional `(JsonValue | bigint | Date | Uint8Array)[]` `parameters`. Transaction-control statements such as `BEGIN`, `COMMIT`, `ROLLBACK`, and `SAVEPOINT` are rejected because the action owns the transaction boundary.

## Output

Returns `{ results }`. `results` contains one `command`, `rowCount`, `rows`, and `fields` envelope per statement in input order.

## Permissions, failures, and retries

The connected role needs the union of the exact database privileges required by every statement. The first PostgreSQL failure stops execution and rolls back earlier changes. If rollback itself fails, the action reports both failures.

This action is not replay-safe. A connection loss during `COMMIT` can leave transaction resolution unknown, so Automate.ax does not repeat the transaction automatically. Use durable business keys and constraints when a caller may retry the automation.