LogoLogo
Package RegistryThe Graph
  • Introduction
  • Getting Started
  • Tutorials
    • Generate Your First Substreams
      • on EVM
      • on Solana
        • Transactions & Instructions
        • Account Changes
      • on TRON
      • on Injective
      • on MANTRA
      • on Starknet
      • on Stellar
  • How-To Guides
    • Developing Substreams (Deep Dive)
      • on EVM
        • Exploring Ethereum
          • Mapping Blocks
          • Filter Transactions
          • Retrieve Events of a Smart Contract
        • Making eth_calls
      • on Solana
        • Explore Solana
          • Filter Instructions
          • Filter Transactions
        • SPL Token Tracker
        • NFT Trades
        • DEX Trades
        • From Yellowstone to Substreams
      • on Cosmos
        • Injective
          • Simple Substreams Example
          • Foundational Modules
    • Install Substreams CLI
      • Substreams CLI Authentication
    • Using a Substreams Sink
      • Substreams:SQL
        • Using Relational Mappings
        • Using Database Changes
      • Substreams:Stream
        • JavaScript
        • Go
      • Substreams:PubSub
      • Files
      • Community Sinks
        • MongoDB
        • Key-Value Store
        • Prometheus
    • Publishing a Substreams Package
    • Getting Started Using Rust and Protobuf
      • Rust
        • Option struct
        • Result struct
      • Protobuf Schemas
  • Reference Material
    • Chains and endpoints
      • Ethereum Data Model
    • Never Miss Data
    • Development Container Reference
    • Substreams CLI
    • Substreams Components
      • Packages
      • Modules
        • Module types
        • Inputs
        • Output
        • Module handlers
        • Module handler creation
        • Indexes
        • Keys in stores
        • Dynamic data sources
        • Aggregation Windows
        • Parameterized Modules
      • Manifests Reference
    • Substreams Architecture
    • Substreams:SQL
      • Sink Config
      • DSN Reference
      • Reorg Handling
    • Indexer Reference
      • Test Substreams Locally
    • Logging, Debugging & Testing
    • Change log
    • FAQ
  • Decentralized Indexing
    • What is The Graph?
Powered by GitBook
On this page
Edit on GitHub
  1. How-To Guides
  2. Using a Substreams Sink

Substreams:SQL

PreviousUsing a Substreams SinkNextUsing Relational Mappings

Last updated 27 days ago

Was this helpful?

CtrlK
  • Requirements
  • Mapping Substreams to SQL
  • Installation

Was this helpful?

The Substreams:SQL service allows you to consume the data extracted from the blockchain through a SQL database.

Requirements

Before you begin, make sure you have:

  • A Substreams package (for example, a package that indexes ERC20 tokens).

  • A SQL database: Postgres or ClickHouse.

  • The substreams-sink-sql CLI installed in your computer.

Mapping Substreams to SQL

The core function of the SQL sink is to translate your Substreams output (Protobuf data) into SQL tables. Choose one of the following methods depending on your needs:

  • Using Relational Mappings

    • Enables foreign key relationships in your SQL schema.

    • Requires adding annotations to your Protobuf messages (e.g., primary and foreign keys).

    • Currently insert-only.

  • Using Database Changes

    • Gives you full control over the output.

    • Supports insert, update, and upsert operations.

    • Ideal for advanced use cases with evolving or mutable data.

    • NOTE: In ClickHouse, reorgs are currently supported with delay.

Relational Mappings

db_out module

SQL relationships

Yes

No

Direct Protobuf<>SQL mappings

Yes

No

INSERT supported

Yes

Yes

UPDATE supported

No

Yes

UPSERT supported

No

Yes

Installation

Enabling substreams-sink-sql in your Substreams CLI.

  1. Download the current binary, optionally depending on your operating system, from the substreams-sink-sql GitHub releases page.

  2. Move the binary to your $PATH.

Installing from Source

  1. Clone the substreams-sink-sql GitHub repository.

  2. Install the binary using Go.

go install ./cmd/substreams-sink-sql
  1. Make sure GO is installed and the GO bin directory is in your $PATH.