API Reference

pgclone

pgclone.copy

copy(
    dump_key: str, *, database: str | None = None, config: str | None = None
) -> str

Copies a database using CREATE DATABASE <dump_key> TEMPLATE <database>.

Note that we use dump keys with the same syntax that dump and restore commands take. Since copy only works with local database copies, this means the dump keys are always the database name prefixed with :.

Parameters:

Name	Type	Description	Default
dump_key	str	A name to use for the copy. Must be prefixed with : and only consist of valid database name characters.	required
database	str | None	The database to copy.	None
config	str | None	The configuration name from settings.PGCLONE_CONFIGS.	None

Returns:

Type	Description
str	The dump key that was copied.

Source code in pgclone/copy_cmd.py

def copy(dump_key: str, *, database: str | None = None, config: str | None = None) -> str:
    """
    Copies a database using `CREATE DATABASE <dump_key> TEMPLATE <database>`.

    Note that we use dump keys with the same syntax that `dump` and `restore`
    commands take. Since `copy` only works with local database copies, this
    means the dump keys are always the database name prefixed with `:`.

    Args:
        dump_key: A name to use for the copy. Must be prefixed with `:` and only
            consist of valid database name characters.
        database: The database to copy.
        config: The configuration name from `settings.PGCLONE_CONFIGS`.

    Returns:
        The dump key that was copied.
    """
    opts = options.get(
        dump_key=dump_key,
        config=config,
        database=database,
    )

    return _copy(dump_key=opts.dump_key, database=opts.database)  # type: ignore - TODO address

pgclone.dump

dump(
    *,
    exclude: list[str] | None = None,
    pre_dump_hooks: list[str] | None = None,
    instance: str | None = None,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None
) -> str

Dumps a database.

Parameters:

Name	Type	Description	Default
exclude	list[str] | None	The models to exclude when dumping the utils.	None
pre_dump_hooks	list[str] | None	A list of management command names to run before dumping the utils.	None
instance	str | None	The instance name to use in the dump key.	None
database	str | None	The database to dump.	None
storage_location	str | None	The storage location to store dumps.	None
config	str | None	The configuration name from settings.PGCLONE_CONFIGS.	None

Returns:

Type	Description
str	The dump key associated with the database dump.

Source code in pgclone/dump_cmd.py

def dump(
    *,
    exclude: list[str] | None = None,
    pre_dump_hooks: list[str] | None = None,
    instance: str | None = None,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None,
) -> str:
    """Dumps a database.

    Args:
        exclude: The models to exclude when dumping the utils.
        pre_dump_hooks: A list of management command names to run before dumping the utils.
        instance: The instance name to use in the dump key.
        database: The database to dump.
        storage_location: The storage location to store dumps.
        config: The configuration name from `settings.PGCLONE_CONFIGS`.

    Returns:
        The dump key associated with the database dump.
    """
    opts = options.get(
        exclude=exclude,
        config=config,
        pre_dump_hooks=pre_dump_hooks,
        instance=instance,
        database=database,
        storage_location=storage_location,
    )

    return _dump(
        exclude=opts.exclude,
        config=opts.config,
        pre_dump_hooks=opts.pre_dump_hooks,
        instance=opts.instance,
        database=opts.database,
        storage_location=opts.storage_location,
    )

pgclone.ls

ls(
    dump_key: str | None = None,
    *,
    instances: bool = False,
    databases: bool = False,
    configs: bool = False,
    local: bool = False,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None
) -> list[str]

Lists dump keys.

Parameters:

Name	Type	Description	Default
dump_key	str | None	Filter by this dump key prefix.	None
instances	bool	Lists only the unique instances associated with the dump keys.	False
databases	bool	Lists only the unique databases associated with the dump keys.	False
configs	bool	Lists only the unique configs associated with the dump keys.	False
local	bool	Only list local restore keys.	False
database	str | None	The database to restore.	None
storage_location	str | None	The storage location to use for the restore.	None
config	str | None	The configuration name from settings.PGCLONE_CONFIGS.	None

Returns:

Type	Description
list[str]	The list of dump keys.

Source code in pgclone/ls_cmd.py

def ls(
    dump_key: str | None = None,
    *,
    instances: bool = False,
    databases: bool = False,
    configs: bool = False,
    local: bool = False,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None,
) -> list[str]:
    """
    Lists dump keys.

    Args:
        dump_key: Filter by this dump key prefix.
        instances: Lists only the unique instances associated with the dump keys.
        databases: Lists only the unique databases associated with the dump keys.
        configs: Lists only the unique configs associated with the dump keys.
        local: Only list local restore keys.
        database: The database to restore.
        storage_location: The storage location to use for the restore.
        config: The configuration name from `settings.PGCLONE_CONFIGS`.

    Returns:
        The list of dump keys.
    """
    opts = options.get(
        dump_key=dump_key, config=config, database=database, storage_location=storage_location
    )

    return _ls(
        dump_key=opts.dump_key,
        config=opts.config,
        database=opts.database,
        storage_location=opts.storage_location,
        instances=instances,
        databases=databases,
        configs=configs,
        local=local,
    )

pgclone.restore

restore(
    dump_key: str | None = None,
    *,
    pre_swap_hooks: list[str] | None = None,
    reversible: bool | None = None,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None
) -> str

Restores a database dump.

Parameters:

Name	Type	Description	Default
dump_key	str | None	Restores the specific dump key or the most recent dump matching the prefix.	None
pre_swap_hooks	list[str] | None	The list of pre-swap hooks to run before swapping the temp restore database with the main utils. The strings are management command names.	None
reversible	bool | None	True if the dump can be reversed.	None
database	str | None	The database to restore.	None
storage_location	str | None	The storage location to use for the restore.	None
config	str | None	The configuration name from settings.PGCLONE_CONFIGS.	None

Returns:

Type	Description
str	The dump key that was restored.

Source code in pgclone/restore_cmd.py

def restore(
    dump_key: str | None = None,
    *,
    pre_swap_hooks: list[str] | None = None,
    reversible: bool | None = None,
    database: str | None = None,
    storage_location: str | None = None,
    config: str | None = None,
) -> str:
    """
    Restores a database dump.

    Args:
        dump_key: Restores the specific dump key or the most recent dump matching the prefix.
        pre_swap_hooks: The list of pre-swap hooks to run before swapping the temp restore
            database with the main utils. The strings are management command names.
        reversible: True if the dump can be reversed.
        database: The database to restore.
        storage_location: The storage location to use for the restore.
        config: The configuration name from `settings.PGCLONE_CONFIGS`.

    Returns:
        The dump key that was restored.
    """
    opts = options.get(
        dump_key=dump_key,
        pre_swap_hooks=pre_swap_hooks,
        config=config,
        reversible=reversible,
        database=database,
        storage_location=storage_location,
    )

    return _restore(
        dump_key=opts.dump_key,
        pre_swap_hooks=opts.pre_swap_hooks,
        config=opts.config,
        reversible=opts.reversible,
        database=opts.database,
        storage_location=opts.storage_location,
    )