psql-extras

CLI extras for Supabase — configure psql service connections and run SQL queries directly against your Supabase database.

Commands

login

Interactively configure a named PostgreSQL service for any generic Postgres server.

npx psql-extras login

You will be prompted for:

• PG service name — a name you choose (e.g. mydb)
• Host — the server hostname
• Port — defaults to 5432
• Database name — defaults to postgres
• Username — defaults to postgres
• Password

login-supabase

Interactively configure a named PostgreSQL service. Writes connection details to ~/.pg_service.conf and the password to ~/.pgpass.

npx psql-extras login-supabase

You will be prompted for:

• PG service name — a name you choose (e.g. supabase)
• Connection method — Transaction Pooler (port 6543, IPv4-compatible) or Direct Connection (port 5432, requires IPv4 add-on)
• Project ref — auto-detected from supabase/.temp/project-ref if available
• Host — e.g. aws-0-us-east-1.pooler.supabase.com (pooler) or db.<ref>.supabase.co (direct)
• Port, database name, username, password

Find connection details on supabase.com → your project → Connect → Connection String → URI → Primary Database.

After login, connect directly with psql:

psql service=supabase -c 'SELECT 1'

If psql is not installed: sudo apt-get install -y postgresql-client

execute <service> '<SQL>'

Run a SQL query against a named service from ~/.pg_service.conf.

npx psql-extras execute supabase 'SELECT * FROM auth.users LIMIT 10'

Results are printed as a formatted table by default.

Flags:

| Flag | Description | |------|-------------| | --json | Output results as JSON instead of a table |

npx psql-extras execute supabase 'SELECT id, email FROM auth.users' --json

Prerequisites

• Node.js (ESM support required — Node 18+)
• psql for direct psql usage: sudo apt-get install -y postgresql-client

Installation

Available on npmjs.com. No install required — run directly with npx:

npx psql-extras login           # generic Postgres
npx psql-extras login-supabase  # Supabase-specific

Or install globally:

npm install -g psql-extras

Files written

| File | Purpose | |------|---------| | ~/.pg_service.conf | Named connection entries read by psql and this CLI | | ~/.pgpass | Passwords for those connections (chmod 600) | | ~/.config/psql-extras/config.json | Stores the active service name |