Send Feedback
Skip to content

pgwire Configuration and API

This page describes the configuration options available when launching the pgwire process, supported query syntax, and connection parameters. Use this page when tuning your integration or debugging client compatibility.

Command-line flags

Flag Description Example
-T <secs> Connection timeout in seconds. If set to 0, connections never timeout. -T 30
-I <ip> Interface to bind to. Defaults to all interfaces (0.0.0.0). -I 127.0.0.1
-v Enables verbose logging (printed to stdout/stderr). -v
<port> Port for pgwire to listen on. 5434
<kdb_host> IP address of the q process host 10.0.2.2
<kdb_port> Port that q is listening on 5001

Note

You must provide the listen port, kdb host, and kdb port as positional arguments, in that order.

Security best practices

While pgwire is intended for internal or developer use, here are a few recommendations for improving security in production setups:

  • Bind to localhost if using on a single machine: use -I 127.0.0.1 to avoid exposing pgwire to the network.
  • Use a secure reverse proxy (for example, nginx or stunnel) if you need TLS termination or access control.
  • Monitor logs: use -v during development to trace connection activity.

How pgwire translates queries

Internally, pgwire relays SQL queries to the q process using .s.init[], which parses the SQL string into an equivalent q expression. For example:

SELECT sym, price FROM trade WHERE sym = 'AAPL'

is passed to the q engine as a string and evaluated using .s.spg. This means:

  • Queries are interpreted — not compiled.
  • All logic executes in the q process.
  • Only basic ANSI SQL is supported (for example, SELECT, WHERE, LIMIT, ORDER BY).

Return values and errors

When a client submits a query:

  • Results are returned as PostgreSQL-compatible tabular rows.
  • If parsing fails or the query is malformed, pgwire returns a SQL-level error message to the client.
  • Errors are not retried and do not propagate backtraces; use the query logging mechanism (see examples page) to capture failures server-side.

Logging and observability

  • Standard output and error are used for logs when -v is enabled.
  • No file-based logging is performed by default.
  • To monitor activity in production, redirect logs to systemd/journalctl or container logs.

Next steps: