Migrer vers ClickHouse Managed Postgres avec PeerDB

Découvrez comment migrer vos données PostgreSQL vers ClickHouse Managed Postgres avec PeerDB

Ce guide explique, étape par étape, comment migrer votre base de données PostgreSQL vers ClickHouse Managed Postgres à l’aide de PeerDB.

​

Prérequis

• Accès à votre base de données PostgreSQL source.
• Une instance ClickHouse Managed Postgres vers laquelle vous souhaitez migrer vos données.
• PeerDB installé sur une machine. Vous pouvez suivre les instructions d’installation dans le dépôt GitHub de PeerDB. Il vous suffit de cloner le dépôt et d’exécuter docker-compose up. Pour ce guide, nous utiliserons PeerDB UI, qui sera accessible à l’adresse http://localhost:3000 une fois PeerDB démarré.

​

Points à prendre en compte avant la migration

Avant de démarrer votre migration, gardez les points suivants à l’esprit :

• Objets de base de données : PeerDB créera automatiquement des tables dans la base de données cible à partir du schéma source. Cependant, certains objets de base de données, comme les index, les contraintes et les triggers, ne seront pas migrés automatiquement. Vous devrez recréer manuellement ces objets dans la base de données cible après la migration.
• Modifications DDL : Si vous activez la réplication continue, PeerDB maintiendra la base de données cible synchronisée avec la source pour les opérations DML (INSERT, UPDATE, DELETE) et propagera les opérations ADD COLUMN. Cependant, les autres modifications DDL (comme DROP COLUMN et ALTER COLUMN) ne sont pas propagées automatiquement. Pour en savoir plus sur la prise en charge des modifications de schéma, consultez ce guide
• Connectivité réseau : Assurez-vous que les bases de données source et cible sont toutes deux accessibles depuis la machine sur laquelle PeerDB s’exécute. Vous devrez peut-être configurer des règles de pare-feu ou des paramètres de groupe de sécurité pour autoriser la connectivité.

​

Créer des peers

Nous devons d’abord créer des peers pour les bases de données source et cible. Un peer représente une connexion à une base de données. Dans PeerDB UI, accédez à la section “Peers” en cliquant sur “Peers” dans la barre latérale. Pour créer un nouveau peer, cliquez sur le bouton + New peer.

​

Création du peer source

Créez un peer pour votre base de données PostgreSQL source en saisissant les détails de connexion, tels que l’hôte, le port, le nom de la base de données, le nom d’utilisateur et le mot de passe. Une fois ces informations renseignées, cliquez sur le bouton Create peer pour enregistrer le peer.

​

Création du peer cible

De la même manière, créez un peer pour votre instance ClickHouse Managed Postgres en fournissant les informations de connexion nécessaires. Vous pouvez obtenir les informations de connexion de votre instance depuis la console ClickHouse Cloud. Après avoir renseigné les informations, cliquez sur le bouton Create peer pour enregistrer le peer cible.

Vous devriez maintenant voir les peers source et cible dans la section “Peers”.

​

Obtenir le dump du schéma de la base de données source

Pour reproduire la configuration de la base de données source dans la base de données cible, nous devons obtenir un dump du schéma de la base de données source. Vous pouvez utiliser pg_dump pour créer un export contenant uniquement le schéma de votre base de données PostgreSQL source :

Installation de pg_dump

Ubuntu :

Mettez à jour les listes de paquets :

sudo apt update

Installez le client PostgreSQL :

sudo apt install postgresql-client

macOS :

Méthode 1 : avec Homebrew (recommandé)

Installez Homebrew si vous ne l’avez pas :

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Installez PostgreSQL :

brew install postgresql

Vérifiez l’installation :

pg_dump --version

pg_dump -d 'postgresql://<user>:<password>@<host>:<port>/<database>'  -s > source_schema.sql

​

Supprimer les contraintes d’unicité et les index du dump du schéma

Avant de l’appliquer à la base de données cible, nous devons supprimer les contraintes UNIQUE et les index du fichier de dump afin que l’ingestion de PeerDB dans les tables cibles ne soit pas bloquée par ces contraintes. Ces éléments peuvent être supprimés comme suit :

# Preview
grep -n "CONSTRAINT.*UNIQUE" <dump_file_path>
grep -n "CREATE UNIQUE INDEX" <dump_file_path>
grep -n -E "(CONSTRAINT.*UNIQUE|CREATE UNIQUE INDEX)" <dump_file_path>

# Remove
sed -i.bak -E '/CREATE UNIQUE INDEX/,/;/d; /(CONSTRAINT.*UNIQUE|ADD CONSTRAINT.*UNIQUE)/d' <dump_file_path>

​

Appliquer le dump du schéma à la base de données cible

Après avoir nettoyé le fichier de dump du schéma, vous pouvez l’importer dans votre base de données cible ClickHouse Managed Postgres en vous connectant via psql et en exécutant le fichier de dump du schéma :

psql -h <target_host> -p <target_port> -U <target_username> -d <target_database> -f source_schema.sql

Ici, du côté de la cible, nous ne voulons pas que l’ingestion de PeerDB soit bloquée par des contraintes de clé étrangère. Pour cela, nous pouvons modifier le rôle de la cible (utilisé ci-dessus dans le peer cible) afin de définir session_replication_role sur replica :

ALTER ROLE <target_role> SET session_replication_role = replica;

​

Créer un mirror

Ensuite, nous devons créer un mirror pour définir le processus de migration des données entre les peers source et cible. Dans PeerDB UI, accédez à la section “Mirrors” en cliquant sur “Mirrors” dans la barre latérale. Pour créer un nouveau mirror, cliquez sur le bouton + New mirror.

1. Donnez à votre mirror un nom décrivant la migration.
2. Sélectionnez les peers source et cible que vous avez créés précédemment dans les menus déroulants.
3. Assurez-vous que :

• Soft delete est sur OFF.
• Développez Advanced settings. Assurez-vous que le système de types Postgres est activé et que les colonnes PeerDB sont désactivées.

4. Sélectionnez les tables que vous souhaitez migrer. Vous pouvez choisir des tables spécifiques ou sélectionner toutes les tables de la base de données source.

Sélection des tables

Assurez-vous que les noms des tables de destination sont identiques à ceux des tables source dans la base de données cible, car nous avons migré le schéma tel quel à l’étape précédente.

5. Une fois les paramètres du mirror configurés, cliquez sur le bouton Create mirror.

Vous devriez voir votre mirror nouvellement créé dans la section “Mirrors”.

​

Attendre le chargement initial

Après avoir créé le mirror, PeerDB lance le chargement initial des données depuis la base de données source vers la base de données cible. Vous pouvez cliquer sur le mirror, puis sur l’onglet Chargement initial pour suivre la progression de la migration initiale des données.

Une fois le chargement initial terminé, vous devriez voir un état indiquant que la migration est terminée.

​

Suivi du chargement initial et de la réplication

Si vous cliquez sur le peer source, vous pouvez voir la liste des commandes que PeerDB est en train d’exécuter. Par exemple :

1. Nous exécutons d’abord une requête COUNT pour estimer le nombre de lignes dans chaque table.
2. Ensuite, nous exécutons une requête de partitionnement avec NTILE pour découper les grandes tables en fragments plus petits afin d’optimiser le transfert des données.
3. Nous exécutons ensuite des commandes FETCH pour récupérer les données depuis la base de données source, puis PeerDB les synchronise avec la base de données cible.

​

Tâches post-migration

Ces étapes peuvent varier selon votre cas d’usage et les exigences de votre application. L’essentiel est de garantir la cohérence des données, de minimiser les interruptions de service et de valider l’intégrité des données migrées avant de basculer complètement vers le nouveau système.

Une fois la migration terminée :

• Effectuez les vérifications de validation avant le basculement

Comparez les tables clés de la source et de la cible avant de basculer le trafic :

-- Row count comparison for critical tables
SELECT 'public.orders' AS table_name, COUNT(*) AS row_count FROM public.orders;
SELECT 'public.customers' AS table_name, COUNT(*) AS row_count FROM public.customers;

-- Spot-check latest records in high-activity tables
SELECT MAX(updated_at) FROM public.orders;
SELECT MAX(id) FROM public.orders;

• Arrêter les écritures sur le système source

Mettez d’abord en pause les écritures de l’application. Comme mesure de protection supplémentaire, placez la base de données source en lecture seule pendant le basculement :

ALTER DATABASE <source_db> SET default_transaction_read_only = on;

Si vous devez revenir en arrière, vous pouvez réactiver les écritures :

ALTER DATABASE <source_db> SET default_transaction_read_only = off;

• Confirmez que la réplication est entièrement à jour

Vérifiez que la dernière ligne d’une ou de plusieurs tables très sollicitées en écriture est identique sur la source et la cible :

-- Run on both source and target and compare results
SELECT MAX(id) AS latest_id, MAX(updated_at) AS latest_ts FROM public.orders;

• Recréez et activez les contraintes, les index et les déclencheurs

Si vous avez supprimé ou différé des contraintes/index pour l’ingestion, réappliquez-les maintenant. Réinitialisez également le rôle de réplication sur la cible si vous l’aviez précédemment défini sur replica :

ALTER ROLE <target_role> SET session_replication_role = origin;

# Example: apply a SQL file containing constraints/indexes/triggers
psql -h <target_host> -p <target_port> -U <target_user> -d <target_db> -f post_migration_objects.sql

• Réinitialiser les séquences des tables cibles

Après le chargement des données, synchronisez les séquences avec les valeurs actuelles des tables :

-- Generic sequence reset for all serial/identity-backed columns in non-system schemas
DO $$
DECLARE r RECORD;
BEGIN
    FOR r IN
        SELECT
            n.nspname AS schema_name,
            c.relname AS table_name,
            a.attname AS column_name,
            pg_get_serial_sequence(format('%I.%I', n.nspname, c.relname), a.attname) AS seq_name
        FROM pg_class c
        JOIN pg_namespace n ON n.oid = c.relnamespace
        JOIN pg_attribute a ON a.attrelid = c.oid
        WHERE c.relkind = 'r'
            AND a.attnum > 0
            AND NOT a.attisdropped
            AND n.nspname NOT IN ('pg_catalog', 'information_schema')
    LOOP
        IF r.seq_name IS NOT NULL THEN
            EXECUTE format(
                'SELECT setval(%L, COALESCE((SELECT MAX(%I) FROM %I.%I), 0) + 1, false)',
                r.seq_name, r.column_name, r.schema_name, r.table_name
            );
        END IF;
    END LOOP;
END $$;

• Basculer le trafic applicatif

Une fois la validation réussie et les séquences/contraintes en place :

1. Dirigez le trafic de lecture vers ClickHouse Managed Postgres.
2. Dirigez le trafic d’écriture vers ClickHouse Managed Postgres.
3. Surveillez les erreurs de l’application, les violations de contraintes et la santé de la base de données.

• Nettoyer les ressources

Une fois la migration validée et votre application basculée vers ClickHouse Managed Postgres, vous pouvez supprimer le mirror et les peers dans PeerDB.

Slots de réplication

Si vous avez activé la réplication continue, PeerDB créera un slot de réplication sur la base de données PostgreSQL source. Veillez à supprimer manuellement le slot de réplication de la base de données source une fois la migration terminée afin d’éviter une consommation inutile de ressources.

​

Références

• Documentation de ClickHouse Managed Postgres
• Guide PeerDB pour la création d’un CDC
• FAQ sur Postgres ClickPipe (également valable pour PeerDB)

​

Prochaines étapes

Félicitations ! Vous avez migré avec succès votre base de données PostgreSQL vers ClickHouse Managed Postgres à l’aide de pg_dump et pg_restore. Vous pouvez maintenant découvrir les fonctionnalités de Managed Postgres et son intégration avec ClickHouse. Voici un guide de démarrage rapide de 10 minutes pour bien démarrer :

• Guide de démarrage rapide de Managed Postgres