psql and PostgreSQL protocol connections

Connect to your database with existing PostgreSQL tools. Use your login session, or issue credentials for a system.

The fastest way

runlot pg shell

This command finds psql and connects to your database. Anything you pass after -- goes straight to psql.

runlot pg shell -- -c "select count(*) from posts"

The password is passed through the PGPASSWORD environment variable, because command-line arguments are visible to other users on the same machine via ps.

Connecting through a local port

Port forwarding is convenient for GUI clients and other tools.

runlot port-forward

Forwarding 127.0.0.1:15432 to the me/my-app database.
Connect with psql "postgresql://…@127.0.0.1:15432/…". Press Ctrl-C to stop.

runlot port-forward --port 5555 --listen 127.0.0.1
runlot port-forward --port 0      # picks an available port automatically

The password never reaches your local machine. Port forwarding uses your runlot login session. The CLI only receives connection details (host, port, database name); authentication happens at the front using your login session. If the token expires or you are removed from the organization, the next connection is rejected.

Connecting directly from outside

Where runlot login is not available — an external BI tool, or an app running on another hosting environment — issue credentials with pg token.

postgresql://<user>:<password>@<project>--<org>.wire.runlot.app:5433/<database>?sslmode=require

The port number is 5433. The hostname carries the project and organization joined by --; that is how the front knows which project's database to open before any credentials are sent. runlot pg connect prints the exact value.

TLS

In libpq, sslmode=require means encryption only, with no certificate verification. To verify the certificate as well, point at a CA directory.

runlot pg shell --ca-dir ./ca      # or RUNLOT_CA_DIR

SNI is always required, whether or not you verify the certificate. The front uses SNI to determine the target project, so turning SNI off makes the connection impossible.

Driver compatibility

Today, only drivers that use the text result format can connect. That covers psql, node-postgres, and psycopg (default settings). Drivers that require the binary result format — pgx, JDBC, Npgsql, asyncpg — are currently rejected with a 0A000 error. The engine implementation is complete; the rollout to production nodes is still pending.

Binary parameters will remain unsupported. They are a separate feature from the result format, and until they are supported they are rejected explicitly.

Authentication methods

The front identifies the project from SNI and then completes authentication immediately after the connection starts. The following credentials are available.

For	Credential	Where it is used
Users	`runlot login` session	`runlot port-forward`, dashboard SQL editor
Systems	Password in the connection string	External BI tools, apps on other hosting environments

Any runlot_* startup parameters sent by the client are stripped at the front, and only verified role information is added back. A client cannot forge a role.