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 Settings, *, version: PostgreSQLVersion | None = None) AsyncIterator[InstanceListItem]#

Yield instances found by system lookup.


version – filter instances matching a given version.


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.

  • wait – possibly wait for PostgreSQL to get ready.

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


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.


timeout – delay to wait for instance stop.


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.