03 Provisionnement et migration

Complément formateur du module participant 03 Provisionnement et migration.

Durée

Environ 60 minutes au total, dont la répartition importe davantage que le total : 10 à 15 minutes de travail actif (l’étape 1 provisionne le service ClickHouse Cloud avec Terraform en 2 à 3 minutes ; l’étape 2 crée trips_raw, charge les données de référence des zones et lance le premier dbt run à vide en quelques minutes supplémentaires), puis 40 à 50 minutes de transfert autonome (script de l’étape 3, qui déplace 50 millions de lignes à environ 20 000 lignes/s).

C’est l’information de planification la plus importante de tout l’atelier : après le démarrage de l’étape 3, la salle n’a plus rien à faire pendant près d’une heure. Lancez le script puis placez la pause ici, utilisez l’attente pour reprendre les éléments du fil conducteur du module 02 qui n’ont pas pu être traités, ou organisez une séance de questions-réponses sur les choix consignés dans migration-plan.md. Ne prévoyez aucune autre pause dans ce module : placez-la volontairement ici.

Fil conducteur

• Reprenez la justification donnée dans le module : le laboratoire déplace les données avec un script Python plutôt qu’avec un connecteur natif parce que Snowflake n’est pas une source ClickPipes prise en charge (Kafka, S3, Kinesis et le CDC PostgreSQL/MySQL le sont, pas Snowflake), tandis que chaque solution de remplacement (export S3, Snowflake -> Kafka -> ClickHouse) remplace une configuration de laboratoire par une infrastructure sans rapport avec la migration : bucket S3, rôle IAM ou cluster Kafka.
• Nommez explicitement les avantages réels du script Python : aucun compte AWS, solution autonome (les deux nouveaux paquets vivent dans le même environnement que dbt), reprise avec --resume à partir d’une marque max(pickup_at) et transparence suffisante pour qu’un partenaire lise la correspondance des colonnes au lieu de parcourir un assistant.
• Présentez honnêtement l’alternative de production : au-delà d’environ 500 millions de lignes, ou lorsque le coût d’un warehouse qui analyse toute la table compte, l’export S3 est préférable — export parallèle et chargement parallèle. Le script Python convient à l’échelle de l’atelier, ce n’est pas une recommandation universelle.
• Annoncez dès maintenant l’écart de migration, même s’il sera refermé au module 05 : le producteur Snowflake continue d’écrire pendant toute l’étape 3, si bien que ClickHouse prend un retard proche de la durée du transfert. Cet écart est attendu et la bascule du module 05 est conçue pour le mesurer et le refermer. Dites-le avant que quelqu’un ne demande si l’attente de 40 à 50 minutes « perd » des données.

Erreurs courantes

• Le premier dbt run de l’étape 2 échoue avec Could not find profile named 'nyc_taxi_ch'. Rien dans l’atelier ne crée automatiquement le profil dbt ClickHouse nyc_taxi_ch, bien que dbt_project.yml l’exige. Le module participant 03 Provisionnement et migration couvre ce point : « Configurer le profil dbt », à l’étape 2, explique comment fusionner un bloc nyc_taxi_ch: avec le fichier ~/.dbt/profiles.yml existant avant ce dbt run. Si un partenaire a sauté ou mal recopié l’étape, renvoyez-le vers celle-ci plutôt que de réexpliquer ici le contournement.
• L’authentification Terraform échoue avec 401 Unauthorized. Vérifiez CLICKHOUSE_TOKEN_KEY et CLICKHOUSE_TOKEN_SECRET : les deux se trouvent dans l’interface ClickHouse Cloud, sous Settings -> API keys, et doivent avoir la portée Admin.
• Le script de migration échoue en cours d’exécution. Relancez-le avec --resume ; il utilise comme marque le max(pickup_at) déjà présent dans ClickHouse et ignore les lignes chargées, de sorte qu’un redémarrage ne crée jamais de chargement partiel irrécupérable.
• Le script de migration ne parvient pas du tout à se connecter. Vérifiez toutes les variables d’environnement Snowflake et ClickHouse (echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD et echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD), puis exécutez source .env && source .clickhouse_state et réessayez.
• dbt run échoue avec Connection refused ou Unknown host. CLICKHOUSE_HOST n’est pas défini dans le shell actuel : exécutez source .clickhouse_state depuis workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ et réessayez.

Étapes de réinitialisation

• Script de migration interrompu : python scripts/02_migrate_trips.py --resume poursuit à partir de la marque plutôt que de reprendre tout le transfert des 50 millions de lignes.
• Le service ClickHouse Cloud doit être entièrement reconstruit : exécutez source .env && ./teardown.sh depuis workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ (ce qui détruit le service et, si la bascule a déjà eu lieu, le conteneur du producteur ClickHouse), puis relancez ./setup.sh. Cette opération ne touche pas la partie Snowflake du module 01, qui possède son propre teardown.sh dans workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Une réinitialisation complète est coûteuse ici : une nouvelle migration répète la totalité du transfert de 40 à 50 minutes. Préférez --resume ou une correction ciblée tant que le service ClickHouse lui-même reste sain.