Run Queries on PostgreSQL in Jinba Flow

Use POSTGRES_RUN_QUERY to run a query, including INSERT statements with RETURNING that return rows.

The PostgreSQL tool allows you to run SQL queries on a PostgreSQL database.

• POSTGRES_RUN_QUERY
  • Run a SQL query on a PostgreSQL database. Supports SELECT, INSERT, UPDATE, DELETE, and other SQL statements.
  • Inputs: connection (a PostgreSQL connection secret) and query (the SQL to run).
  • Retrieve results in a structured format (columns and rows).

Connect with PostgreSQL credentials

Create a POSTGRES secret with your connection details and pass it as the connection input:

• Host: Hostname of the PostgreSQL server (required).
• Port: Port number. Defaults to 5432 if omitted.
• Database: Name of the database to connect to.
• User: Username to connect with.
• Password: Password for the user.
• SSL: Whether to use SSL. Enabled by default; set to false (or disable) to turn it off. The legacy sslmode field is also accepted.
• ssl_verify: Whether to verify the server’s TLS certificate. Enabled by default. Turning it off keeps the connection encrypted but stops checking the server’s identity. Not recommended.
• ssl_ca: The CA certificate (PEM) that signed the server certificate. Set this when the server uses a private or self-signed CA, such as Amazon RDS, Google Cloud SQL or Supabase direct connections. You can paste several certificates in one value.

Note: Treat credentials as sensitive information and never commit them to public repositories.

SSL behavior

SSL is enabled by default, and the tool verifies the server certificate against the public CAs plus any certificate in ssl_ca. A connection whose certificate cannot be verified fails with PostgresConnectionError. The error message names the setting to change.

The tool never falls back to an unencrypted connection. If the server does not support SSL, turn off SSL explicitly.

If you turn off ssl_verify, each run records a warning in the step’s logs.

When Host is an IP address, the server certificate rarely lists that IP. If ssl_ca is set for an IP host, the tool checks only that the certificate is signed by ssl_ca and skips the name check, and each run records a notice in the step’s logs. Use this only with a CA dedicated to that server, such as a Google Cloud SQL instance’s server CA. With a shared or public CA, any certificate that CA signed would be accepted. Otherwise, set Host to the host name on the certificate.

Run a query

- id: run_query
  input:
    - name: connection
      value: "{{secrets.MY_POSTGRES_SECRET}}"
    - name: query
      value: "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10;"
  tool: POSTGRES_RUN_QUERY

Example: Query and Summarize with an LLM

- id: fetch_orders
  input:
    - name: connection
      value: "{{secrets.MY_POSTGRES_SECRET}}"
    - name: query
      value: "SELECT status, COUNT(*) AS count FROM orders GROUP BY status;"
  tool: POSTGRES_RUN_QUERY

- id: summarize
  tool: OPENAI_INVOKE
  needs: [fetch_orders]
  input:
    - name: prompt
      value: |
        Summarize the following order status breakdown for a weekly report.

        Columns: {{steps.fetch_orders.result.columns}}
        Rows: {{steps.fetch_orders.result.rows}}

Notes

• Timeouts: The connection attempt times out after 10 seconds, and each statement times out after 30 seconds.
• Not read-only: Write statements (INSERT, UPDATE, DELETE, DDL) are executed as-is. Use a database user with appropriately scoped privileges.
• Result serialization: Non-primitive values are converted to strings — dates become ISO 8601 strings, binary (bytea) values become hex strings, and JSON/array/object values are serialized as JSON strings.
• Non-row-returning statements: Queries that return no result set (e.g., plain INSERT without RETURNING) return empty columns and rows.