PGPM Env

Manage PostgreSQL environment variables with profile support using the pgpm env command.

When to Apply

Use this skill when:

• Setting up environment variables for database connections
• Running commands that need PostgreSQL connection info
• Switching between local Postgres and Supabase profiles
• Deploying PGPM modules with correct database settings
• Running tests or scripts that need database access

Quick Start

Load Environment Variables

eval "$(pgpm env)"

This sets the following environment variables:

• PGHOST=localhost
• PGPORT=5432
• PGUSER=postgres
• PGPASSWORD=password
• PGDATABASE=postgres

Run Command with Environment

pgpm env pgpm deploy --database mydb

This runs pgpm deploy --database mydb with the PostgreSQL environment variables automatically set.

Profiles

Default Profile (Local Postgres)

eval "$(pgpm env)"

Variable	Value
PGHOST	localhost
PGPORT	5432
PGUSER	postgres
PGPASSWORD	password
PGDATABASE	postgres

Supabase Profile

eval "$(pgpm env --supabase)"

Variable	Value
PGHOST	localhost
PGPORT	54322
PGUSER	supabase_admin
PGPASSWORD	postgres
PGDATABASE	postgres

Command Reference

Print Environment Exports

pgpm env                    # Default Postgres profile
pgpm env --supabase         # Supabase profile

Output (for shell evaluation):

export PGHOST="localhost"
export PGPORT="5432"
export PGUSER="postgres"
export PGPASSWORD="password"
export PGDATABASE="postgres"

Execute Command with Environment

pgpm env <command> [args...]
pgpm env --supabase <command> [args...]

Examples:

pgpm env createdb mydb
pgpm env pgpm deploy --database mydb
pgpm env psql -c "SELECT 1"
pgpm env --supabase pgpm deploy --database mydb

Common Workflows

Development Setup

# Start database container
pgpm docker start

# Load environment into current shell
eval "$(pgpm env)"

# Now all commands have database access
createdb myapp
pgpm deploy --database myapp

Running Tests

# Run tests with database environment
pgpm env pnpm test

# Or load into shell first
eval "$(pgpm env)"
pnpm test

PGPM Deployment

# Deploy to a specific database
pgpm env pgpm deploy --database constructive

# Verify deployment
pgpm env pgpm verify --database constructive

Supabase Local Development

# Start Supabase locally (using supabase CLI)
supabase start

# Load Supabase environment
eval "$(pgpm env --supabase)"

# Deploy modules to Supabase
pgpm deploy --database postgres

Shell Integration

Bash/Zsh

Add to your shell profile for automatic loading:

# ~/.bashrc or ~/.zshrc
alias pgenv='eval "$(pgpm env)"'
alias pgenv-supa='eval "$(pgpm env --supabase)"'

Then use:

pgenv          # Load default Postgres env
pgenv-supa     # Load Supabase env

One-liner Commands

# Create database and deploy in one command
pgpm env bash -c "createdb mydb && pgpm deploy --database mydb"

Environment Variables Reference

The pgpm env command sets standard PostgreSQL environment variables that are recognized by:

• psql and other PostgreSQL CLI tools
• Node.js pg library
• PGPM CLI commands
• Any tool using libpq

Variable	Description
PGHOST	Database server hostname
PGPORT	Database server port
PGUSER	Database username
PGPASSWORD	Database password
PGDATABASE	Default database name

Troubleshooting

Issue	Solution
"Connection refused"	Ensure database container is running with pgpm docker start
Wrong database	Check PGDATABASE or specify --database flag
Auth failed	Verify password matches container settings
Supabase not connecting	Ensure Supabase is running on port 54322
Env vars not persisting	Use eval "$(pgpm env)" to load into current shell

References

For related skills:

• Docker container management: See pgpm-docker skill
• Running tests: See pgpm-testing skill