00 Preparação

Ponto de partida

Ainda não há nada instalado. Você precisa de um terminal e cerca de 30 minutos para instalar cinco ferramentas de linha de comando, criar duas contas gratuitas de avaliação na nuvem, clonar o repositório e configurar dois ambientes virtuais do Python.

Por quê

Este workshop provisiona duas nuvens — Snowflake como origem e ClickHouse Cloud como destino — e executa dois adaptadores dbt nelas, um para cada nuvem. Os dois adaptadores têm requisitos mínimos rígidos de versão, e o que realmente causa problemas é o Python: dbt-snowflake (e dbt-clickhouse, usado depois) exige Python 3.11, 3.12 ou 3.13. O Python 3.14 ou mais recente quebra uma dependência transitiva, mashumaro, usada pelos dois adaptadores. Se você errar agora, a falha não aparecerá aqui: ela surgirá dois módulos depois como um erro confuso de importação do dbt, aparentemente sem relação com a versão do Python. Fixar o interpretador neste módulo evita esse problema.

Etapa 1 — instalar a cadeia de ferramentas

Todos os pacotes deste workshop devem ser instalados em um ambiente virtual isolado, nunca com um pip install global sem ambiente. A etapa 4 configura os dois ambientes necessários.

Etapa 2 — criar as duas contas de nuvem

Você precisa de uma conta de avaliação em cada nuvem. As duas são gratuitas e dispensam cartão de crédito:

• Conta de avaliação do Snowflake — este é o ambiente de origem. O módulo 01 provisiona aqui um warehouse, um banco de dados e um pipeline Medallion.
• Conta de avaliação do ClickHouse Cloud — este é o ambiente de destino. Ele não será usado até que o módulo 03 o provisione e a migração comece de fato.

Ao criar as duas contas agora, nenhuma delas se tornará um impedimento quando você iniciar o módulo 01.

Etapa 3 — clonar o repositório

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

Todos os comandos no restante do workshop pressupõem que você esteja em workshop_public/snowflake_migration_lab dentro desse clone.

Etapa 4 — configurar os dois ambientes virtuais do dbt

dbt-snowflake e dbt-clickhouse fixam intervalos de dependências incompatíveis, por isso não podem compartilhar um ambiente virtual. Você criará um por adaptador, um para cada lado da migração na nuvem.

dbt-snowflake, usado com a origem no módulo 01:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

# Use python3.13 explicitly if your system default is 3.14+
python3.13 -m venv .venv          # or: python3 -m venv .venv
source .venv/bin/activate
pip install "dbt-snowflake>=1.7,<2.0"
deactivate

dbt-clickhouse, usado com o destino a partir do módulo 03:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse"
python3.13 -m venv .venv
source .venv/bin/activate
pip install "dbt-clickhouse>=1.8,<2.0" snowflake-connector-python clickhouse-connect
deactivate

Cada .venv permanece no diretório do respectivo módulo. Ative o ambiente necessário e use deactivate quando trocar de um para o outro, em vez de tentar fazer um único ambiente atender aos dois adaptadores.

Como verificar se você terminou

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

terraform version                  # expect >= 1.6
docker --version                   # expect >= 24
python3 --version                  # expect 3.11, 3.12, or 3.13
snowsql --version                  # expect >= 1.2

source 01-setup-snowflake/.venv/bin/activate
dbt --version                      # expect dbt-snowflake >= 1.7
deactivate

source 03-migrate-to-clickhouse/.venv/bin/activate
dbt --version                      # expect dbt-clickhouse >= 1.8
deactivate

Todos os cinco comandos devem exibir uma versão igual ou superior ao mínimo indicado, e cada dbt --version deve listar o adaptador que você acabou de instalar nesse ambiente virtual.

Estado final

A cadeia de ferramentas está instalada, as duas contas de avaliação estão ativas, o repositório foi clonado e os dois ambientes virtuais do dbt estão configurados. Ainda não há nada provisionado em nenhuma das nuvens; isso começa no módulo 01. Continue em 01 Ambiente de origem para construir o lado Snowflake da migração.