Postgres
Audience: Admins, Developers, Solution Architects
Purpose: Explains what the Postgres integration is, when to use it, and how it works within your Agentic Workflows
Overview
Run SQL queries and statements against an external PostgreSQL database directly from an Agentic Workflow in Kizen and use the results in later steps with the Postgres integration.
What Is the Postgres Integration?
The Postgres integration adds two action steps to the Agentic Workflow builder:
Read Data: Runs a
SELECTquery against your PostgreSQL database and returns the results to a variableWrite Data: Executes
INSERT,UPDATE, orDELETEstatements and returns the number of affected Records
You configure the connection to your PostgreSQL database once, as an integration secret in Kizen. See Enable Postgres in Kizen for details.
The integration supports a single PostgreSQL environment or multiple environments, each with its own connection credentials. If you have more than one environment, you specify which to query when you call Read Data or Write Data from your Agentic Workflow.
To learn more, see Add Postgres Data to an Agentic Workflow.
When to Use the Postgres Integration
Use the Postgres integration when an Agentic Workflow needs to check or update data that lives outside Kizen, in a PostgreSQL application database or data warehouse, before continuing to the next step. You don't need to copy the data into Kizen first. The integration handles the communication with the PostgreSQL server.
Common Use Cases
Confirming a patient's prior authorization status before scheduling
Updating an insurance claim record after automated review
Checking a credit applicant's real-time debt-to-income ratio
How the Postgres Integration Works
Before you configure the Postgres integration, it's important to understand how it functions at a conceptual level.
Connection Model
Connecting to a PostgreSQL database from Kizen requires a PostgreSQL role with the appropriate read and write privileges on the tables to query. But instead of using an authorization protocol like OAuth, the Postgres integration keeps track of your connection credentials as an integration secret. A single secret can hold credentials to multiple PostgreSQL environments, such as production and staging, as separate keys. You select which environment to use at each Read Data or Write Data step of the Agentic Workflow.
For more information, see Add Postgres Data to an Agentic Workflow.
Query Execution
Queries and statements execute synchronously, so the Agentic Workflow waits at the Read Data or Write Data step until the PostgreSQL database returns the result. The step times out on the Kizen side after 30 seconds.
Rate Limiting
Rate limits are subject to your PostgreSQL server's maximum number of connections, per-role connection limits, and timeout setting.
Results Handling
Both the Read Data and Write Data steps include the Return Single Value input, which, when true, signifies that you expect to return exactly one row and one column from the database. The result comes back as a string. When false, the full result set comes back as a single string in JSON format. To refer to the values of individual keys in later steps of the Agentic Workflow, parse the JSON string in a Code step.
Please also note the following:
Results sets larger than 5 MB might be truncated. Use
LIMITin the query to narrow the results.A result with multiple rows isn't auto-paginated. If you need pages, use
LIMITandOFFSETin the query.A query that returns no rows returns an empty string, not the null value.
Failure Handling
If a connection or query fails, for example because of invalid credentials, an unreachable database, or invalid SQL, the step fails immediately and results in an error message. For more information, see Troubleshoot Postgres. Kizen doesn't automatically retry a failed step, so after you correct the underlying issue, rerun the step manually.
Data Safety
If your Agentic Workflow writes data to your database, be sure to validate its behavior thoroughly on non-production data first. You can't roll back a Write Data operation after it executes, and the operation might partially apply if an error occurs during execution.
To maximize the safety of your data, grant the connected user role the appropriate level of access to PostgreSQL data and operations. If you don't intend to write data, for example, a read-only user with SELECT privileges on the specific tables to read is sufficient. Avoid PostgreSQL superusers.
Available Postgres Actions and Topics
For step-by-step instructions on using the Postgres integration, see the following topics:
What's Next
Continue to Enable Postgres in Kizen to configure your PostgreSQL network, turn on the Postgres integration, and enter your connection credentials as an integration secret.
Postgres, PostgreSQL, and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada. Kizen's PostgreSQL integration is not affiliated with, sponsored by, or endorsed by the PostgreSQL Community Association of Canada, the PostgreSQL Global Development Group, or the PostgreSQL Project.
Last updated
Was this helpful?