Export contract events to Postgres

This guide walks you through exporting every event a contract emits into a Postgres database with a Turbo pipeline. You’ll define the pipeline in YAML and deploy it with the Turbo CLI.

Prefer a visual editor? You can build the same pipeline by dragging sources, transforms, and sinks onto a canvas with Goldsky Flow in the dashboard.

What you’ll need

An idea of the data you’re interested in indexing (e.g. a contract address)
A destination sink to write your data to; any Postgres database works, for example a Neon instance
The Turbo Pipelines CLI extension installed and a Goldsky account, logged in to your project

Walkthrough

In this example, we will create a pipeline that indexes Bored Ape Yacht Club contract events to a Postgres database. This will include all transfers and other auxiliary events emitted by that address, using the Ethereum raw logs dataset as the source and decoding the events in a SQL transform.

Create a secret

Store your Postgres credentials as a secret so the pipeline can connect to your database:

goldsky secret create BAYC_POSTGRES

When prompted, enter your Postgres connection string:

postgres://username:password@host:port/database

See managing secrets for details. If you already have a secret, find its name with goldsky secret list.

Define the pipeline

Create a file named bored-ape-events.yaml:

bored-ape-events.yaml

name: bored-ape-events
resource_size: s

sources:
  ethereum_raw_logs:
    type: dataset
    dataset_name: ethereum.raw_logs
    version: 1.0.0
    start_at: latest # Process data from the time this pipeline is created

transforms:
  # Decode every BAYC log using the contract ABI fetched from Etherscan
  bayc_decoded:
    type: sql
    primary_key: id
    sql: |
      SELECT
        id,
        address,
        _gs_log_decode(
          _gs_fetch_abi('https://api.etherscan.io/api?module=contract&action=getabi&address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&apikey=YOUR_KEY', 'etherscan'),
          topics,
          data
        ) as decoded,
        block_number,
        block_timestamp,
        transaction_hash
      FROM ethereum_raw_logs
      WHERE address = '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'

  # Unnest the decoded event name and parameters into flat columns
  bayc_events:
    type: sql
    primary_key: id
    sql: |
      SELECT
        id,
        address,
        decoded.event_signature as event_signature,
        decoded.event_params as event_params,
        block_number,
        block_timestamp,
        transaction_hash
      FROM bayc_decoded
      WHERE decoded IS NOT NULL

sinks:
  bayc_postgres:
    type: postgres
    from: bayc_events
    schema: public
    table: bored_ape_events
    secret_name: BAYC_POSTGRES
    primary_key: id

A quick tour of the pipeline:

Source: the ethereum.raw_logs dataset streams every event log on Ethereum. start_at: latest processes data from the time the pipeline is created; use start_at: earliest with a source-level filter on the contract address to backfill history via fast scan.
Transforms: the first transform filters to the BAYC contract address and decodes each log with _gs_log_decode, fetching the ABI from Etherscan with _gs_fetch_abi (replace YOUR_KEY with your own Etherscan API key). The second transform unnests the decoded event name and parameters. For a deeper explanation of this decoding pattern, see Decode contract events.
Sink: writes the decoded events to the public.bored_ape_events table, creating it automatically on first write. Change schema and table if you prefer different names.

If you only care about NFT transfers, skip the decoding entirely and use the curated ethereum.erc721_transfers dataset as your source; see EVM sources.

Validate and deploy

Check the configuration, then deploy:

goldsky turbo validate bored-ape-events.yaml
goldsky turbo apply bored-ape-events.yaml

Pass -i to apply to open the live inspect TUI right after deployment and watch events flow through each step.

Monitor the pipeline

Upon successful completion of these steps, an active pipeline is created and data should start appearing in your database shortly. To check on it at any time:

# Confirm the pipeline is running
goldsky turbo list

# Stream the pipeline's runtime logs
goldsky turbo logs bored-ape-events -f

# Watch live records at any step of the pipeline
goldsky turbo inspect bored-ape-events -n bayc_events

Query your data

Connect to your Postgres database and query the decoded events:

SELECT event_signature, count(*)
FROM public.bored_ape_events
GROUP BY event_signature
ORDER BY count(*) DESC;

Explore

For a full list of all available commands, use:

goldsky turbo --help

Or browse the Turbo CLI reference.

Can’t find what you’re looking for? Reach out to us at support@goldsky.com for help.

Turbo

Guides

Reference

Mirror (legacy)

Export contract events to Postgres

What you’ll need

Walkthrough

​What you’ll need

​Walkthrough

What you’ll need

Walkthrough