Actions: named transactions with effects

An action is a named, parameterised SQL transaction. You define it once, for example saveOrder, and then call it by name from your SDK, from a cron job, or from an AI coding tool. Everything inside runs atomically: either all of it happens or none of it does.

Open Actions

In the sidebar, under Platform Services, choose Actions. The page, Actions Studio, lists your Registered Database Actions with their signature, such as pgb.saveOrder(), a status of Active, the SQL template, and Test / Run Action and Delete buttons.

Define an action

1. Choose + Define New Action.
2. Enter an Action Display Name and a Function Signature. The signature is how you call it, so use camelCase with no spaces or punctuation, for example saveUser.
3. Add a Description.
4. Write the SQL Template. Use %(param_name)s for inputs, for example INSERT INTO users (name, email) VALUES (%(name)s, %(email)s) RETURNING id, name.
5. Choose Validate SQL & Catalog to check it against your real tables.
6. Optionally add an Outbox Webhook URL, and Then do (Effects) (below).
7. Choose Save & Register Action.

AI Action Copilot (Generate from Schema) can suggest actions from your tables. You review the suggestions and choose Accept Selected.

Effects: what happens after the SQL commits

Effects run only after the transaction has committed, so a failed insert never sends an email, and a sent email is never lost with a rolled back insert. Choose + Add effect to add one. Each effect is delivered at least once and retried with back-off if it fails.

Effect	Does
function	Calls one of your functions
queue	Publishes a queue message
mail	Sends an email
event	Emits an event that event rules can react to
job	Enqueues a background job
realtime	Broadcasts to a realtime channel
container	Calls a route on one of your containers
action	Runs another action (depth is limited so loops stop)
webhook	Calls a URL

In effect values, {{params.email}} is an input and {{results.0.id}} is a value the SQL returned. Make effects safe to repeat, because a delivery can be retried.

Run it

Choose Test / Run Action, enter Input Parameters (JSON Object) and run. Tick Dry Run Simulation (Rollback transaction after execution) to preview the result and the planned effects without changing anything. From code:

const res = await pgb.actions.saveUser({ name: "Alex", email: "[email protected]" });
const preview = await pgb.actions.saveUser({ name: "Alex" }, { dryRun: true });

With a secret key you can also manage actions in code, with $register, $list, $get, $deliveries (to see what each effect did and why one failed), $retryDelivery and $delete.

Keep actions in your own repository

On the Actions page, Download pgbhub.config.json gives you a file describing your actions that you can keep in version control. To generate TypeScript types for your schema, use npx pgb pull from the TypeScript SDK package. See Use the TypeScript SDK.

Good to know

• If a table or column an action uses changes, the page shows a Schema Impact Alert with a Suggest Fix button.
• AI agents connected through the MCP server can discover and run your actions. See Connect AI coding tools with the MCP server.
• Actions also work as the target of a cron job or a job.