1. Главная
  2. Хаб
  3. Сценарии
  4. Переезд из другого ClickHouse: выгрузка в S3, загрузка через интеграцию и сверка строк

Сценарий 26

Переезд из другого ClickHouse: выгрузка в S3, загрузка через интеграцию и сверка строк

Переносим таблицы из ClickHouse у другого провайдера или на своём сервере в управляемый ClickHouse h3llo.cloud: старый сервер выгружает данные в бакет S3, новый забирает их через S3-интеграцию, а сверка числа строк по месяцам показывает, что ничего не потерялось. В конце — догрузка свежих данных и переключение приложений.

60 минСредний10 шагов ClickHouse, S3 обновлено

Содержание
  1. 01Составьте список таблиц на старом сервере
  2. 02Создайте управляемый ClickHouse
  3. 03Заведите базу и пользователя для переноса
  4. 04Создайте бакет для выгрузки
  5. 05Подключите бакет к ClickHouse интеграцией
  6. 06Создайте таблицы на новом сервере
  7. 07Выгрузите данные со старого сервера в бакет
  8. 08Загрузите данные в новую таблицу
  9. 09Сверьте число строк по месяцам
  10. 10Догрузите свежие данные и переключите приложения
  11. Проверка результата
  12. Как удалить ресурсы
  13. Типичные ошибки
  14. Сколько стоит

Что получится

Таблицы старого ClickHouse со всеми строками в управляемом ClickHouse h3llo.cloud, совпадающие счётчики строк по месяцам на обеих сторонах, догруженный хвост свежих данных и приложения, которые пишут и читают уже из нового сервера.

Что понадобится

  • Доступ к старому ClickHouse с правом SELECT на переносимые таблицы и правом на табличную функцию s3 (у самостоятельно развёрнутого сервера оно есть у пользователя default).
  • Исходящий доступ со старого сервера к https://storage.h3llo.cloud (порт 443).
  • clickhouse-client на компьютере или сервере, откуда вы подключаетесь к новой базе, и CLI h3 с API-ключом проекта — для шага с интеграцией.
  • Колонка времени в больших таблицах (например, ts): по ней удобно делить выгрузку и сверку на месяцы.
  1. Шаг 1. Составьте список таблиц на старом сервере

    Сначала поймите объём и схему: какие таблицы переносим, сколько в них строк и какие движки. Таблицы с движками Kafka, MySQL, PostgreSQL, URL хранят подключения к внешним системам, а не данные. Такие таблицы не выгружают: их заново настраивают на новой стороне (см. «Типичные ошибки»).

    На старом ClickHouse
    SELECT database, name, engine, total_rows,
           formatReadableSize(total_bytes) AS size
    FROM system.tables
    WHERE database NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema')
    ORDER BY total_bytes DESC;
    
    -- DDL каждой переносимой таблицы: сохраните вывод в файл schema.sql
    SHOW CREATE TABLE shop.events FORMAT TSVRaw;

    Проверка

    У вас есть список таблиц с объёмом и файл schema.sql с их CREATE TABLE. Суммарный объём подскажет размер диска новой базы: берите с запасом в полтора-два раза — слияния кусков временно занимают место.

  2. Шаг 2. Создайте управляемый ClickHouse

    Выберите ту же линию версии, что у старого сервера, или новее. Доступны 26.8, 26.3 (LTS) и 25.8.33.6.

    Консоль

    1. В меню проекта откройте Базы данных и нажмите Создать базу данных (если базы уже есть — Создать).
    2. СУБД — ClickHouse, версия 26.3. vCPU — 4, RAM — 16 ГБ, Диски — 200 ГБ (минимум для ClickHouse — 2 vCPU и 4 ГБ RAM).
    3. Имя базы данных — ch-new. Сеть оставьте предложенной.
    4. Публичный IPv4 — «Вкл.», «Выделить новый IP», если будете подключаться со своего компьютера. Для подключения только с серверов проекта оставьте выключенным.
    5. Нажмите Создать базу данных.

    CLI

    Терминал
    h3 db create --name ch-new --engine clickhouse --version 26.3 \
      --cpu 4 --memory 16Gi --size 200 --white-ip
    h3 db list        # id новой базы понадобится дальше

    Проверка

    Статус меняется с «Создается» на «Работает». В карточке базы, в блоке «Подключение», есть «Адрес в VPC» и (если включали) «Публичный IP».

  3. Шаг 3. Заведите базу и пользователя для переноса

    Встроенный пользователь app не может получить доступ к интеграциям, поэтому для переноса нужен отдельный пользователь. Пресет «Администратор» разрешает создавать таблицы и писать в них, но не управляет пользователями.

    Консоль

    1. В карточке базы в строке «Пользователи и базы» нажмите Открыть.
    2. В секции «Базы данных» нажмите Создать базу, в окне «Новая база» введите Имя базы analytics и нажмите Создать.
    3. В секции «Пользователи» нажмите Создать пользователя. В окне «Новый пользователь»: Имя пользователя migrator, в Доступ к базам для analytics выберите «Администратор», Профиль — «Большой» (запрос до 600 секунд). Нажмите Создать.
    4. Сохраните пароль из окна «Пользователь создан» и нажмите Я сохранил пароль.

    CLI

    Терминал
    DB=<id базы ch-new>
    h3 db database create $DB --name analytics
    echo '{"name":"migrator","grants":[{"database":"analytics","preset":"admin"}],"profile":"large"}' \
      | h3 db user create $DB --from-file -
    h3 db user credentials $DB migrator

    Проверка

    Пользователь подключается к новой базе. Платформа выдаёт сертификат, которому публичные корневые центры не доверяют, поэтому клиенту нужен флаг --accept-invalid-certificate — шифрование при этом остаётся.

    Терминал
    clickhouse-client --secure --host <IP или адрес в VPC> --port 9440 \
      --accept-invalid-certificate --user migrator --password '<пароль>' \
      --query 'SELECT version()'

    Если не получилось

    • Подключение висит до тайм-аута — у базы нет публичного IP, а вы подключаетесь снаружи. Подключайтесь с сервера в той же сети проекта или привяжите IP: h3 db public-ip attach.
    • Сразу после создания пользователя возможна ошибка доступа: права применяются в течение минуты. Если не прошли — Изменить доступ и сохраните права ещё раз.
  4. Шаг 4. Создайте бакет для выгрузки

    Консоль

    1. Откройте S3 хранилище и нажмите Создать бакет. Имя бакета — ch-migration, нажмите Создать бакет.
    2. На странице «Бакеты S3» скопируйте «Публичный ключ» и «Приватный ключ» — одна пара на все бакеты проекта.

    CLI

    Терминал
    h3 s3 bucket create ch-migration

    Terraform

    s3.tf
    resource "h3_s3_bucket" "migration" {
      project_id = var.project_id
      name       = "ch-migration"
    }
    
    # ключи проекта отдаются только при создании бакета
    output "s3_access_key_id" {
      value     = h3_s3_bucket.migration.access_key_id
      sensitive = true
    }
    output "s3_secret_access_key" {
      value     = h3_s3_bucket.migration.secret_access_key
      sensitive = true
    }

    Проверка

    Бакет ch-migration есть в списке «Бакеты S3», ключи сохранены.

  5. Шаг 5. Подключите бакет к ClickHouse интеграцией

    В управляемом ClickHouse у пользователей нет табличных функций s3, url и remote с произвольным адресом. Бакет подключается именованной коллекцией: платформа хранит ключи у себя и выдаёт пользователю право читать только этот бакет и префикс.

    Интеграции настраиваются через API. CLI h3 подписывает запрос ключом проекта.

    CLI

    Терминал
    h3 api POST /api/databases/v1/$DB/integrations -d '{
      "name": "migration_s3",
      "kind": "s3",
      "bucket": "ch-migration",
      "prefix": "export",
      "accessKeyId": "<публичный ключ>",
      "secretAccessKey": "<приватный ключ>",
      "grantTo": ["migrator"]
    }'
    h3 api GET /api/databases/v1/$DB/integrations

    Проверка

    В ответе GET у migration_s3 статус READY, ключей в ответе нет. Коллекция смотрит в ch-migration/export/.

    Если не получилось

    • UNKNOWN_USER в grantTo — указан встроенный app или пользователь, которого нет в «Пользователи и базы». Нужен пользователь, созданный на шаге 3.
    • ALREADY_EXISTS — интеграция с таким именем уже есть: удалите её (h3 api DELETE /api/databases/v1/$DB/integrations/migration_s3) или выберите другое имя.
  6. Шаг 6. Создайте таблицы на новом сервере

    Примените DDL из schema.sql, заменив имя базы на analytics. Материализованные представления и словари создайте после загрузки: иначе представление получит каждую строку второй раз.

    Если база создана с репликами через API, добавьте ON CLUSTER c и замените MergeTree на ReplicatedMergeTree() без аргументов — путь в Keeper платформа задаёт сама. Для базы из консоли (один сервер) DDL подходит как есть.

    На новом ClickHouse (пользователь migrator)
    CREATE TABLE analytics.events
    (
        ts       DateTime,
        user_id  UInt64,
        event    LowCardinality(String),
        payload  String
    )
    ENGINE = MergeTree
    PARTITION BY toYYYYMM(ts)
    ORDER BY (event, ts);

    Проверка

    SHOW TABLES FROM analytics показывает все переносимые таблицы, пустые.

  7. Шаг 7. Выгрузите данные со старого сервера в бакет

    Формат Native сохраняет типы ClickHouse один в один (LowCardinality, Nullable, DateTime64, Enum), поэтому для переезда ClickHouse → ClickHouse он надёжнее Parquet. Большую таблицу выгружайте по месяцам: каждый месяц — отдельный файл, повтор после сбоя затронет только его.

    Хранилище работает только с адресами вида https://storage.h3llo.cloud/<бакет>/<путь>, регион не нужен.

    На старом ClickHouse
    INSERT INTO FUNCTION s3(
        'https://storage.h3llo.cloud/ch-migration/export/events/{_partition_id}.native',
        '<публичный ключ>', '<приватный ключ>', 'Native')
    PARTITION BY toYYYYMM(ts)
    SELECT * FROM shop.events
    SETTINGS s3_truncate_on_insert = 1;

    Проверка

    В бакете появились файлы по месяцам. Проверьте с компьютера, где настроен rclone из сценария «Резервные копии в S3», или на странице бакета в консоли:

    Терминал
    rclone ls h3:ch-migration/export/events/

    Если не получилось

    • Access Denied или SignatureDoesNotMatch — перепутаны ключи: первым идёт «Публичный ключ», вторым «Приватный».
    • Старый сервер не выходит в интернет или провайдер запрещает функцию s3 — выгрузите таблицу в файл (clickhouse-client --query 'SELECT * FROM shop.events FORMAT Native' > events.native) и загрузите его в бакет через rclone по тому же пути.
  8. Шаг 8. Загрузите данные в новую таблицу

    Коллекция migration_s3 уже указывает на ch-migration/export/, поэтому в запросе остаётся только путь к файлам внутри префикса.

    На новом ClickHouse (пользователь migrator)
    INSERT INTO analytics.events
    SELECT * FROM s3(migration_s3, filename = 'events/*.native', format = 'Native');

    Проверка

    Запрос завершился без ошибок, SELECT count() FROM analytics.events больше нуля. Долгую загрузку видно в разделе диагностики базы или в system.processes.

    Если не получилось

    • Override not allowed for 'url' — в запросе передан адрес бакета. Адрес и ключи задаёт коллекция, в запросе указывайте только filename и format.
    • Timeout exceeded — у пользователя профиль «Стандартный» или «Малый». Поставьте «Большой» (Профиль и квота) или загружайте по одному месяцу: filename = 'events/202610.native'.
    • Not enough space — диска не хватает на данные и слияния. Увеличьте диск базы и повторите месяц, на котором остановились.
  9. Шаг 9. Сверьте число строк по месяцам

    Один и тот же запрос на обеих сторонах. Расхождение покажет, какой месяц выгрузить и загрузить заново.

    На старом и на новом ClickHouse
    SELECT toYYYYMM(ts) AS month, count() AS rows, min(ts), max(ts)
    FROM analytics.events          -- на старом сервере: shop.events
    GROUP BY month
    ORDER BY month;

    Проверка

    Таблицы с обеих сторон совпадают строка в строку. Если в каком-то месяце строк меньше, удалите его на новой стороне (ALTER TABLE analytics.events DROP PARTITION 202610), выгрузите заново и загрузите один файл.

  10. Шаг 10. Догрузите свежие данные и переключите приложения

    Пока шла выгрузка, старый сервер продолжал получать данные. Перед переключением остановите запись, догрузите хвост с момента первой выгрузки и направьте приложения на новый адрес.

    На старом ClickHouse — хвост после остановки записи
    INSERT INTO FUNCTION s3(
        'https://storage.h3llo.cloud/ch-migration/export/events-tail/tail.native',
        '<публичный ключ>', '<приватный ключ>', 'Native')
    SELECT * FROM shop.events WHERE ts >= '2026-11-01 00:00:00'
    SETTINGS s3_truncate_on_insert = 1;
    На новом ClickHouse
    ALTER TABLE analytics.events DELETE WHERE ts >= '2026-11-01 00:00:00';
    INSERT INTO analytics.events
    SELECT * FROM s3(migration_s3, filename = 'events-tail/tail.native', format = 'Native');

    Проверка

    Сверка из прошлого шага совпадает и для последнего месяца. В настройках приложения — новый адрес: «Адрес в VPC» для серверов и кластеров проекта, порт 9440 (нативный протокол) или 8443 (HTTPS).

Проверка результата

Приложение пишет в новый ClickHouse, отчёты строятся по полным данным, а сверка по месяцам совпадает со старым сервером на момент остановки записи.

Терминал
clickhouse-client --secure --host <адрес> --port 9440 --accept-invalid-certificate \
  --user migrator --password '<пароль>' \
  --query "SELECT max(ts), count() FROM analytics.events"

Как удалить ресурсы

После переезда уберите временное: интеграцию, бакет с выгрузкой и, когда убедитесь, что откат не понадобится, — старый сервер.

CLI

Терминал
h3 api DELETE /api/databases/v1/$DB/integrations/migration_s3
h3 s3 bucket delete ch-migration
  1. S3 хранилище → строка ch-migration → меню «…» → Удалить. Удаление бакета удаляет все файлы выгрузки.
  2. Пользователя migrator можно оставить для администрирования или удалить: «Пользователи и базы» → меню пользователя → Удалить.

Типичные ошибки

Почему не remote() или remoteSecure() напрямую со старого сервера?

У пользователей управляемого ClickHouse нет табличных функций `remote`, `url`, `s3` и `file` с произвольным адресом — так платформа не даёт отправить данные или пароли на чужой сервер. Внешние данные подключаются интеграциями: S3, Kafka и PostgreSQL своего проекта.

Что делать с таблицами на движке Kafka и материализованными представлениями?

Таблицу `Kafka` создайте заново через Kafka-интеграцию (`kind: kafka`) — источник должен быть Managed Kafka в той же сети проекта. Материализованные представления создайте после загрузки данных, иначе исторические строки попадут в целевую таблицу дважды.

Пользователи и права старого сервера переносятся?

Нет. Пользователей заведите в «Пользователи и базы» с пресетами «Только чтение», «Чтение и запись» или «Администратор»; команды `CREATE USER` и `GRANT` пресетам недоступны.

Словари со старого сервера

Словари из таблиц PostgreSQL создаются через API (`POST /api/databases/v1/<id>/dictionaries`) поверх PostgreSQL-интеграции. Словари из других источников придётся заменить таблицами или словарями из PostgreSQL.

У старого сервера был кластер с шардами

Выгружайте с каждого шарда в свой подкаталог (`events/shard1/…`) или через `Distributed`-таблицу целиком. Новая база с шардами создаётся через API (`clickhouseConfig.shards`), для запросов ко всем шардам нужна таблица `Distributed` на кластере `c`.

Связанные продукты и материалы

Сколько стоит

≈ 19,37 ₽ в час · 13 949 ₽ в месяц при работе 24/7

vCPU ClickHouse4 × 1 035 ₽
RAM ClickHouse, ГБ16 × 414 ₽
Диск до 20 000 IOPS*, ГБ200 × 14,40 ₽
Публичный IPv4 базы1 × 90 ₽
Выгрузка в S3 на время переезда, ГБ100 × 2,15 ₽
Чтение выгрузки из S3 при загрузке, ГБ100 × 0,90 ₽

Загрузка в S3 и запросы бесплатны, скачивание из бакета оплачивается за ГБ по тарифу хранилища. Хранение выгрузки считается за время переезда — бакет удаляется в конце. Публичный IPv4 нужен только для подключения к базе со своего компьютера — с сервера в той же сети проекта можно обойтись без него.

Цены из прайс-листа, по которому работает биллинг; списание поминутное, месяц — 720 часов. Если удалить ресурсы после проверки, сценарий обойдётся в рубли.

Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.

* IOPS растут с объёмом диска; точные значения для вашего объёма видны в консоли при выборе.