Instances

Module pglift.instances exposes the following API to manipulate instances:

async pglift.instances.apply(settings: Settings, instance: Instance, *, _creating: bool = False, _upgrading_from: Instance | None = None, _is_running: bool | None = None) → InstanceApplyResult

Apply state described by interface model as a PostgreSQL instance.

Depending on the previous state and existence of the target instance, the instance may be created or updated or dropped.

If configuration changes are detected and the instance was previously running, the server will be reloaded automatically; if a restart is needed, the user will be prompted in case of interactive usage or this will be performed automatically if ‘restart_on_changes’ is set to True.

async pglift.instances.get(instance: Instance) → Instance

Return a interface Instance model from a system Instance.

pglift.instances.exists(name: str, version: str | None, settings: Settings) → bool

Return true when instance exists

async pglift.instances.ls(settings: Settings, *, version: PostgreSQLVersion | None = None) → AsyncIterator[InstanceListItem]

Yield instances found by system lookup.

Parameters:

version – filter instances matching a given version.

Raises:

InvalidVersion – if specified version is unknown.

async pglift.instances.drop(instance: Instance) → None

Drop an instance.

pglift.instances.init(instance: BaseInstance, manifest: Instance) → tuple[PostgreSQLInstance, bool]

Initialize a PostgreSQL cluster.

async pglift.instances.configure(instance: BaseInstance, manifest: Instance, *, run_hooks: bool = True, _creating: bool = False, _is_running: bool | None = None) → dict[str, tuple[str | bool | float | int | timedelta | None, str | bool | float | int | timedelta | None]]

Write instance’s configuration in postgresql.conf.

async pglift.instances.start(instance: Instance, *, foreground: bool = False, wait: bool = True, _check: bool = True) → None

Start an instance.

Parameters:

• wait – possibly wait for PostgreSQL to get ready.

• foreground – start postgres in the foreground, replacing the current process.

Note

When starting in “foreground”, hooks will not be triggered and wait parameter have no effect.

async pglift.instances.stop(instance: Instance, *, mode: Literal['smart', 'fast', 'immediate'] = 'fast', wait: bool = True, deleting: bool = False) → None

Stop an instance.

async pglift.instances.restart(instance: Instance, *, mode: Literal['smart', 'fast', 'immediate'] = 'fast', wait: bool = True) → None

Restart an instance.

async pglift.instances.reload(instance: PostgreSQLInstance) → None

Reload an instance.

async pglift.instances.pending_restart(cnx: AsyncConnection[Dict[str, Any]]) → bool

Return True if the instance is pending a restart to account for configuration changes.

pglift.instances.stopped(instance: Instance, *, timeout: int = 10) → AsyncIterator[None]

Context manager to temporarily stop an instance.

Parameters:

timeout – delay to wait for instance stop.

Raises:

InstanceStateError – when the instance did stop after specified timeout (in seconds).

async pglift.instances.promote(instance: Instance) → None

Promote a standby instance

pglift.instances.upgrade(instance: Instance, *, version: str | None = None, name: str | None = None, port: int | None = None, jobs: int | None = None, _instance_model: type[Instance] | None = None) → Instance

Upgrade a primary instance using pg_upgrade

async pglift.instances.settings(cnx: AsyncConnection[Dict[str, Any]]) → list[PGSetting]

Return the list of run-time parameters of the server, as available in pg_settings view.