Configuration locale du développement ClickHouse

Cette skill vous guide à travers la mise en place d'un environnement de développement ClickHouse complet en local en utilisant clickhousectl. Suivez ces étapes dans l'ordre.

Quand l'utiliser

Utilisez cette skill quand l'utilisateur veut :

Construire une application qui nécessite une base de données analytique ou ClickHouse spécifiquement
Configurer une instance ClickHouse locale pour le développement
Installer ClickHouse sur sa machine
Créer des tables et commencer à interroger ClickHouse localement
Prototyper ou expérimenter avec ClickHouse

Étape 1 : Installer clickhousectl

Vérifiez si clickhousectl est déjà disponible :

which clickhousectl

Si non trouvé, installez-le :

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

Cela installe clickhousectl dans ~/.local/bin/clickhousectl et crée un alias chctl.

Si la commande n'est toujours pas trouvée après l'installation : L'utilisateur peut avoir besoin d'ajouter ~/.local/bin à son PATH ou d'ouvrir une nouvelle session de terminal. Suggérez :

export PATH="$HOME/.local/bin:$PATH"

Étape 2 : Installer ClickHouse

Installez la dernière version stable de ClickHouse :

clickhousectl local install stable

Cela télécharge le binaire ClickHouse dans ~/.clickhouse/versions/. Le binaire est partagé entre les projets, il n'a donc besoin d'être téléchargé qu'une fois.

Spécificateurs de version alternatifs (à utiliser si l'utilisateur a un besoin spécifique) :

lts — dernière version avec support à long terme
25.12 — dernier patch d'une version mineure spécifique
25.12.5.44 — version exacte

Définissez la version installée comme version par défaut :

clickhousectl local use stable

Étape 3 : Initialiser le projet

À partir du répertoire racine du projet de l'utilisateur :

clickhousectl local init

Cela crée une structure de dossiers standard :

clickhouse/
  tables/                 # Déclarations CREATE TABLE
  materialized_views/     # Définitions de vues matérialisées
  queries/                # Requêtes sauvegardées
  seed/                   # Données de seed / déclarations INSERT

Note : Cette étape est optionnelle. Si l'utilisateur a déjà sa propre structure de dossiers pour les fichiers SQL, ignorez cette étape et adaptez les étapes suivantes à ses chemins.

Étape 4 : Démarrer un serveur local

clickhousectl local server start --name <name>

Cela démarre un serveur ClickHouse en arrière-plan. Les données du serveur sont stockées dans .clickhouse/servers/<name>/data/ dans le répertoire du projet.

Pour vérifier les serveurs en cours d'exécution et voir leurs ports exposés :

clickhousectl local server list

Étape 5 : Créer le schéma

En fonction des exigences de l'application de l'utilisateur, écrivez les fichiers SQL CREATE TABLE.

Écrivez chaque définition de table dans son propre fichier dans clickhouse/tables/ :

# Exemple : clickhouse/tables/events.sql

CREATE TABLE IF NOT EXISTS events (
    timestamp DateTime,
    user_id UInt32,
    event_type LowCardinality(String),
    properties String
)
ENGINE = MergeTree()
ORDER BY (event_type, timestamp)

Lors de la conception de schémas, si la skill clickhouse-best-practices est disponible, consultez-la pour des conseils sur la sélection des colonnes ORDER BY, les types de données et le partitionnement.

Appliquez le schéma au serveur en cours d'exécution :

clickhousectl local client --name <name> --queries-file clickhouse/tables/events.sql

Étape 6 : Remplir avec des données (optionnel)

Si l'utilisateur a besoin de données d'exemple pour le développement, écrivez les déclarations INSERT dans clickhouse/seed/ :

# Exemple : clickhouse/seed/events.sql

INSERT INTO events (timestamp, user_id, event_type, properties) VALUES
    ('2024-01-01 00:00:00', 1, 'page_view', '{"page": "/home"}'),
    ('2024-01-01 00:01:00', 2, 'click', '{"button": "signup"}');

Appliquez les données de seed :

clickhousectl local client --name <name> --queries-file clickhouse/seed/events.sql

Étape 7 : Vérifier la configuration

Confirmez que les tables ont été créées :

clickhousectl local client --name <name> --query "SHOW TABLES"

Exécutez une requête de test :

clickhousectl local client --name <name> --query "SELECT count() FROM events"

Si l'utilisateur veut utiliser un service ClickHouse géré, utilisez la skill clickhousectl-cloud-deploy pour l'aider à déployer sur ClickHouse Cloud.

clickhousectl-local-dev