pgtui

library1.7.0jsnpmunverified

pgtui is a CLI tool for viewing and dumping PostgreSQL schemas into a readable directory structure. It generates TypeScript model definitions and directory-based schema representations from a live PostgreSQL connection. The current stable version is 1.7.0, released on an irregular cadence. It differentiates itself from pg_dump by producing human-readable and navigable output, and by integrating with Docker for containerized environments. Useful for documentation, migration reviews, and type generation.

database devops

npm install pgtui

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGTUI

pgtui

databasejavascriptv1.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pgtui (CLI)

✓ npm install -g pgtui pgtui dump-to-dir

✗ npm install pgtui npx pgtui (works but not CLI preferred)

pgtui is a CLI tool; no JavaScript imports. Use global or devDependency for CLI usage.

Docker image

✓ docker run -e PGHOST=... seveibar/pgtui

✗ docker run seveibar/pgtui (missing env vars)

Docker usage requires connection environment variables or volume mounts.

Install pgtui globally or as devDep, then connect to a Postgres database to view schema interactively or dump it to files. Shows basic CLI usage for three main commands.

npm install -g pgtui # View interactive schema pgtui --host localhost --user postgres --password secret --database mydb # Dump schema to directory pgtui dump-to-dir --host localhost --user postgres --password secret --database mydb --output ./db-structure # Generate TypeScript models pgtui dump-typescript-models --host localhost --user postgres --password secret --database mydb --output ./models

Debug

Known issues

gotchaCLI does not read .env files; all connection parameters must be passed via command line flags or environment variables.

fix

Use environment variables PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE or pass flags --host, --port, --user, --password, --database.

affects: >=0.0.0

gotchaInteractive mode (no command) currently displays schema in terminal but may not support all terminals; requires TTY.

fix

Use dump-to-dir for non-interactive environments like CI.

affects: >=0.0.0

gotchaDocker image defaults to using host.docker.internal if no host provided; may not work on Linux without --add-host.

fix

Explicitly set --host to reachable address or use --add-host host.docker.internal:host-gateway on Linux.

affects: >=0.0.0

Errors

Common errors & fixes

Error: getaddrinfo ENOTFOUND localhost

PostgreSQL host not reachable (e.g., Docker container can't resolve 'localhost').

fix

Use --host host.docker.internal on Docker, or provide actual IP address.

Error: password authentication failed for user "postgres"

Incorrect password or missing password flag.

fix

Pass --password <password> or set PGPASSWORD environment variable.

pgtui: command not found

pgtui not installed globally or not in PATH when using npx.

fix

Run 'npm install -g pgtui' or use 'npx pgtui' from a directory with pgtui as devDependency.

Upgrade

Version history

1.7.0latest on npm

Audit

Dependencies

pgrequiredNode Postgres client for connecting to PostgreSQL

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/seveibar/pgtui ↗

packagepgtui ↗

homepagehttps://github.com/seveibar/pgtui#readme ↗