pgtoolkit.ctl

Note

This module requires Python 3.8 or higher.

API Reference

class pgtoolkit.ctl.PGCtl(bindir: str | ~pathlib._local.Path | None = None, *, run_command: ~pgtoolkit.ctl.CommandRunner = <function run_command>)[source]

Handler for pg_ctl commands.

Parameters:

  • bindir – location of postgresql user executables; if not specified, this will be determined by calling pg_config if that executable is found in $PATH.

  • run_command – callable implementing CommandRunner that will be used to execute pg_ctl commands.

Raises:

OSError if either pg_config or pg_ctl is not available.

controldata(datadir: Path | str) → dict[str, str][source]

Run the pg_controldata command and parse the result to return controldata as dict.

Parameters:

datadir – Path to database storage area

init(datadir: Path | str, **opts: str | Literal[True]) → CompletedProcess[source]

Initialize a PostgreSQL cluster (initdb) at datadir.

Parameters:

  • datadir – Path to database storage area

  • opts – extra options passed to initdb

Options name passed as opts should be underscore’d instead dash’ed and flag options should be passed a boolean True value; e.g. auth_local="md5", data_checksums=True for pg_ctl init -o '--auth-local=md5 --data-checksums'.

reload(datadir: Path | str) → CompletedProcess[source]

Reload a PostgreSQL cluster.

Parameters:

datadir – Path to database storage area

restart(datadir: Path | str, *, mode: str | None = None, wait: bool | int = True, **opts: str | Literal[True]) → CompletedProcess[source]

Restart a PostgreSQL cluster.

Parameters:

  • datadir – Path to database storage area

  • mode – Shutdown mode, can be “smart”, “fast”, or “immediate”

  • wait – Wait until operation completes, if an integer value is passed, this will be used as –timeout value.

  • opts – extra options passed to postgres command.

Options name passed as opts should be underscore’d instead of dash’ed and flag options should be passed a boolean True value; e.g. F=True, work_mem=123 for pg_ctl restart -o '-F --work-mem=123'.

start(datadir: Path | str, *, wait: bool | int = True, logfile: Path | str | None = None, **opts: str | Literal[True]) → CompletedProcess[source]

Start a PostgreSQL cluster.

Parameters:

  • datadir – Path to database storage area

  • wait – Wait until operation completes, if an integer value is passed, this will be used as –timeout value.

  • logfile – Optional log file path

  • opts – extra options passed to postgres command.

Options name passed as opts should be underscore’d instead of dash’ed and flag options should be passed a boolean True value; e.g. F=True, work_mem=123 for pg_ctl start -o '-F --work-mem=123'.

status(datadir: Path | str) → Status[source]

Check PostgreSQL cluster status.

Parameters:

datadir – Path to database storage area

Returns:

Status value.

stop(datadir: Path | str, *, mode: str | None = None, wait: bool | int = True) → CompletedProcess[source]

Stop a PostgreSQL cluster.

Parameters:

  • datadir – Path to database storage area

  • mode – Shutdown mode, can be “smart”, “fast”, or “immediate”

  • wait – Wait until operation completes, if an integer value is passed, this will be used as –timeout value.

class pgtoolkit.ctl.AsyncPGCtl(bindir: Path, run_command: AsyncCommandRunner)[source]

Async handler for pg_ctl commands.

See PGCtl for the interface.

async classmethod get(bindir: str | ~pathlib._local.Path | None = None, *, run_command: ~pgtoolkit.ctl.AsyncCommandRunner = <function asyncio_run_command>) → AsyncPGCtl[source]

Construct an AsyncPGCtl instance from specified or inferred ‘bindir’.

Parameters:

  • bindir – location of postgresql user executables; if not specified, this will be determined by calling pg_config if that executable is found in $PATH.

  • run_command – callable implementing CommandRunner that will be used to execute pg_ctl commands.

Raises:

OSError if either pg_config or pg_ctl is not available.

class pgtoolkit.ctl.Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

PostgreSQL cluster runtime status.

not_running = 3

Not running

running = 0

Running

unspecified_datadir = 4

Unspecified data directory

pgtoolkit.ctl.run_command(args: Sequence[str], *, check: bool = False, **kwargs: Any) → CompletedProcess[source]

Default CommandRunner implementation for PGCtl using subprocess.run().

async pgtoolkit.ctl.asyncio_run_command(args: Sequence[str], *, capture_output: bool = False, check: bool = False, **kwargs: Any) → CompletedProcess[source]

Default AsyncCommandRunner implementation for AsyncPGCtl using asyncio.subprocess().

class pgtoolkit.ctl.CommandRunner(*args, **kwargs)[source]

Protocol for run_command callable parameter of PGCtl.

The text mode, as defined in subprocess, must be used in implementations.

Keyword arguments are expected to match that of subprocess.run().

__call__(args: Sequence[str], *, capture_output: bool = False, check: bool = False, **kwargs: Any) → CompletedProcess[source]

Call self as a function.

class pgtoolkit.ctl.AsyncCommandRunner(*args, **kwargs)[source]

Protocol for run_command callable parameter of PGCtl.

The text mode, as defined in subprocess, must be used in implementations.

Keyword arguments are expected to match that of subprocess.run().

async __call__(args: Sequence[str], *, capture_output: bool = False, check: bool = False, **kwargs: Any) → CompletedProcess[source]

Call self as a function.