Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ For more details:
--single-connection Do not use a separate connection for completions.
-v, --version Version of pgcli.
-d, --dbname TEXT database name to connect to.
--env-file PATH Read a database URL from a local .env file.
--pgclirc FILE Location of pgclirc file.
-D, --dsn TEXT Use DSN configured into the [alias_dsn] section
of pgclirc file.
Expand All @@ -111,6 +112,30 @@ For more details:

``pgcli`` also supports many of the same `environment variables`_ as ``psql`` for login options (e.g. ``PGHOST``, ``PGPORT``, ``PGUSER``, ``PGPASSWORD``, ``PGDATABASE``).

To connect using a URL in a local project file, opt in explicitly::

# .env (or .env.local)
DB_URL='postgresql://user:password@localhost:5432/app_db'

$ pgcli --env-file .env
$ pgcli --env-file .env.local --ping

The first non-empty variable wins, in this order: ``DATABASE_URL``,
``DATABASE_URI``, ``DB_URL``, ``DB_URI``. Values must be ``postgres://`` or
``postgresql://`` URLs. Quoted values, comments, and ``export`` prefixes are
supported. Variable references such as ``${PASSWORD}`` are kept literal.

Explicit connection arguments (``DBNAME``, ``USERNAME``, ``-d``, ``-h``, ``-p``,
``-U``/``-u``, or ``-D``) select the usual connection instead of the file URL.
Otherwise, the file URL takes precedence over environment defaults such as
``PGDATABASE`` and ``DSN``. The usual libpq defaults, including ``PGSERVICE``,
still apply to the URL. Other options, including ``--ssh-tunnel``,
``--list``, and ``--ping``, work as with a URL passed on the command line.

Only the named file is read; pgcli does not search parent directories or load
``.env`` automatically. An unreadable file, missing URL, or invalid URL produces
an error. The file does not export any variables into the process environment.

The SSL-related environment variables are also supported, so if you need to connect a postgres database via ssl connection, you can set set environment like this:

::
Expand Down
3 changes: 3 additions & 0 deletions changelog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ Upcoming

Features:
---------
* Add ``--env-file PATH`` to opt in to reading a database URL from a local
``.env`` file. Explicit connection arguments take precedence over the file,
which takes precedence over environment defaults.
* Add ``\\cd`` and ``\\ls`` filesystem commands, with path completion for
filesystem-aware commands including ``\\e``, ``\\i``, ``\\log-file``, and ``\\o``.
* Add a ``\service`` prompt token for connections made using ``service=...``
Expand Down
6 changes: 5 additions & 1 deletion pgcli-completion.bash
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ _pgcli()
_pg_databases
return 0
;;
--env-file)
_filedir
return 0
;;
--help|-v|--version|-p|--port|-R|--row-limit)
# all other arguments are noop with these
return 0
Expand All @@ -57,7 +61,7 @@ _pgcli()
--*)
# return list of available options
COMPREPLY=( $( compgen -W '--host --port --user --password --no-password
--single-connection --version --dbname --pgclirc --dsn
--single-connection --version --dbname --env-file --pgclirc --dsn
--row-limit --help' -- "$cur" ) )
[[ $COMPREPLY == *= ]] && compopt -o nospace
return 0
Expand Down
49 changes: 45 additions & 4 deletions pgcli/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
from cli_helpers.utils import strip_ansi
from .explain_output_formatter import ExplainOutputFormatter
import click
from click.core import ParameterSource
import sqlparse
from sqlparse import tokens as sqlparse_tokens
import tzlocal
Expand All @@ -35,6 +36,7 @@
import setproctitle
except ImportError:
setproctitle = None
from dotenv import dotenv_values
from prompt_toolkit.completion import DynamicCompleter, ThreadedCompleter
from prompt_toolkit.enums import DEFAULT_BUFFER, EditingMode
from prompt_toolkit.shortcuts import PromptSession, CompleteStyle
Expand Down Expand Up @@ -82,7 +84,7 @@

from getpass import getuser

from psycopg import DatabaseError, OperationalError, InterfaceError, Notify
from psycopg import DatabaseError, OperationalError, InterfaceError, Notify, ProgrammingError
from psycopg.conninfo import make_conninfo, conninfo_to_dict
from psycopg.errors import Diagnostic

Expand Down Expand Up @@ -1584,6 +1586,28 @@ def echo_via_pager(self, text, color=None):
click.echo_via_pager(text, color)


def read_env_database(env_file):
"""Read a database URL without exporting unrelated project settings."""
try:
with open(env_file, encoding="utf-8-sig") as stream:
values = dotenv_values(stream=stream, interpolate=False)
except (OSError, UnicodeError) as exc:
raise click.BadParameter("Could not read the environment file.", param_hint="--env-file") from exc

for name in ("DATABASE_URL", "DATABASE_URI", "DB_URL", "DB_URI"):
value = values.get(name)
if value and value.strip():
# Do not echo the URL: it may contain credentials.
if not value.startswith(("postgres://", "postgresql://")):
raise click.BadParameter(f"{name} must be a PostgreSQL URL.", param_hint="--env-file")
try:
conninfo_to_dict(value)
except ProgrammingError as exc:
raise click.BadParameter(f"{name} contains an invalid PostgreSQL URL.", param_hint="--env-file") from exc
return value
raise click.BadParameter("No non-empty DATABASE_URL, DATABASE_URI, DB_URL or DB_URI found.", param_hint="--env-file")


@click.command()
# Default host is '' so psycopg can default to either localhost or unix socket
@click.option(
Expand Down Expand Up @@ -1640,6 +1664,11 @@ def echo_via_pager(self, text, color=None):
)
@click.option("-v", "--version", is_flag=True, help="Version of pgcli.")
@click.option("-d", "--dbname", "dbname_opt", help="database name to connect to.")
@click.option(
"--env-file",
type=click.Path(exists=True, dir_okay=False, readable=True),
help="Read a database URL from this local .env file. Explicit connection arguments take precedence.",
)
@click.option(
"--pgclirc",
default=config_location() + "config",
Expand Down Expand Up @@ -1758,7 +1787,9 @@ def echo_via_pager(self, text, color=None):
)
@click.argument("dbname", default=lambda: None, envvar="PGDATABASE", nargs=1)
@click.argument("username", default=lambda: None, envvar="PGUSER", nargs=1)
@click.pass_context
def cli(
ctx,
dbname,
username_opt,
host,
Expand Down Expand Up @@ -1789,6 +1820,7 @@ def cli(
force_destructive: bool,
input_files: tuple,
connect_timeout: int | None,
env_file,
):
if version:
print("Version:", __version__)
Expand Down Expand Up @@ -1838,6 +1870,15 @@ def cli(
)
sys.exit(1)

env_database = None
if env_file and not any(
ctx.get_parameter_source(name) == ParameterSource.COMMANDLINE
for name in ("dbname", "dbname_opt", "username", "username_opt", "host", "port", "dsn")
):
env_database = read_env_database(env_file)
# An explicitly selected file takes precedence over environment defaults.
dsn = ""

pgcli = PGCli(
prompt_passwd,
never_prompt,
Expand Down Expand Up @@ -1866,12 +1907,12 @@ def cli(
if dbname_opt and dbname:
# work as psql: when database is given as option and argument use the argument as user
username = dbname
database = dbname_opt or dbname or ""
database = env_database or dbname_opt or dbname or ""
user = username_opt or username
service = None
if database.startswith("service="):
service = database[8:]
elif os.getenv("PGSERVICE") is not None:
elif env_database is None and os.getenv("PGSERVICE") is not None:
service = os.getenv("PGSERVICE")
# because option --ping, --list or -l are not supposed to have a db name.
# A connection string is not a db name though: a URI or a key=value conninfo
Expand Down Expand Up @@ -2022,7 +2063,7 @@ def echo_error(msg: str):

pgcli.logger.debug(
"Launch Params: \n\tdatabase: %r\tuser: %r\thost: %r\tport: %r",
database,
"<from --env-file>" if env_database else database,
user,
host,
port,
Expand Down
5 changes: 3 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ requires-python = ">=3.10"
dependencies = [
"pgspecial>=2.0.0",
# Click 8.1.8 through 8.3.0 have broken pager invocation for multi-argument PAGER values, which causes behave test failures.
"click >= 4.1, != 8.1.8, != 8.2.*, != 8.3.0, < 9",
"click >= 8.0, != 8.1.8, != 8.2.*, != 8.3.0, < 9",
"Pygments>=2.0", # Pygments has to be Capitalcased.
# We still need to use pt-2 unless pt-3 released on Fedora32
# see: https://github.com/dbcli/pgcli/pull/1197
Expand All @@ -33,6 +33,7 @@ dependencies = [
"psycopg-binary >= 3.0.14; sys_platform == 'win32'",
"sqlparse >=0.3.0,<0.7",
"configobj >= 5.0.6",
"python-dotenv >= 1.0",
"cli_helpers[styles] >= 2.15.2",
# setproctitle is used to mask the password when running `ps` in command line.
# But this is not necessary in Windows since the password is never shown in the
Expand Down Expand Up @@ -134,4 +135,4 @@ exclude = [
[tool.pytest.ini_options]
minversion = "6.0"
addopts = "--capture=sys --showlocals -rxs"
testpaths = ["tests"]
testpaths = ["tests"]
Loading
Loading