Docs
⌘ K

7 minutes

Meilleure pratique pour les subgraphs 6 - Utiliser le greffage pour un déploiement rapide des correctifs

TLDR

Le greffage est une fonctionnalité puissante dans le développement de Subgraphs qui vous permet de construire et de déployer de nouveaux Subgraphs tout en réutilisant les données indexées des Subgraphs existants.

Aperçu

Cette fonction permet de déployer rapidement des correctifs pour les problèmes critiques, éliminant ainsi la nécessité de réindexer l’ensemble du Subgraph à partir de zéro. En préservant les données historiques, le greffage minimise les temps d’arrêt et assure la continuité des services de données.

Avantages du greffage pour les correctifs

  1. Déploiement rapide

    • Minimiser les temps d’arrêt : Lorsqu’un Subgraph rencontre une erreur critique et cesse d’être indexé, la greffe vous permet de déployer immédiatement un correctif sans attendre la réindexation.
    • Récupération immédiate : Le nouveau Subgraph continue à partir du dernier bloc indexé, garantissant que les services de données restent ininterrompus.

  2. Préservation des données

    • Réutilisation des données historiques : Le greffage copie les données existantes du Subgraph de base, de sorte que vous ne perdez pas de précieux enregistrements historiques.
    • Consistance : Maintient la continuité des données, ce qui est crucial pour les applications qui s’appuient sur des données historiques cohérentes.

  3. Efficacité

    • Économie de temps et de ressources : Évite surcoût de calcul lié à la réindexation de grands ensembles de données.
    • Focalisation sur les corrections : Permet aux développeurs de se concentrer sur la résolution des problèmes plutôt que sur la gestion de la récupération des données.

Meilleures pratiques lors de l’utilisation du greffage pour les correctifs

  1. Déploiement initial sans greffage

    • Démarrez proprement : Déployez toujours votre Subgraph initial sans greffe pour vous assurer qu’il est stable et qu’il fonctionne comme prévu.
    • Testez minutieusement : Validez les performances du Subgraph afin de minimiser les besoins en correctifs futurs.

  2. Mise en œuvre du correctif par greffage

    • Identifier le problème : Lorsqu’une erreur critique se produit, déterminez le numéro de bloc du dernier événement indexé avec succès.
    • Créer un nouveau Subgraph : Développer un nouveau Subgraph qui inclut le correctif.
    • Configurer la greffe : Utiliser la greffage pour copier les données jusqu’au numéro de bloc identifié à partir du Subgraph défaillant.
    • Déployer rapidement : Publier le Subgraph greffé pour rétablir le service dès que possible.

  3. Actions post-correctif

    • Surveillez les performances : Assurez-vous que le Subgraph greffé est indexé correctement et que le correctif résout le problème.
    • Républier sans greffer : Une fois stable, déployer une nouvelle version du Subgraph sans greffe pour une maintenance à long terme.

      Remarque : il n’est pas recommandé de s’appuyer indéfiniment sur le greffage, car cela peut compliquer les mises à jour et la maintenance futures.

    • Mettre à jour les références : Rediriger tous les services ou applications pour qu’ils utilisent le nouveau Subgraph non greffé.

  4. Considérations importantes

    • Sélection minutieuse des blocs : Choisissez soigneusement le numéro du bloc de greffage pour éviter toute perte de données.
    • Conseil : Utilisez le numéro de bloc du dernier événement correctement traité.
    • Utiliser l’ID de déploiement : Assurez-vous que vous faites référence à l’ID de déploiement du Subgraph de base, et non à l’ID du Subgraph.
    • Note : L’ID de déploiement est l’identifiant unique d’un déploiement de Subgraph spécifique.
    • Déclaration de fonctionnalité : N’oubliez pas de déclarer le greffage dans le manifeste Subgraph en dessous de features.

Exemple : Déploiement d’un correctif par greffage

Supposons que vous ayez un Subgraph qui suit un contrat intelligent qui a cessé d’être indexé en raison d’une erreur critique. Voici comment vous pouvez utiliser le greffage pour déployer un correctif.

  1. Manifeste du subgraph échoué (subgraph.yaml)

    specVersion: 1.3.0schema:  file: ./schema.graphqldataSources:  - kind: ethereum/contract    name: OldSmartContract    network: sepolia    source:      address: '0xOldContractAddress'      abi: Lock      startBlock: 5000000    mapping:      kind: ethereum/events      apiVersion: 0.0.9      language: wasm/assemblyscript      entities:        - Withdrawal      abis:        - name: Lock          file: ./abis/OldLock.json      eventHandlers:        - event: Withdrawal(uint256,uint256)          handler: handleOldWithdrawal      file: ./src/old-lock.ts

  2. Nouveau manifeste de subgraph greffé (subgraph.yaml)

    specVersion: 1.3.0schema:  file: ./schema.graphqldataSources:  - kind: ethereum/contract    name: NewSmartContract    network: sepolia    source:      address: '0xNewContractAddress'      abi: Lock      startBlock: 6000001 # Bloc suivant le dernier bloc indexé    mapping:      kind: ethereum/events      apiVersion: 0.0.9      language: wasm/assemblyscript      entities:        - Withdrawal      abis:        - name: Lock          file: ./abis/Lock.json      eventHandlers:        - event: Withdrawal(uint256,uint256)          handler: handleWithdrawal      file: ./src/lock.tsfeatures:  - graftinggraft:  base: QmBaseDeploymentID # Deployment ID of the failed Subgraph  block: 6000000 # Dernier bloc indexé avec succès

Explication:

  • Mise à jour de la source de données : Le nouveau Subgraph pointe vers 0xNewContractAddress, qui pourrait être une version corrigée du contrat intelligent.
  • Bloc de départ : Fixé à un bloc après le dernier bloc indexé avec succès afin d’éviter de retraiter l’erreur.
  • Configuration du greffage :
    • base : ID de déploiement du Subgraph défaillant.
    • bloc : Numéro du bloc où le greffage doit commencer.

  1. Étapes de déploiement

    • Mise à jour du code : Implémentez le correctif dans vos scripts de mappage (par exemple, handleWithdrawal).
    • Ajuster le manifeste : Comme indiqué ci-dessus, mettez à jour le fichier subgraph.yaml avec les configurations de greffage.
    • Déployer le subgraph :
      • S’authentifier à l’aide de l’interface de Graph CLI.
      • Déployer le nouveau Subgraph en utilisant graph deploy.

  2. Post-Déploiement

    • Vérifier l’indexation : Vérifier que le Subgraph est correctement indexé à partir du point de greffage.
    • Surveiller les données : S’assurer que les nouvelles données sont capturées et que le correctif est efficace.
    • Planifier la republication : Planifier le déploiement d’une version non greffée pour une stabilité à long terme.

Avertissements et précautions

Bien que le greffage soit un outil puissant pour déployer rapidement des correctifs, il existe des scénarios spécifiques dans lesquels il doit être évité afin de préserver l’intégrité des données et d’assurer des performances optimales.

  • Modifications de schéma incompatibles : Si votre correctif nécessite de modifier le type des champs existants ou de supprimer des champs de votre schéma, le greffage n’est pas appropriée. La greffe suppose que le schéma du nouveau subgraph soit compatible avec celui du subgraph de base. Des modifications incompatibles peuvent entraîner des incohérences et des erreurs dans les données, car les données existantes ne seront pas alignées sur le nouveau schéma.
  • Révisions importantes de la logique de mappage : Lorsque le correctif implique des modifications substantielles de votre logique de mappage, telles que la modification du traitement des événements ou des fonctions de gestion, le greffage risque de ne pas fonctionner correctement. La nouvelle logique peut ne pas être compatible avec les données traitées dans le cadre de l’ancienne logique, ce qui entraîne des données incorrectes ou un échec de l’indexation.
  • Déploiements sur le réseau The Graph : Le greffage n’est pas recommandée pour les subgraphs destinés au réseau décentralisé de The Graph (réseau principal). Elle peut compliquer l’indexation et peut ne pas être entièrement prise en charge par tous les Indexeurs, ce qui peut entraîner un comportement inattendu ou une augmentation des coûts. Pour les déploiements sur le réseau principal, il est plus sûr de réindexer le subgraph à partir de zéro pour garantir une compatibilité et une fiabilité totales.

Gestion des risques

  • Intégrité des données : Des numéros de blocs incorrects peuvent entraîner la perte ou la duplication de données.
  • Test : Testez toujours le greffage dans un environnement de développement avant de la déployer en production.

Conclusion

Le greffage est une stratégie efficace pour déployer des correctifs dans le cadre du développement de Subgraphs :

  • Rétablissement rapide sans besoin de réindexation après des erreurs critiques.
  • Préserver les données historiques, en maintenant la continuité pour les applications et les utilisateurs.
  • Assurer la disponibilité du service en minimisant les temps d’arrêt lors des corrections critiques.

Cependant, il est important d’utiliser le greffage de manière judicieuse et de suivre les meilleures pratiques pour atténuer les risques. Après avoir stabilisé votre Subgraph à l’aide du correctif, prévoyez de déployer une version non greffée afin de garantir la maintenabilité à long terme.

Ressources supplémentaires

En incorporant le greffage dans votre flux de développement Subgraph, vous pouvez améliorer votre capacité à répondre rapidement aux problèmes, en veillant à ce que vos services de données restent robustes et fiables.

Bonnes pratiques pour les subgraphs 1-6

  1. Améliorer la vitesse des requêtes avec l’élagage des Subgraphs

  2. Améliorer l’indexation et la réactivité des requêtes en utilisant @derivedFrom

  3. Améliorer l’indexation et les performances des requêtes en utilisant des entités immuables et des Bytes comme IDs

  4. Améliorer la vitesse d’indexation en évitant les eth_calls

  5. Simplifier et optimiser avec les séries chronologiques et les agrégations

  6. Utiliser le greffage pour un déploiement rapide des correctifs