neon.queries.run

Execute a SQL statement over psycopg3 against a Neon branch

Executes a single SQL statement against a Neon branch over the Postgres wire protocol (psycopg3). This atomic does NOT use the Neon REST API for query execution — it connects directly with the supplied connection_uri.

The driver (psycopg[binary]) is an optional dependency of base-library, installed only in environments that run this atomic::

pip install ltinteg-workflow-base-library[neon-query]

Inputs:

• connection_uri: str — full postgres DSN with embedded credentials (required). Treated as a secret: never logged. Scheme MUST be postgres:// or postgresql:// — any other scheme is a non-retryable error.
• sql: str — the SQL statement to execute (required).
• params: list — positional query parameters; passed parameterised, never string-formatted (optional).
• fetch_results: bool — whether to fetch rows (optional, default: True).
• timeout_seconds: int — connect timeout, capped at 120 (optional, default: 30).

Outputs (terminal state_data):

• rows: list — list of row dicts (empty if DML/DDL or fetch_results is False)
• row_count: int — cursor rowcount
• status_message: str — e.g. "SELECT 5", "INSERT 0 1"

Credential handling: authentication is entirely in connection_uri; this atomic never calls context.get_plugin("neon"). The URI is supplied by the orchestration workflow (C-06) that first calls A-20 to obtain it.

Notes:

• autocommit=True is required: Neon serverless suspends on idle and re-opening a transaction across suspend/resume is unreliable.

Overview

Property	Value
Workflow type	Atomic
Library	Base
Version	1.0

Input Schema

Field	Type	Required	Default	Description
connection_uri	string	Yes	—	Full postgres DSN with embedded credentials (secret)
sql	string	Yes	—	SQL statement to execute
params	list	No	—	Positional query parameters (parameterised)
fetch_results	boolean	No	—	Whether to fetch rows (default: True)
timeout_seconds	integer	No	—	Connect timeout seconds (default: 30, cap 120)

Output Schema

Field	Type	Required	Default	Description
rows	list	No	—	List of row dicts (empty for DML/DDL)
row_count	integer	No	—	—
status_message	string	No	—	e.g. 'SELECT 5', 'INSERT 0 1'
connection_uri	string	No	—	—
sql	string	No	—	—
params	list	No	—	—
fetch_results	boolean	No	—	—
timeout_seconds	integer	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "neon.queries.run",
  "initial_data": {
    "connection_uri": "value",
    "sql": "value"
  }
}