Getting started

Installation

Global install lets you run pgshell from any directory:

npm install -g pgshell

From source (development)

git clone https://github.com/Foisalislambd/pgshell.git
cd pgshell
npm install
npm run build
node dist/index.js

During development you can use npm run dev for hot reload, or npm link to use the local build as the global pgshell command.

Configuration

PgShell reads a .env file in the directory where you run the command. Keep that in mind when switching projects.

Option 1 — Individual variables

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=your_database

Option 2 — Connection URL

DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

If both URL and individual variables exist, DATABASE_URL takes precedence.

Option 3 — Standard PostgreSQL environment variables

PGUSER=postgres
PGPASSWORD=yourpassword
PGHOST=localhost
PGPORT=5432
PGDATABASE=yourdatabase

Interactive setup and keychain

If you run PgShell without a .env, it can prompt for host, port, user, password, and database—or for a full postgresql:// URI. Passwords can be stored in your OS keychain (Windows Credential Manager, macOS Keychain, or Linux Secret Service). Connection profiles live in ~/.pgshell/config.json; passwords are not stored in plain text.

Cloud and SSL

SSL is enabled automatically when your connection string includes sslmode=require (or similar), or when the host matches common managed-Postgres patterns—for example .amazonaws.com, .supabase.com, .neon.tech, .render.com, .fly.io, or .railway.app.