Subgraph Örnek Uygulama 6 - Acil Güncelleme Dağıtımı için Aşılama Kullanın

Özet

Grafting is a powerful feature in Subgraph development that allows you to build and deploy new Subgraphs while reusing the indexed data from existing ones.

Genel Bakış

This feature enables quick deployment of hotfixes for critical issues, eliminating the need to re-index the entire Subgraph from scratch. By preserving historical data, grafting minimizes downtime and ensures continuity in data services.

Acil Güncellemelerde Aşılamanın Avantajları

1. Hızlı Dağıtım

   • Minimize Downtime: When a Subgraph encounters a critical error and stops indexing, grafting enables you to deploy a fix immediately without waiting for re-indexing.
   • Immediate Recovery: The new Subgraph continues from the last indexed block, ensuring that data services remain uninterrupted.

2. Veri Koruma

   • Reuse Historical Data: Grafting copies the existing data from the base Subgraph, so you don’t lose valuable historical records.
   • Tutarlılık: Tutarlı tarihsel verilere bağımlı uygulamalar için veri sürekliliğini sağlar.

3. Verimlilik

   • Zaman ve Kaynak Tasarrufu: Büyük veri kümelerinin yeniden endekslenmesinden kaynaklı hesaplama yükünü önler.
   • Hatalara Odaklanma: Geliştiricilerin veri kurtarma yönetimi yerine sorunları çözmeye odaklanmalarını sağlar.

Acil Güncellemeler için Aşılama Kullanmak - Örnek Uygulamalar

1. Aşılama Olmadan Başlangıç Dağıtımı

   • Start Clean: Always deploy your initial Subgraph without grafting to ensure that it’s stable and functions as expected.
   • Test Thoroughly: Validate the Subgraph’s performance to minimize the need for future hotfixes.

2. Aşılama ile Acil Güncelleme Yapmak

   • Sorunu Belirleme: Kritik bir hata oluştuğunda, son başarılı endekslenmiş olayın blok numarasını belirleyin.
   • Create a New Subgraph: Develop a new Subgraph that includes the hotfix.
   • Configure Grafting: Use grafting to copy data up to the identified block number from the failed Subgraph.
   • Deploy Quickly: Publish the grafted Subgraph to restore service as soon as possible.

3. Acil Güncelleme Sonrasındaki Aksiyonlar

   • Monitor Performance: Ensure the grafted Subgraph is indexing correctly and the hotfix resolves the issue.
   • Republish Without Grafting: Once stable, deploy a new version of the Subgraph without grafting for long-term maintenance.
     Not: Aşılamaya süresiz olarak güvenmek önerilmez. Bu durum gelecekteki güncellemeleri ve bakımı karmaşık hale getirebilir.

   • Update References: Redirect any services or applications to use the new, non-grafted Subgraph.

4. Önemli Hususlar

   • Bloku Dikkatli Seçimek: Veri kaybını önlemek için aşılama blok numarasını dikkatli seçin.
   • İpucu: Doğru işlenmiş son olayın blok numarasını kullanın.
   • Use Deployment ID: Ensure you reference the Deployment ID of the base Subgraph, not the Subgraph ID.
   • Note: The Deployment ID is the unique identifier for a specific Subgraph deployment.
   • Feature Declaration: Remember to declare grafting in the Subgraph manifest under features.

Örnek: Aşılama ile Bir Acil Güncelleme Dağıtmak

Suppose you have a Subgraph tracking a smart contract that has stopped indexing due to a critical error. Here’s how you can use grafting to deploy a hotfix.

1. Hata Veren Subgraph Manifestosu (subgraph.yaml)

   1specVersion: 1.3.02schema:3  file: ./schema.graphql4dataSources:5  - kind: ethereum/contract6    name: OldSmartContract7    network: sepolia8    source:9      address: '0xOldContractAddress'10      abi: Lock11      startBlock: 500000012    mapping:13      kind: ethereum/events14      apiVersion: 0.0.915      language: wasm/assemblyscript16      entities:17        - Withdrawal18      abis:19        - name: Lock20          file: ./abis/OldLock.json21      eventHandlers:22        - event: Withdrawal(uint256,uint256)23          handler: handleOldWithdrawal24      file: ./src/old-lock.ts

2. Yeni Aşılanmış Subgraph Manifestosu (subgraph.yaml)

   1specVersion: 1.3.02schema:3  file: ./schema.graphql4dataSources:5  - kind: ethereum/contract6    name: NewSmartContract7    network: sepolia8    source:9      address: '0xNewContractAddress'10      abi: Lock11      startBlock: 6000001 # Block after the last indexed block12    mapping:13      kind: ethereum/events14      apiVersion: 0.0.915      language: wasm/assemblyscript16      entities:17        - Withdrawal18      abis:19        - name: Lock20          file: ./abis/Lock.json21      eventHandlers:22        - event: Withdrawal(uint256,uint256)23          handler: handleWithdrawal24      file: ./src/lock.ts25features:26  - grafting27graft:28  base: QmBaseDeploymentID # Deployment ID of the failed Subgraph29  block: 6000000 # Last successfully indexed block

Açıklama:

• Data Source Update: The new Subgraph points to 0xNewContractAddress, which may be a fixed version of the smart contract.
• Başlangıç Bloğu: Hatanın tekrar işlenmesini önlemek için başarıyla endekslenmiş son bloktan bir blok sonraya ayarlayın.
• Aşılama Yapılandırması:
  • base: Deployment ID of the failed Subgraph.
  • block: Aşılama işleminin başlaması gereken blok numarası.

3. Dağıtım Adımları

   • Kodu Güncelleyin: eşleme kodlarınıza (örneğin, handleWithdrawal kısmına) acil güncelleme uygulayın.
   • Manifestoyu Ayarlayın: Yukarıda gösterildiği gibi, subgraph.yaml dosyasını aşılama yapılandırmalarıyla güncelleyin.
   • Subgraph’i Dağıtın:
     • Graph CLI ile kimlik doğrulaması yapın.
     • Deploy the new Subgraph using graph deploy.

4. Dağıtım Sonrası

   • Verify Indexing: Check that the Subgraph is indexing correctly from the graft point.
   • Veriyi Takip Etme: Yeni verilerin yakalandığından ve acil güncellemenin etkili olduğundan emin olun.
   • Yeniden Yayımlama İçin Planlama: Uzun süreli istikrar için aşılama yapılmamış sürümün dağıtımını planlayın.

Uyarılar ve Dikkat Edilmesi Gerekenler

Aşılama, acil güncellemeleri hızlı bir şekilde dağıtmayı sağlayan güçlü bir araçtır. Fakat veri bütünlüğünü korumak ve ideal performansı sağlamak için aşılanma kullanımından kaçınılması gereken belirli durumlar vardır.

• Incompatible Schema Changes: If your hotfix requires altering the type of existing fields or removing fields from your schema, grafting is not suitable. Grafting expects the new Subgraph’s schema to be compatible with the base Subgraph’s schema. Incompatible changes can lead to data inconsistencies and errors because the existing data won’t align with the new schema.
• Önemli Eşlem Mantığı Revizyonları: Acil güncelleme olayların işlenme şeklinin değiştirilmesi veya işleyici fonksiyonlarının değiştirilmesi gibi eşlem mantığınızda önemli değişiklikleri içeriyorsa, aşılama doğru çalışmayabilir. Buradaki yeni mantık, eski mantık altında işlenmiş verilerle uyumlu olmayabilir. Bu da hatalı verilere veya başarısız endekslemelere yol açabilir.
• Deployments to The Graph Network: Grafting is not recommended for Subgraphs intended for The Graph’s decentralized network (mainnet). It can complicate indexing and may not be fully supported by all Indexers, potentially causing unexpected behavior or increased costs. For mainnet deployments, it’s safer to re-index the Subgraph from scratch to ensure full compatibility and reliability.

Risk Yönetimi

• Veri Bütünlüğü: Yanlış blok numaraları veri kaybına veya yinelenmelere yol açabilir.
• Test Etme: Aşılamayı daima önce geliştirme ortamında test ettikten sonra üretime dağıtın.

Sonuç

Grafting is an effective strategy for deploying hotfixes in Subgraph development, enabling you to:

• Yeniden endeksleme yapmadan kritik hatalardan Hızla Kurtulun.
• Uygulamalar ve kullanıcılar için sürekliliği koruyarak Tarihsel Verileri Koruyun.
• Kritik düzeltmeler sırasında kesinti sürelerini en aza indirerek Hizmet Erişilebilirliğini Sağlayın.

However, it’s important to use grafting judiciously and follow best practices to mitigate risks. After stabilizing your Subgraph with the hotfix, plan to deploy a non-grafted version to ensure long-term maintainability.

Ek Kaynaklar

• Aşılama Dokümantasyonu: Aşılama ile Bir Sözleşmeyi Değiştirin ve Geçmişini Koruyun
• Dağıtım Kimliklerini Anlamak: Dağıtım Kimliği ile Subgraph Kimliği arasındaki farkı öğrenin.

By incorporating grafting into your Subgraph development workflow, you can enhance your ability to respond to issues swiftly, ensuring that your data services remain robust and reliable.

Subgraph Örnek Uygulamalar 1-6

1. Improve Query Speed with Subgraph Pruning

2. Improve Indexing and Query Responsiveness by Using @derivedFrom

3. Improve Indexing and Query Performance by Using Immutable Entities and Bytes as IDs

4. Improve Indexing Speed by Avoiding eth_calls

5. Simplify and Optimize with Timeseries and Aggregations

6. Use Grafting for Quick Hotfix Deployment