pgtoolkit.ctl
Note
This module requires Python 3.8 or higher.
API Reference
- class pgtoolkit.ctl.PGCtl(bindir: ~pathlib.Path | str | 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 executepg_ctl
commands.
- Raises:
OSError
if eitherpg_config
orpg_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
forpg_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
forpg_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
forpg_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: ~pathlib.Path | str | 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 executepg_ctl
commands.
- Raises:
OSError
if eitherpg_config
orpg_ctl
is not available.
- class pgtoolkit.ctl.Status(value, names=None, *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 forPGCtl
usingsubprocess.run()
.
- async pgtoolkit.ctl.asyncio_run_command(args: Sequence[str], *, capture_output: bool = False, check: bool = False, **kwargs: Any) CompletedProcess [source]
Default
AsyncCommandRunner
implementation forAsyncPGCtl
usingasyncio.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()
.
- 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()
.