Databases

Module pglift.databases exposes the following API to manipulate PostgreSQL databases:

async pglift.databases.apply(instance: PostgreSQLInstance, database: Database) → ApplyResult

Apply state described by specified interface model as a PostgreSQL database.

The instance should be running and not a standby.

async pglift.databases.exists(instance: PostgreSQLInstance, name: str) → bool

Return True if named database exists in ‘instance’.

The instance should be running.

async pglift.databases.ls(instance: PostgreSQLInstance, dbnames: Sequence[str] = (), exclude_dbnames: Sequence[str] = ()) → list[DatabaseListItem]

List databases in instance.

Parameters:

dbnames – restrict operation on databases with a name in this list.

async pglift.databases.get(instance: PostgreSQLInstance, name: str) → Database

Return the database object with specified name.

Raises:

DatabaseNotFound – if no database with specified ‘name’ exists.

async pglift.databases.drop(instance: PostgreSQLInstance, database: DatabaseDropped) → None

Drop a database from a primary instance.

Raises:

DatabaseNotFound – if no database with specified ‘name’ exists.

async pglift.databases.run(instance: ~pglift.models.system.PostgreSQLInstance, sql_command: str, *, dbnames: ~collections.abc.Sequence[str] = (), exclude_dbnames: ~collections.abc.Sequence[str] = (), notice_handler: ~pglift.types.NoticeHandler = <function default_notice_handler>) → dict[str, list[dict[str, Any]]]

Execute a SQL command on databases of instance.

Parameters:

• dbnames – restrict operation on databases with a name in this list.

• exclude_dbnames – exclude databases with a name in this list from the operation.

• notice_handler – a function to handle notice.

Returns:

a dict mapping database names to query results, if any.

Raises:

psycopg.ProgrammingError – in case of unprocessable query.

pglift.databases.dump(instance: ~pglift.models.system.PostgreSQLInstance, dbname: str, output_directory: ~pathlib.PurePath | None = None, *, cmd: ~typing.Annotated[~pglift.system.command.CommandType, ~pglift.deps.Dependency(var=<ContextVar name='Command' default=<module 'pglift.system.cmd' from '/home/docs/checkouts/readthedocs.org/user_builds/pglift/envs/latest/lib/python3.13/site-packages/pglift/system/cmd.py'> at 0x76365c60a930>)] = <object object>) → None

Dump a database of instance (logical backup).

Parameters:

• dbname – Database name.

• dumps_directory – An existing directory to write dump file(s) to; if unspecified postgresql.dumps_directory setting value will be used.

Raises:

psycopg.OperationalError – if the database with ‘dbname’ does not exist.