Déployer vers ClickHouse Cloud

Cette skill vous guide dans le déploiement vers ClickHouse Cloud en utilisant clickhousectl. Elle couvre la configuration du compte, l'authentification CLI, la création de service, la migration de schéma et la connexion de votre application. Suivez ces étapes dans l'ordre.

Quand appliquer cette skill

Utilisez cette skill quand l'utilisateur souhaite :

Déployer son application ClickHouse en production
Héberger ClickHouse en tant que service cloud géré
Migrer d'une configuration locale de ClickHouse vers ClickHouse Cloud
Créer un service ClickHouse Cloud
Configurer ClickHouse Cloud pour la première fois

Étape 1 : S'inscrire à ClickHouse Cloud

Avant d'utiliser des commandes cloud, l'utilisateur a besoin d'un compte ClickHouse Cloud.

Posez la question à l'utilisateur : « Avez-vous déjà un compte ClickHouse Cloud ? »

S'il n'a pas de compte, expliquez :

ClickHouse Cloud est un service entièrement géré qui exécute ClickHouse pour vous — pas d'infrastructure à maintenir, mise à l'échelle automatique, sauvegardes et mises à jour incluses. Il y a un essai gratuit pour que vous puissiez commencer sans carte de crédit.

Pour créer un compte, allez sur : https://clickhouse.cloud

Inscrivez-vous avec votre email, Google ou GitHub. Une fois dans la console, faites-le-moi savoir et nous continuerons avec l'étape suivante.

Attendez que l'utilisateur confirme qu'il s'est inscrit ou qu'il a déjà un compte avant de poursuivre.

Étape 2 : Authentifier le CLI

D'abord, assurez-vous que clickhousectl est installé. Vérifiez avec :

which clickhousectl

S'il n'est pas trouvé, installez-le :

curl -fsSL https://clickhouse.com/cli | sh

Maintenant, authentifiez-vous. Il y a deux options — choisissez en fonction de la situation :

Important : la connexion OAuth est en lecture seule. La connexion par navigateur (Option A) accorde un accès en lecture seule — vous pouvez lister les organisations, les services et interroger les services existants, mais vous ne pouvez pas créer, modifier ou supprimer des services. Toute opération cloud destructrice ou mutante (création, suppression, mise à l'échelle de service, etc.) nécessite une authentification par clé API (Option B). Si ce workflow implique la création ou la modification de ressources cloud, vous devez utiliser l'Option B.

Option A : Connexion par navigateur (accès en lecture seule)

À utiliser quand une personne est disponible pour ouvrir un navigateur et que vous avez seulement besoin d'inspecter les ressources cloud existantes (lister les orgs, lister les services, interroger les données). Il utilise le flux de dispositif OAuth — aucune clé API nécessaire.

Demandez à l'utilisateur d'exécuter :

clickhousectl cloud login

Cela affiche une URL et un code. L'utilisateur ouvre l'URL dans son navigateur, confirme le code et se connecte avec son compte ClickHouse Cloud. Le CLI reçoit automatiquement les identifiants une fois le flux du navigateur terminé.

Cela suffit pour les étapes qui ne font que lire des données (par exemple, cloud org list, cloud service get, cloud service client). Pour toute étape qui crée ou modifie des ressources, passez à l'authentification par clé API.

Option B : Authentification par clé API (requise pour les actions destructrices)

Utilisez cette option lors de la création, modification ou suppression de ressources cloud (par exemple, cloud service create, cloud service delete). Utilisez également cette option pour les environnements sans interface graphique/CI où aucun navigateur n'est disponible. --api-key et --api-secret sont tous les deux obligatoires — si l'utilisateur ne fournit que l'un sans l'autre, dites-lui que les deux sont nécessaires.

clickhousectl cloud login --api-key <key> --api-secret <secret>

Si l'utilisateur n'a pas encore de clés API, guidez-le pour en créer une :

Dans la console ClickHouse Cloud :

Cliquez sur l'icône d'engrenage (Paramètres) dans la barre latérale gauche

Allez à Clés API

Cliquez sur Créer une clé API

Donnez-lui un nom (par exemple, « cli ») et sélectionnez le rôle Admin

Cliquez sur Générer une clé API

Copiez l'identifiant de clé et le secret de clé — le secret n'est affiché qu'une seule fois

Pour vérifier que l'authentification fonctionne :

clickhousectl cloud org list

Cela devrait retourner l'organisation de l'utilisateur.

Étape 3 : Créer un service cloud

Nécessite l'authentification par clé API. La création de service est une opération mutante. Si vous vous êtes authentifié avec la connexion par navigateur (Option A) à l'Étape 2, vous devez vous réauthentifier avec l'authentification par clé API (Option B) avant de poursuivre.

Créez un nouveau service ClickHouse Cloud :

clickhousectl cloud service create --name <service-name>

La sortie inclut l'ID du service et le mot de passe utilisateur par défaut — notez-le pour les commandes suivantes.

Attendez que le service soit prêt. Après sa création, le service met un moment à être approvisionné. Vérifiez son statut :

clickhousectl cloud service get <service-id>

Vous pouvez extraire le champ « state » pour voir s'il est « running ».

Étape 4 : Migrer les schémas

Si l'utilisateur a des définitions de table locales (par exemple, en utilisant la skill clickhousectl-local-dev), migrez-les vers le service cloud.

Utilisez cloud service client pour exécuter des requêtes sur le service cloud — il recherche automatiquement le endpoint, le port et les paramètres TLS. Vous avez juste besoin du nom du service (ou --id) et du mot de passe de l'étape 3.

Lisez les fichiers de schéma locaux depuis clickhouse/tables/ et appliquez chacun au service cloud :

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/tables/<table>.sql

Appliquez-les dans l'ordre des dépendances — les tables référencées par les vues matérialisées doivent être créées en premier.

Appliquez également les vues matérialisées si elles existent :

clickhousectl cloud service client --name <service-name> \
  --queries-file clickhouse/materialized_views/<view>.sql

Le flag --user par défaut est default. Si l'utilisateur a un utilisateur de base de données différent, passez --user <username>.

Étape 5 : Vérifier le déploiement

Connectez-vous au service cloud et confirmez que les tables existent :

clickhousectl cloud service client --name <service-name> --query "SHOW TABLES"

Exécutez une requête de test pour confirmer que le schéma est correct :

clickhousectl cloud service client --name <service-name> --query "DESCRIBE TABLE <table-name>"

Étape 6 : Mettre à jour la configuration de l'application

Récupérez le endpoint du service pour la configuration de l'application de l'utilisateur :

clickhousectl cloud service get <service-id>

Fournissez à l'utilisateur les détails de connexion :

Hôte : depuis la sortie du service get
Port : 8443 pour HTTPS / 9440 pour TLS natif
Utilisateur : default
Mot de passe : le mot de passe de l'étape 3 (création du service)
SSL/TLS : obligatoire (toujours activé sur Cloud)

Exemples de chaînes de connexion (adaptez au langage/framework de l'utilisateur) :

Python (clickhouse-connect) :

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='<cloud-host>',
    port=8443,
    username='default',
    password='<password>',
    secure=True
)

Node.js (@clickhouse/client) :

import { createClient } from '@clickhouse/client'

const client = createClient({
  url: 'https://<cloud-host>:8443',
  username: 'default',
  password: '<password>',
})

Go (clickhouse-go) :

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"<cloud-host>:9440"},
    Auth: clickhouse.Auth{
        Username: "default",
        Password: "<password>",
    },
    TLS: &tls.Config{},
})

Suggérez à l'utilisateur de stocker le mot de passe dans une variable d'environnement ou un gestionnaire de secrets plutôt que de le coder en dur.

Suggérez à l'utilisateur de ne pas utiliser l'utilisateur par défaut en production. Un utilisateur devrait être créé uniquement pour son application.

clickhousectl-cloud-deploy