Ajuster la configuration de la sync incrémentale

La configuration d'une sync vit sur ExternalDataSchema et peut être modifiée à tout moment via external-data-schemas-partial-update. La plupart des changements sont non-destructifs (prennent effet à la prochaine sync), mais quelques-uns (changer sync_type, modifier les clés primaires) nécessitent une manipulation prudente pour éviter de corrompre les données synchronisées.

Quand utiliser cette skill

• L'utilisateur veut changer comment une table déjà connectée est synchronisée
• Un diagnostic a signalé que le champ incrémental ou la clé primaire est incorrect
• La table se synchronise trop souvent / pas assez souvent
• Basculer une table incrémentale vers CDC (ou vice versa)
• La table source a été modifiée de l'autre côté (nouvelles colonnes, colonnes supprimées) et la config de sync doit être mise à jour

Si l'utilisateur configure une source toute nouvelle, utilisez plutôt setting-up-a-data-warehouse-source — la configuration est choisie au moment de la création là-bas.

Outils disponibles

Les champs que vous pouvez ajuster

Depuis l'endpoint partial-update :

Flux de travail

Étape 1 — Lire la configuration actuelle

Commencez toujours par external-data-schemas-retrieve({id}). Comprendre l'état actuel prévient les erreurs comme « corriger » un incremental_field qui est en fait correct.

Notez :

• sync_type, incremental_field, incremental_field_type, primary_key_columns actuels
• status actuel (ne pas ajuster un schéma actuellement Running — attendre ou annuler d'abord)
• last_synced_at (pour pouvoir dire si la prochaine sync a fonctionné)
• latest_error s'il existe (l'erreur vous indique souvent exactement quoi changer)

Étape 2 — Si vous changez sync_type ou incremental_field, actualiser les candidats

Appelez external-data-schemas-incremental-fields-create({id}). Bien que le nom de l'opération dise « create », elle relit la source et retourne les champs candidats actuels — utilisez-la pour confirmer que le champ que vous voulez définir existe réellement sur la source et quels sync types sont maintenant disponibles pour cette table.

La réponse :

{
  "incremental_fields": [{"field": "updated_at", "type": "datetime", ...}, ...],
  "incremental_available": true,
  "append_available": true,
  "cdc_available": true,
  "full_refresh_available": true,
  "detected_primary_keys": ["id"],
  "available_columns": [...]
}

Si votre incremental_field cible n'est pas dans la liste, dites-le à l'utilisateur — il doit soit choisir un champ différent, soit modifier la table source pour en ajouter un.

Étape 3 — Appliquer le changement

Appelez external-data-schemas-partial-update({id}, {...champs modifiés}).

Envoyez uniquement les champs qui changent réellement. Partial update signifie que les champs non spécifiés restent comme ils sont.

Exemples :

// Basculer de full_refresh à incremental
{
  "sync_type": "incremental",
  "incremental_field": "updated_at",
  "incremental_field_type": "datetime"
}

// Changer la fréquence de sync à horaire
{"sync_frequency": "1hour"}

// Corriger une mauvaise PK sur une table CDC
{"primary_key_columns": ["tenant_id", "order_id"]}

// Suspendre un schéma
{"should_sync": false}

Étape 4 — Décider si les données existantes sont toujours valides

C'est l'étape facile à rater. Certains changements de config invalident les données synchronisées ; d'autres non.

Les changements qui N'INVALIDENT PAS les données existantes :

• sync_frequency, sync_time_of_day — planification seulement
• should_sync — marche/arrêt
• cdc_table_mode dans la plupart des cas — la prochaine sync commencera à écrire dans la nouvelle forme, mais les lignes consolidées historiques restent valides
• Basculer entre incremental et full_refresh avec le même incremental_field — la prochaine sync refait juste à zéro
• Basculer vers ou depuis sync_type: "webhook" — les données synchronisées restent valides ; seul le chemin d'ingestion change. N'oubliez pas d'enregistrer ou désenregistrer le webhook (voir sections ci-dessous) aux côtés du changement sync_type.

Les changements qui PEUVENT invalider les données existantes et nécessitent une resync :

• Changer incremental_field vers une colonne différente — le repère de limite haute provient de l'ancienne colonne et ne correspondra pas. Sans resync, vous manquerez les lignes qui ont été mises à jour entre les historiques des deux champs.
• Changer primary_key_columns — les lignes existantes peuvent être déduplicatées incorrectement par rapport aux nouvelles définitions de PK.
• Basculer de full_refresh à append — les lignes existantes n'ont pas la forme d'historique de version qu'append attend.
• Basculer de append à full_refresh — problème opposé ; vous vous retrouverez avec des versions historiques dupliquées.
• Basculer vers/depuis cdc — la forme de la table change fondamentalement.

Quand le changement invalide les données, le flux propre est :

1. external-data-schemas-partial-update avec la nouvelle config
2. Avertir l'utilisateur que c'est destructif
3. external-data-schemas-resync pour effacer et réimporter sous la nouvelle config

Ou de manière équivalente, external-data-schemas-delete-data → external-data-schemas-reload. delete-data + reload est plus propre quand la table est grande et l'utilisateur veut recommencer de zéro.

Étape 5 — Déclencher et confirmer

Pour les changements non-destructifs, appelez external-data-schemas-reload({id}) pour appliquer la nouvelle config immédiatement plutôt que d'attendre le calendrier.

Attendez un moment, puis external-data-schemas-retrieve({id}) pour confirmer status = Running puis Completed. Rapportez last_synced_at et tout nouveau latest_error.

Changements spécifiques courants

Basculer full_refresh → incremental

1. incremental-fields-create pour confirmer que le champ désiré existe et incremental_available: true.
2. partial-update: {sync_type: "incremental", incremental_field, incremental_field_type}.
3. Pas d'effacement de données nécessaire — la prochaine sync change juste de stratégie. Si la source grandit vite, la prochaine sync incrémentale est la moins chère.

Basculer incremental → cdc (Postgres seulement)

1. Exécutez external-data-sources-check-cdc-prerequisites-create sur la source parent. Procédez seulement si valid: true.
2. incremental-fields-create pour confirmer cdc_available: true et voir detected_primary_keys.
3. partial-update: {sync_type: "cdc", primary_key_columns: [...], cdc_table_mode: "consolidated"}.
4. Resync requise — les tables CDC ont une forme différente. Déclenchez external-data-schemas-resync après la mise à jour. Avertissez l'utilisateur que cela efface les données existantes.

Corriger un champ incrémental obsolète après dérive de schéma

La source a supprimé la colonne updated_at. La sync échoue avec « column does not exist ».

1. incremental-fields-create pour voir quels champs restent.
2. Choisissez un remplacement (ou basculez vers full_refresh si aucun ne convient).
3. partial-update avec le nouveau champ + type (ou nouveau sync_type).
4. reload pour réessayer.

Changer les clés primaires sur une table CDC

1. partial-update: {primary_key_columns: [...]}.
2. Resync requise — les pierres tombales CDC existantes et les clés d'upsert ne correspondent pas à la nouvelle définition de PK, menant à la duplication de lignes ou à des mises à jour manquées.
3. resync, avertissez l'utilisateur.

Changer sync_frequency

1. partial-update: {sync_frequency: "1hour"}.
2. Pas de reload nécessaire — la prochaine sync planifiée applique la nouvelle cadence. Ou reload manuellement si l'utilisateur veut confirmer que rien n'a cassé.

Basculer un schéma vers sync_type: "webhook"

Fonctionne seulement pour les sources qui implémentent WebhookSource (aujourd'hui : Stripe) et les tables où supports_webhooks: true depuis incremental-fields-create.

1. incremental-fields-create pour confirmer supports_webhooks: true pour la table.
2. partial-update: {sync_type: "webhook"}.
3. Si la source n'a pas déjà un webhook enregistré (vérifier avec webhook-info-retrieve), appelez external-data-sources-create-webhook-create({source_id}) pour l'enregistrer.
4. Pas de resync requise — les données de bulk-sync existantes du schéma restent, et le webhook devient le chemin d'ingestion principal une fois la prochaine réconciliation terminée.
5. Gardez sync_frequency défini (ex. 24hour) — il agit comme une réconciliation de filet de sécurité au cas où une livraison webhook serait manquée.

Basculer hors de sync_type: "webhook"

1. partial-update: {sync_type: "incremental"} (ou quel que soit le type bulk approprié) avec le incremental_field + incremental_field_type requis.
2. Si aucun autre schéma sur la source n'utilise toujours sync_type: "webhook", appelez external-data-sources-delete-webhook-create({source_id}) pour désenregistrer. Laisser un webhook orphelin enregistré du côté source signifie juste que les événements seront reçus et supprimés — pas nuisible, mais désordonné.
3. Si d'autres schémas sur la source sont toujours en webhook, laissez le webhook enregistré — il est partagé entre tous les schémas de type webhook sur la source.

Renouveler un secret de signature webhook

Le secret de signature de la source (ex. whsec_... de Stripe) a été renouvelé, et les payloads échouent maintenant la vérification de signature.

1. Récupérez le nouveau secret du tableau de bord de la source.
2. external-data-sources-update-webhook-inputs-create({source_id}, {inputs: {signing_secret: "whsec_..."}}).
3. Pas de reload nécessaire — le prochain payload webhook entrant vérifiera le nouveau secret.

Suspendre un schéma

1. partial-update: {should_sync: false}. Le schéma arrête la synchronisation mais reste configuré.
2. Pour reprendre plus tard : partial-update: {should_sync: true}, puis reload pour une exécution immédiate.

Notes importantes

• Lisez avant d'écrire. Récupérez toujours la configuration actuelle en premier. partial-update ne se plaindra pas si vous définissez un champ à la valeur qu'il avait déjà, mais vous pourriez être sur le point de changer quelque chose dont vous n'aviez pas réalisé qu'il était déjà défini.
• Pas chaque sync_type n'est disponible sur chaque schéma. La réponse incremental-fields-create vous indique ce qui est disponible maintenant, ce qui peut être différent de ce qui était disponible à la création (ex. CDC peut avoir été activé pour l'équipe depuis).
• Effacez quand la forme change. Basculer la stratégie de sync change souvent la table physique. Si vous ne resync pas, vous mélangez les formes de lignes et les requêtes retourneront des ordures.
• CDC a besoin de prérequis. Ne basculez jamais vers sync_type: "cdc" sans exécuter check-cdc-prerequisites-create en premier. La sync échouera juste immédiatement.
• Ne touchez pas un schéma Running. Si le schéma s'exécute actuellement, attendez qu'il se termine ou external-data-schemas-cancel avant d'appliquer le changement. Mettre à jour la config en cours de sync peut laisser le repère de limite haute incrémental incohérent.
• La fréquence de sync est bon marché à changer. Encouragez l'expérimentation là-bas. Sync_type et incremental_field sont coûteux à changer — encouragez la prudence.
• Les webhooks sont enregistrés au niveau de la source, pas au niveau du schéma. Plusieurs schémas de type webhook sur la même source partagent un seul enregistrement webhook. Supprimez le webhook seulement quand le dernier schéma de type webhook sur cette source est en train d'être basculé, sinon les autres schémas arrêtent de recevoir les pushes.