pgwire Quickstart
This guide walks through how to get pgwire running in just a few steps. It also includes tips for verification and troubleshooting.
Step 1: start a KDB-X process with sql support
You need a running KDB-X instance. Call .s.init[] and make sure there's a database available.
q -p 5001
.s.init[]
\l databasefile
Step 2: run pgwire
Use the following command structure:
pg [-T timeout] [-I interface] [-v] listen_port kdb_host kdb_port
Example parameters
| Parameter | Description | Example |
|---|---|---|
listen_port |
Local port to expose pgwire | 5434 |
kdb_host |
Host IP address for the KDB-X instance | 10.0.2.2 |
kdb_port |
Port the KDB-X instance is listening on | 5001 |
-T |
Optional: timeout in seconds | 0 (default) |
-I |
Listening interface | 127.0.0.1 |
-v |
Enable verbose logging | (optional) |
Windows
pg 5434 10.0.2.2 5001
Macos
./pgmac 5434 10.0.2.2 5001
Note
Before attempting to connect, ensure that you run .s.init[] and that the database is available at the specified host/port.
Step 3: verify if pgwire is working
You can check that pgwire is accepting connections using a PostgreSQL client like psql:
psql -h 127.0.0.1 -p 5434 -U postgres
If the server accepts the connection, you're ready to query.
Note
If you don’t have psql installed, use telnet or nc to confirm the port is open.
Common troubleshooting tips
| Issue | Suggested Fix |
|---|---|
| Connection refused | Ensure pgwire is running and listening on the correct port |
| Queries fail or hang | Call .s.init[] and verify that the database is ready |
| BI tool sees no tables | Ensure the schema is loaded and .s.init[] is correctly parsing it |
| pgwire exits immediately | Check for invalid arguments or missing database process |
| Windows firewall blocking port | Allow access to pgwire via Windows Defender Firewall |
Development setup tip
You can also test pgwire in a local containerized environment using Docker or Kubernetes, by exposing the necessary ports and pointing pgwire to a running q container with .s.init[]. This makes testing more portable and scriptable.
Next steps:
- Go through end-to-end examples.
- Check out a list of pgwire settings, functions, supported SQL syntax, and tuning parameters.