Protocol Reference

Every stdin/stdout line is one JSON object with required code.

• pipe mode: full protocol with id correlation
• CLI mode: same event schema, id may be omitted in display output
• protocol events are emitted on stdout only
• stderr is not part of the runtime protocol contract

Interface Boundary

This protocol is the only runtime interface.

• psql mode is CLI argument translation only; runtime protocol is unchanged
• no legacy text interpolation
• no table/text output contract

Input (stdin)

query

Execute one SQL statement.

options fields:

Parameter Binding Rules

1. Dynamic values should be passed via params with $1..$N placeholders.
2. Placeholder count must equal params length (validated from prepared-statement metadata, not SQL text scanning).
3. Count/type validation failures return error_code: "invalid_params".

Driver-side type mapping (prepared statement parameter OIDs):

• bool -> JSON bool or "true"/"false"
• int2/int4/int8 -> JSON integer or numeric string
• float4/float8/numeric -> JSON number or numeric string
• json/jsonb -> JSON object/array/scalar
• others -> text form (string preferred)

Unsupported:

• :name interpolation
• SQL string template expansion by client-side substitutions

CLI mapping notes:

• --param N=value maps to this params array
• in psql mode, numeric -v N=value may be translated to params[N]

config

Partial runtime config update. Echoes full config afterward.

Session connection shape supports:

• dsn_secret
• conninfo_secret
• host
• port
• user
• dbname
• password_secret

TLS settings supplied in dsn_secret or conninfo_secret (for example sslmode=require) are honored by the PostgreSQL driver.

CLI translation notes:

• agent-first mode uses direct agent-first flags (--dsn-secret, --host, …)
• psql mode may translate legacy flags (-h, -p, -U, -d, -c, -f) into these same canonical fields

cancel

Cancel an in-flight query by id.

{"code":"cancel","id":"q-123"}

When the database connection is already established, afpsql sends a PostgreSQL server-side cancel request before aborting local output handling. Cancellation is still race-prone: a query may finish normally before the cancel request is processed.

ping

Health check.

{"code":"ping"}

close

Graceful shutdown.

{"code":"close"}

Output (stdout)

result

Small result returned inline.

result_start

Start of streamed result.

result_rows

One streamed row batch.

result_end

End of streamed result.

sql_error

Database execution error.

error

Client/runtime/protocol error.

Canonical error_code values:

• invalid_request
• invalid_params
• connect_failed
• result_too_large
• cancelled

Other output codes

log event fields:

• event (e.g. query.result, query.error, query.sql_error)
• request_id (optional)
• session (optional)
• error_code (optional)
• command_tag (optional)
• trace

Startup log events include parsed args, redacted config, and selected redacted environment fallback fields. They intentionally omit raw argv. Bind values are summarized as param_count, not logged as plaintext.

log category matching (from config.log / --log):

• empty list disables log events
• all or * enables all categories
• exact match (query.result)
• group prefix match (query -> query.*)

Runtime Safety Limits

Pipe mode applies hard protocol limits before executing a request:

• max JSONL line: 1 MiB
• max SQL text: 1 MiB
• max params per query: 65,535
• max concurrent in-flight queries: 64

Environment Fallback

Optional runtime fallback variables:

• AFPSQL_DSN_SECRET
• AFPSQL_CONNINFO_SECRET
• AFPSQL_HOST
• AFPSQL_PORT
• AFPSQL_USER
• AFPSQL_DBNAME
• AFPSQL_PASSWORD_SECRET

Standard PostgreSQL environment fallback (lower precedence):

• PGHOST
• PGPORT
• PGUSER
• PGDATABASE

Example: Small Result

Input:

{"code":"query","id":"q1","sql":"select 1 as n"}

Output:

{"code":"result","id":"q1","command_tag":"ROWS 1","columns":[{"name":"n","type":"int4"}],"rows":[{"n":1}],"row_count":1,"trace":{"duration_ms":2}}

Example: Streamed Result

Input:

{"code":"query","id":"q2","sql":"select * from big_table where id > $1","params":[100],"options":{"stream_rows":true,"batch_rows":1000}}

Output:

{"code":"result_start","id":"q2","columns":[{"name":"id","type":"int8"},{"name":"name","type":"text"}]}
{"code":"result_rows","id":"q2","rows":[{"id":101,"name":"a"},{"id":102,"name":"b"}],"rows_batch_count":2}
{"code":"result_end","id":"q2","command_tag":"ROWS 200000","trace":{"duration_ms":443,"row_count":200000,"payload_bytes":34199211}}