pgcli

library4.4.0pypypiunverified

pgcli is a Python package that serves as an interactive command-line interface for the PostgreSQL database server. It enhances the standard PostgreSQL experience with features like auto-completion, syntax highlighting, smart-completion, and extensive support for psql-like back-slash commands. The project is actively maintained with a consistent release cadence, with version 4.4.0 being the current stable release.

database

pip install pgcli

package ↗homepage ↗

INSTALL

IMPORT

SIG · PGCLI

pgcli

databasepythonv4.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Connect to a local PostgreSQL database named 'my_database' using the current system username. You will be prompted for a password if required. Alternatively, use a connection URL: `pgcli postgresql://user:password@host:port/dbname`.

pgcli -h localhost -p 5432 -U $(whoami) -d my_database

pgcli --version

Debug

Known issues

breakingPython 3.8 and older are no longer supported. Version 4.0.0 dropped support for Python <3.8, and version 4.2.0 dropped support for Python <3.9.

fix

Upgrade your Python environment to Python 3.9 or newer. Ensure your virtual environment uses a supported Python version.

affects: >=4.0.0

gotchaInstallation on Linux often requires system-level development packages for `libpq` and Python (`python-dev`, `libpq-dev`, or equivalents like `postgresql-devel`, `python-devel`). Without these, the `psycopg` adapter build may fail.

fix

Install the necessary system packages, e.g., `sudo apt-get install python3-dev libpq-dev` (Debian/Ubuntu) or `sudo yum install python3-devel postgresql-devel` (RHEL/CentOS/Fedora) before running `pip install pgcli`.

affects: All versions

gotchaConnection issues can arise due to network proxies (e.g., Zscaler) interfering with direct TCP connections or SSL certificate validation. Errors like 'SSL routines:ssl3_get_server_certificate:certificate verify failed' are common.

fix

Ensure the proxy's root certificate is installed in your system's trust chain. Verify outbound firewall rules allow PostgreSQL traffic (port 5432 by default). Consider using an SSH tunnel if direct access is restricted.

affects: All versions

gotchaStoring passwords in shell history or inadequately permissioned `.pgpass` files (e.g., `chmod 644`) poses a security risk. Environment variables (like `PGPASSWORD`) can also be inspected.

fix

Always set `.pgpass` file permissions strictly (e.g., `chmod 600`). Avoid storing production passwords directly in shell history. Use secure credential management systems or rely on interactive password prompts where appropriate.

affects: All versions

gotchaThe interactive nature and ease of use can inadvertently lead to executing destructive SQL commands. This is a common footgun in any direct database CLI.

fix

Utilize `pgcli`'s configuration options like `destructive_statements_require_transaction` and `destructive_warning` (introduced in 4.4.0) to prompt for confirmation before executing potentially damaging queries.

affects: All versions

Errors

Common errors & fixes

could not connect to server: Connection refused Is the server running on host "localhost" (...) and accepting TCP/IP connections on port 5432?

pgcli is unable to establish a connection to the PostgreSQL server, often due to the server not running, incorrect host/port, or firewall restrictions preventing the connection.

fix

Ensure the PostgreSQL server is running, verify the host and port are correct (e.g., `pgcli -h <host> -p <port> -U <user> <dbname>`), and check any local or network firewalls that might be blocking port 5432 (or your configured port).

ImportError: no pq wrapper available. Attempts made: - couldn't import psycopg 'c' implementation: No module named 'psycopg_c' - couldn't import psycopg 'binary' implementation: No module named 'psycopg_binary' - couldn't import psycopg 'python' implementation: libpq library not found

This error occurs because the underlying PostgreSQL adapter (psycopg2 or psycopg) that pgcli uses cannot find the necessary client libraries (libpq) or its C/binary components during installation or runtime.

fix

Install the PostgreSQL development libraries for your operating system (e.g., `sudo apt-get install libpq-dev python3-dev` on Debian/Ubuntu, `sudo yum install postgresql-devel python3-devel` on RHEL/CentOS, or `brew install postgresql` and `xcode-select --install` on macOS), then reinstall pgcli with `pip install --no-cache-dir pgcli`.

FATAL: password authentication failed for user "your_username"

pgcli successfully connected to the PostgreSQL server, but the username or password provided is incorrect, or the user lacks permission to connect to the specified database.

fix

Verify the username and password are correct. You can explicitly provide them using `pgcli -U <correct_username> -W <dbname>` (which will prompt for a password) or ensure your `~/.pgpass` file is correctly configured for passwordless access.

command not found: pgcli

The `pgcli` executable is not found in your system's PATH, typically meaning it wasn't installed correctly, or the directory where pip installs executables is not included in your PATH environment variable.

fix

First, ensure pgcli is installed by running `pip install pgcli`. If it is, locate the `pgcli` executable (e.g., `which pgcli` or `find / -name pgcli` for a global search) and add its directory to your system's PATH environment variable. Alternatively, use `python3 -m pgcli` to run it directly via the Python module.

SSL routines:ssl3_get_server_certificate:certificate verify failed

The client (pgcli) is unable to verify the SSL certificate presented by the PostgreSQL server, often due to an untrusted certificate authority, an expired certificate, or an intermediary like a proxy (e.g., Zscaler) intercepting the connection with its own certificate.

fix

Install the server's root SSL certificate into your system's trust store. If using a proxy, import the proxy's root certificate. Alternatively, for testing, you might be able to disable SSL verification with an option in pgcli's configuration or connection string (though not recommended for production).

Upgrade

Version history

4.4.0latest on PyPI · released Dec 24, 2025

Audit

Dependencies

PostgreSQLrequiredRequired for connecting to a PostgreSQL database. The CLI client interacts with a running PostgreSQL instance.

python-dev / libpq-devrequiredSystem-level development headers for Python and PostgreSQL's C library (libpq) are required to build the `psycopg` or `psycopg-binary` adapter, especially on Linux.

psycopg / psycopg-binaryrequiredThe core PostgreSQL adapter. `psycopg` for Linux/macOS, `psycopg-binary` for Windows.

prompt_toolkitrequiredCore library providing interactive terminal features like auto-completion and syntax highlighting.

keyringoptionalOptional, for integrating with system keyring services to securely store database credentials.

sshtunneloptionalOptional, for establishing SSH tunnels to connect to remote PostgreSQL instances.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pgcli/ ↗

homepagehttps://pgcli.com ↗