Copia de seguridad y restauración de instantáneas

La copia de seguridad de instantáneas es un modo de copia de seguridad ligero para motores de tabla nativos de la nube. En lugar de copiar los datos, escribe nodos de bloqueo para cada parte en ClickHouse Keeper. Estos bloqueos impiden que el servidor elimine las partes del almacenamiento de objetos referenciadas mientras se conserve la instantánea. A continuación, la copia de seguridad registra las referencias al almacenamiento de objetos en lugar de copiar físicamente los datos, lo que permite crear instantáneas rápidamente independientemente del tamaño de la tabla.

El modo ligero se aplica a las tablas SharedMergeTree, SharedSet y SharedJoin. Para todos los demás tipos de motor, como Log o Memory, la copia de seguridad recurre automáticamente a una copia de seguridad estándar basada en copias.

La copia de seguridad mediante instantánea utiliza el comando estándar BACKUP con experimental_lightweight_snapshot = true. La configuración id es obligatoria: asigna un nombre a la instantánea y se usa para hacer referencia a ella en los comandos de desbloqueo y observabilidad:

BACKUP { TABLE [db.]table_name | DATABASE db_name | ALL [EXCEPT {TABLES | DATABASES} ...] }
TO { S3(...) | AzureBlobStorage(...) }
SETTINGS experimental_lightweight_snapshot = true, id = '<snapshot_id>'

El comando devuelve id y status, y id puede utilizarse para hacer un seguimiento de la operación en system.backups.

Haga una copia de seguridad de una sola tabla en S3:

BACKUP TABLE mydb.events
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'events_snapshot_1'

Haga una copia de seguridad completa de la base de datos:

BACKUP DATABASE mydb
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/mydb/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'mydb_snapshot_1'

Haga una copia de seguridad de todas las tablas excepto una:

BACKUP ALL
EXCEPT TABLES mydb.staging_table
TO S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/full/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS experimental_lightweight_snapshot = true, id = 'full_snapshot_1'

Los mismos comandos funcionan con Azure Blob Storage:

BACKUP TABLE mydb.events
TO AzureBlobStorage('DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...', 'my-container', 'snapshots/events/')
SETTINGS experimental_lightweight_snapshot = true, id = 'events_snapshot_1'

Como una instantánea almacena referencias a archivos del almacenamiento de objetos en lugar de copias de los datos, restaurarla en un servicio de ClickHouse nuevo o distinto requiere acceso al almacenamiento de objetos original. Por ese motivo, la restauración entre servicios no se admite mediante SQL; solo está disponible a través de la UI. Con SQL, puede restaurar una instantánea en el mismo servicio desde un bucket de copia de seguridad externo con snapshot_from_current_service = 1. Esto lee los objetos directamente a través del disco de destino en lugar de pasar por un lector remoto de instantáneas:

RESTORE TABLE mydb.events AS mydb.events_restored
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS snapshot_from_current_service = 1

La cláusula AS restaura con un nuevo nombre de tabla, dejando intacta la tabla original. Para sobrescribir la tabla original, elimínela primero:

DROP TABLE mydb.events;

RESTORE TABLE mydb.events
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')
SETTINGS snapshot_from_current_service = 1

Cada instantánea mantiene bloqueos en ClickHouse Keeper que impiden que los archivos referenciados del almacenamiento de objetos sean eliminados por el recolector de basura. Una vez completada una restauración — o cuando una instantánea ya no sea necesaria — desbloquéela para liberar esos bloqueos.

Hay dos formas: un desbloqueo a nivel de sistema, que elimina todos los bloqueos de la instantánea de una sola vez, y un desbloqueo por tabla, que elimina el bloqueo de una sola tabla mientras mantiene intacto el resto de la instantánea.

Desbloqueo a nivel de sistema — elimina todos los bloqueos de la instantánea:

SYSTEM UNLOCK SNAPSHOT '<snapshot_id>'
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')

Desbloqueo por tabla — elimina el bloqueo de una sola tabla:

ALTER TABLE mydb.events UNLOCK SNAPSHOT '<snapshot_id>'
FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY')

La cláusula FROM es opcional cuando el destino de la instantánea se almacenó en Keeper al crearse (visible en la columna info de system.snapshot_locks):

SYSTEM UNLOCK SNAPSHOT '<snapshot_id>'

-- o por tabla:
ALTER TABLE mydb.events UNLOCK SNAPSHOT '<snapshot_id>'

Tras desbloquear, la fila correspondiente desaparece de system.snapshot_locks y las partes a las que ya no hacen referencia otros snapshots dejan de aparecer en system.snapshot_parts.

Todas las operaciones de instantánea aparecen en system.backups, junto con las operaciones habituales de copia de seguridad y restauración. Consúltela con el id que estableció (o el UUID devuelto por el comando):

SELECT id, name, status, error, start_time, end_time, num_files, uncompressed_size, compressed_size
FROM system.backups
WHERE id = 'events_snapshot_1'
FORMAT Vertical

Row 1:
──────
id:                events_snapshot_1
name:              S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', '[HIDDEN]')
status:            BACKUP_CREATED
error:
start_time:        2024-06-01 10:00:00
end_time:          2024-06-01 10:00:03
num_files:         42
uncompressed_size: 1073741824
compressed_size:   0

system.snapshot_locks muestra las instantáneas confirmadas que están registradas actualmente en Keeper. Cuando se confirma una instantánea, se crea un nodo de Keeper en /clickhouse/snapshot/committed/{snapshot_id}. Antes de eliminar cualquier parte de datos, el servidor comprueba si alguna instantánea confirmada mantiene un bloqueo sobre esa parte. En ese caso, se omite su eliminación. El bloqueo persiste hasta que desbloquee explícitamente la instantánea.

SELECT *
FROM system.snapshot_locks

Cada fila representa una instantánea confirmada. Si ve bloqueos de instantáneas que ya no tienen un destino de copia de seguridad válido, ejecute SYSTEM UNLOCK SNAPSHOT para eliminarlos.

Para comprobar si existe un bloqueo de instantánea específico:

SELECT id, info, lock_path
FROM system.snapshot_locks
WHERE id = 'events_snapshot_1'

system.snapshot_parts muestra las partes de datos actualmente retenidas por al menos un bloqueo de instantánea. Para cada parte bloqueada, existe un nodo de Keeper en /clickhouse/snapshot/{table_uuid}/{part_name} que contiene el tamaño comprimido y sin comprimir de la parte. Esta tabla lee esos nodos para mostrar qué partes están actualmente protegidas frente a su eliminación.

SELECT *
FROM system.snapshot_parts
ORDER BY data_compressed_bytes DESC
LIMIT 20

Las partes con snapshots_size > 1 tienen varias instantáneas que hacen referencia a ellas y no se eliminarán del almacenamiento de objetos hasta que se desbloqueen todas esas instantáneas.

Para comprobar el almacenamiento total retenido:

SELECT
    formatReadableSize(sum(data_compressed_bytes)) AS total_pinned_compressed,
    formatReadableSize(sum(data_uncompressed_bytes)) AS total_pinned_uncompressed,
    count() AS parts_count
FROM system.snapshot_parts

Para encontrar partes bloqueadas por una instantánea pero que ya se han eliminado o ya no están activas en el servidor —es decir, datos que se conservan en el almacenamiento de objetos únicamente por bloqueos de instantáneas:

SELECT
    count(*),
    sum(data_uncompressed_bytes)
FROM system.snapshot_parts
WHERE (name, table_id) NOT IN (
    SELECT
        name,
        toString(tables.uuid)
    FROM system.parts
    INNER JOIN system.tables ON (parts.`table` = tables.name) AND parts.active
)

┌─count()─┬─sum(data_uncompressed_bytes)─┐
│    1000 │                        96037 │
└─────────┴──────────────────────────────┘

Esto es útil para comprender la sobrecarga de almacenamiento que implica conservar instantáneas después de que los datos originales hayan cambiado o se hayan eliminado.

Los siguientes parámetros de configuración del servidor controlan el comportamiento de las instantáneas. Se establecen en el archivo de configuración del servidor, no en SQL.