# 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:
```sql
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:

- Configure and query KDB‑X using the [pgwire quickstart](quickstart.md) guide.
- Go through end-to-end [examples](examples.md).
