Databases¶

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

async pglift.databases.apply(instance, database)¶

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

The instance should be running and not a standby.

Parameters:

instance (PostgreSQLInstance)
database (Database)

Return type:

ApplyResult

async pglift.databases.exists(instance, name)¶

Return True if named database exists in ‘instance’.

The instance should be running.

Parameters:

instance (PostgreSQLInstance)
name (str)

Return type:

bool

async pglift.databases.ls(instance, dbnames=(), exclude_dbnames=())¶

List databases in instance.

Parameters:

dbnames (Sequence[str]) – restrict operation on databases with a name in this list.
instance (PostgreSQLInstance)
exclude_dbnames (Sequence[str])

Return type:

list[DatabaseListItem]

async pglift.databases.get(instance, name)¶

Return the database object with specified name.

Raises:

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

Parameters:

instance (PostgreSQLInstance)
name (str)

Return type:

Database

async pglift.databases.drop(instance, database)¶

Drop a database from a primary instance.

Raises:

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

Parameters:

instance (PostgreSQLInstance)
database (DatabaseDropped)

Return type:

None

async pglift.databases.run(instance, sql_command, *, dbnames=(), exclude_dbnames=(), notice_handler=<function default_notice_handler>)¶

Execute a SQL command on databases of instance.

Parameters:

dbnames (Sequence[str]) – restrict operation on databases with a name in this list.
exclude_dbnames (Sequence[str]) – exclude databases with a name in this list from the operation.
notice_handler (NoticeHandler) – a function to handle notice.
instance (PostgreSQLInstance)
sql_command (str)

Returns:

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

Raises:

psycopg.ProgrammingError – in case of unprocessable query.

Return type:

dict[str, list[dict[str, Any]]]

pglift.databases.dump(instance, dbname, output_directory=None, *, cmd=<object object>)¶

Dump a database of instance (logical backup).

Parameters:

dbname (str) – Database name.
dumps_directory – An existing directory to write dump file(s) to; if unspecified postgresql.dumps_directory setting value will be used.
instance (PostgreSQLInstance)
output_directory (PurePath | None)
cmd (Annotated[CommandType, Dependency(var=<ContextVar name='Command' default=<module 'pglift.system.cmd' from '/home/docs/checkouts/readthedocs.org/user_builds/pglift/envs/latest/lib/python3.14/site-packages/pglift/system/cmd.py'> at 0x7cbbdf1473d0>)])

Raises:

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

Return type:

None