Instances

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

async pglift.instances.apply(settings, instance, *, _is_running=None)

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.

Parameters:

  • settings (Settings)

  • instance (Instance)

  • _is_running (bool | None)

Return type:

InstanceApplyResult

pglift.instances.get(arg, /, **kwargs)
pglift.instances.get(arg, /, *, settings)
pglift.instances.get(instance)
Parameters:
Return type:

Instance

pglift.instances.exists(name, version, settings)

Return true when instance exists

Parameters:

  • name (str)

  • version (Literal['18', '17', '16', '15', '14'])

  • settings (Settings)

Return type:

bool

async pglift.instances.ls(settings, *, version=None)

Yield instances found by system lookup.

Parameters:

  • version (Literal['18', '17', '16', '15', '14'] | None) – filter instances matching a given version.

  • settings (Settings)

Raises:

InvalidVersion – if specified version is unknown.

Return type:

AsyncIterator[InstanceListItem]

async pglift.instances.drop(instance)

Drop an instance.

Parameters:

instance (Instance)

Return type:

None

pglift.instances.init(instance, manifest, *, instance_manager=<object object>, config_manager=<object object>)

Initialize a PostgreSQL cluster.

Parameters:
Return type:

bool

async pglift.instances.configure(instance, manifest, *, run_hooks=True, _is_running=None)

Configure PostgreSQL and satellite components of instance with respect to specified manifest.

Parameters:
Return type:

ConfigureResult

pglift.instances.configure_postgresql(instance, manifest, *, manager=<object object>)

Write instance’s configuration in postgresql.conf.

Parameters:

  • instance (PostgreSQLInstance)

  • manifest (Instance)

  • manager (Annotated[AbstractConfigurationManager, Dependency(var=<ContextVar name='ConfigurationManager' at 0x7ba075779d50>)])

Return type:

tuple[Configuration, Changes]

async pglift.instances.start(instance, *, foreground=False, wait=True, _check=True)

Start an instance.

Parameters:

  • wait (bool) – possibly wait for PostgreSQL to get ready.

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

  • instance (Instance)

  • _check (bool)

Return type:

None

Note

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

pglift.instances.stop(instance, *, mode='fast', wait=True, deleting=False, manager=<object object>)

Stop an instance.

Parameters:

  • instance (Instance)

  • mode (Literal['smart', 'fast', 'immediate'])

  • wait (bool)

  • deleting (bool)

  • manager (Annotated[AbstractInstanceManager, Dependency(var=<ContextVar name='InstanceManager' at 0x7ba07577a480>)])

Return type:

None

async pglift.instances.restart(instance, *, mode='fast', wait=True)

Restart an instance.

Parameters:
Return type:

None

pglift.instances.reload(instance, *, manager=<object object>)

Reload an instance.

Parameters:

  • instance (PostgreSQLInstance)

  • manager (Annotated[AbstractInstanceManager, Dependency(var=<ContextVar name='InstanceManager' at 0x7ba07577a480>)])

Return type:

None

async pglift.instances.pending_restart(cnx)

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

Parameters:

cnx (AsyncConnection[dict[str, Any]] | None)

Return type:

bool

pglift.instances.stopped(instance, *, timeout=10)

Context manager to temporarily stop an instance.

Parameters:

  • timeout (int) – delay to wait for instance stop.

  • instance (Instance)

Raises:

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

Return type:

AsyncIterator[None]

pglift.instances.promote(instance, *, manager=<object object>)

Promote a standby instance

Parameters:

  • instance (Instance)

  • manager (Annotated[AbstractInstanceManager, Dependency(var=<ContextVar name='InstanceManager' at 0x7ba07577a480>)])

Return type:

None

pglift.instances.demote(instance, source, *, rewind_opts=(), manager=<object object>)

Demote an instance as standby.

The target instance is rewound from specified source (thus becoming an exact copy of the source server) and then re-configured so that its original definition is restored as it was before rewind.

The logic for re-configuration is adapted from configure().

Parameters:
Return type:

Instance

pglift.instances.upgrade(instance, *, version=None, name=None, port=None, extra_opts=(), fs=<object object>, _instance_model=None)

Upgrade a primary instance using pg_upgrade

Parameters:

  • instance (Instance)

  • version (Literal['18', '17', '16', '15', '14'] | None)

  • name (str | None)

  • port (int | None)

  • extra_opts (tuple[str, ...])

  • fs (Annotated[AbstractFS[PurePath] | AbstractFS[Path], Dependency(var=<ContextVar name='FileSystem' default=<pglift.system.fs.LocalFS object at 0x7ba076829010> at 0x7ba076672de0>)])

  • _instance_model (type[Instance] | None)

Return type:

Instance

async pglift.instances.settings(cnx)

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

Parameters:

cnx (AsyncConnection[dict[str, Any]] | None)

Return type:

list[PGSetting]