PostgreSQL

The Postgres toolkit lets you connect your own PostgreSQL database to Alma. Once connected, agents can run read queries against your data — joining tables, filtering rows, and surfacing results inside chat or responsibility outputs.

Connecting a database

1. Go to Settings → Connections and find PostgreSQL.
2. Click Connect to open the database connection dialog.
3. Fill in your connection details:
   • Host and Port
   • Database name
   • Username and Password
4. Toggle SSL if your database requires an encrypted connection.
5. Toggle Read-only to enforce read-only access at the session level (recommended for most agent use cases).
6. Click Test & Save — Alma validates the credentials before saving.

You can connect multiple databases (like GitHub accounts) and switch between them in the responsibility configuration dropdown.

Safety guardrails

The Postgres toolkit includes built-in protections:

• DDL blocking — CREATE, DROP, ALTER, and similar schema-changing statements are blocked.
• Query timeout — Long-running queries are automatically cancelled after a configurable timeout.
• Row limits — Result sets are capped to prevent runaway queries from returning unbounded data.

Using Postgres in a responsibility

When configuring a responsibility that includes Postgres tools, a Database dropdown appears in the trigger configuration panel. Select which connected database the agent should query for that responsibility.

Triggering responsibilities from database events

You can trigger agent responsibilities automatically when rows are inserted, updated, or deleted in your Postgres (or Supabase) database using webhooks.

Setting up a webhook trigger

After connecting a database, navigate to its source detail page in Settings → Connections. Alma surfaces a Webhook Setup panel with:

• Endpoint URL — the unique Postgres webhook URL for your connection (e.g. /api/webhooks/postgres/:connectionId).
• Secret header — a secret value you must include in the webhook request headers so Alma can verify the request is authentic.
• Setup instructions — step-by-step guidance for configuring your database to send events to Alma (e.g. using Supabase Database Webhooks or pg_webhooks).

Supported events

Once configured, you can trigger responsibilities on any of the following database events:

Creating an event-driven responsibility

When creating a responsibility, select Event-driven as the trigger type and choose the Postgres source. The available events (row.inserted, row.updated, row.deleted) appear in the trigger configuration panel. You can add source event filters to scope the trigger to a specific table or matching field values.

Disconnecting

Click Disconnect on the connection card to remove a database. Alma stops querying it, but knowledge already extracted into memory is retained.