pgdev

PostgreSQL and NpgsqlRest Development Toolchain.

A CLI tool with a TUI experience for managing PostgreSQL client tools and NpgsqlRest in your development environment.

Note: This project is under active development. Commands, options, and behavior are subject to change.

Requirements

• Bun runtime

Install

bun install -g pgdev

Update

pgdev update

Uninstall

bun uninstall -g pgdev

Commands

pgdev config

Interactive TUI dashboard for configuring your development environment. This is the main entry point for all configuration. Aliases: pgdev init, pgdev setup.

Sections:

• NpgsqlRest — detect or install NpgsqlRest (npm, bun, standalone binary, or Docker)
• PostgreSQL Tools — detect or install psql, pg_dump, pg_restore (Homebrew, apt, apk, dnf)
• NpgsqlRest Config Files — create and manage NpgsqlRest JSON config files (production, development, local) with a TUI editor for connection strings, config settings, and more
• pgdev Environment — configure env file, database connection, and project directories (migrations, routines, tests, schemas)

pgdev exec <sql>

Execute a SQL command via psql using the configured connection.

pgdev exec "SELECT version()"

pgdev psql

Open an interactive psql session using the configured connection.

pgdev sync

Dump database schema to the configured migrations directory.

pgdev update

Update pgdev to the latest published version.

pgdev <custom>

Run custom NpgsqlRest commands defined in pgdev.toml under [npgsqlrest.commands]. For example, if your config has:

[npgsqlrest.commands]
dev = "./config/production.json --optional ./config/development.json"

Then pgdev dev will launch NpgsqlRest with those arguments.

Options

| Option | Description | |--------|-------------| | --version, -v | Show versions of pgdev, NpgsqlRest, PostgreSQL tools, and connected server | | --help, -h | Show help message |

Configuration

pgdev uses two TOML config files in your project root:

| File | Purpose | Git | |------|---------|-----| | pgdev.toml | Shared project config | Commit | | pgdev.local.toml | Personal overrides (tool paths, credentials) | Gitignore |

Layering: defaults → pgdev.toml → pgdev.local.toml

Running pgdev for the first time creates a pgdev.toml with all available options. The full structure:

# Path to .env file for resolving {ENV_VAR} placeholders in config values
env_file = ""

# Show detailed output during tool detection and updates
verbose = true

# Tool paths — bare command name uses PATH, or set a full path
[tools]
npgsqlrest = "npgsqlrest"
psql = "psql"
pg_dump = "pg_dump"
pg_restore = "pg_restore"

# NpgsqlRest run commands — value is the config file args passed to npgsqlrest CLI
# Example: dev = "./config/production.json --optional ./config/development.json"
[npgsqlrest.commands]
dev = ""
validate = ""
serve = ""
validate-prod = ""

# SQL commands used by pgdev
[commands]
schemas_query = "select nspname::text from pg_namespace ..."

# Database connection for pgdev tools (psql, pg_dump, pg_restore)
# Values support {ENV_VAR} placeholders resolved via env_file above
# To share connection with NpgsqlRest instead, set config_file to a JSON config path
[connection]
host = "{PGHOST}"
port = "{PGPORT}"
database = "{PGDATABASE}"
username = "{PGUSER}"
password = "{PGPASSWORD}"
# config_file = "./config/production.json"
# connection_name = "Default"

# Project directories for SQL source files
# Leave empty to skip; directories are created when first needed
[project]
routines_dir = ""
migrations_dir = ""
tests_dir = ""
schemas = []

Top-level options

| Key | Default | Description | |-----|---------|-------------| | env_file | "" | Path to .env file for resolving {ENV_VAR} placeholders in config values | | verbose | true | Show detailed output (command echoes, full error messages) |

[tools]

Paths to external tools. Use a bare command name to use PATH, or set a full path.

| Key | Default | Description | |-----|---------|-------------| | npgsqlrest | "npgsqlrest" | NpgsqlRest server command | | psql | "psql" | PostgreSQL interactive terminal | | pg_dump | "pg_dump" | PostgreSQL dump utility | | pg_restore | "pg_restore" | PostgreSQL restore utility |

[npgsqlrest.commands]

Custom NpgsqlRest run commands. Each key becomes a pgdev <name> subcommand. The value is the config file arguments passed to the NpgsqlRest CLI.

| Key | Default | Description | |-----|---------|-------------| | dev | "" | Development server command | | validate | "" | Validate config command | | serve | "" | Production serve command | | validate-prod | "" | Validate production config command |

[commands]

SQL commands used internally by pgdev.

| Key | Description | |-----|-------------| | schemas_query | SQL query to list project schemas (used by sync and config) |

[connection]

Database connection for pgdev tools. Two modes:

Independent connection — set host, port, database, username, password directly:

| Key | Default | Description | |-----|---------|-------------| | host | "{PGHOST}" | PostgreSQL host | | port | "{PGPORT}" | PostgreSQL port | | database | "{PGDATABASE}" | Database name | | username | "{PGUSER}" | Username | | password | "{PGPASSWORD}" | Password |

Shared connection — read connection string from a NpgsqlRest JSON config file:

| Key | Description | |-----|-------------| | config_file | Path to NpgsqlRest JSON config file (e.g. "./config/production.json") | | connection_name | Connection string name in the config file (default: "Default") |

[project]

Project directory paths for SQL source files.

| Key | Default | Description | |-----|---------|-------------| | routines_dir | "" | Directory for SQL routines (functions/procedures) | | migrations_dir | "" | Directory for migration scripts | | tests_dir | "" | Directory for SQL test files | | schemas | [] | Schemas used by this project (empty = all non-system schemas) |

License

MIT