PostgreSQL (`@hesed/psql`)#

The @hesed/psql plugin lets you query and manage PostgreSQL databases from the terminal. It is preinstalled with Sidekick.

Prerequisites#

A PostgreSQL server (local or remote)
Database credentials with appropriate permissions

Step 1: Gather your database credentials#

You'll need the following from your database administrator or cloud provider:

Field	Example
Host	`db.yourcompany.com` or `localhost`
Port	`5432` (default)
Database	`production_db`
Username	`sdkck_user`
Password	your database password

Security tip: For production environments, use a read-only database user to limit exposure if credentials are ever compromised.

Step 2: Configure auth in Sidekick#

sdkck psql auth add

PostgreSQL add authentication

You will be prompted for the host, port, database name, username, and password.

Step 3: Verify the connection#

sdkck psql auth test

Example commands#

# Run a query
sdkck psql query "SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '7 days'"

# List tables in the connected database
sdkck psql tables

# Describe a table schema
sdkck psql describe-table orders --format json --profile prod

Discover all commands#

sdkck help psql

Troubleshooting#

Connection refused

Verify the host allows connections from your IP
Confirm the port is correct (default is 5432)
For managed databases (e.g., Supabase, Neon, AWS RDS), check that your IP is allowlisted

Authentication failed

Double-check the username and password
Ensure the user has CONNECT and SELECT privileges on the target database

SSL required

Many cloud PostgreSQL providers require SSL. If you see SSL connection is required, your provider may offer a connection string with ?sslmode=require — check the Sidekick psql help for SSL options:
```
sdkck psql auth add --help
```

PostgreSQL (@hesed/psql)#