Configuration File

Advanced TOML configuration for Graph Node

A TOML configuration file enables more complex Graph Node configurations than those exposed through CLI options. The configuration file location is specified with the --config command line flag.

When using a configuration file, you cannot use the --postgres-url, --postgres-secondary-hosts, and --postgres-host-weights CLI options.

Configuration Structure

The TOML configuration file consists of four main sections:

[chains]

Sets endpoints to blockchain clients

[store]

Describes available databases and shards

[ingestor]

Sets the node responsible for block ingestion

[deployment]

Describes how to place newly deployed subgraphs

Many configuration sections support environment variable expansion, especially Postgres connection strings. The official graph-node Docker image includes envsubst for complex use cases.

Basic Configuration

The simplest configuration is equivalent to using the --postgres-url command line option:

[store]
[store.primary]
connection = "postgresql://graph:password@localhost/graph"

[deployment]
[[deployment.rule]]
indexers = [ "index_node_1", "index_node_2" ]

Store Configuration

The [store] section defines database connections and sharding setup. At minimum, you must configure a primary shard.

Single Database Setup

[store]
[store.primary]
connection = "postgresql://graph:${PGPASSWORD}@primary/graph"
pool_size = 10

Connection String Format

The connection string must be a valid libpq connection string. Environment variables embedded in the string are expanded before passing to Postgres.

connection = "postgresql://graph:${PGPASSWORD}@${DB_HOST}/graph"

Connection Pool Size

Each shard must specify how many database connections each graph-node instance maintains in its connection pool.

Fixed Pool Size

Set a single value for all nodes:

[store.primary]
connection = "postgresql://graph:password@primary/graph"
pool_size = 10

Rule-Based Pool Size

Use different pool sizes for different node types based on node_id patterns:

[store.primary]
connection = "postgresql://graph:password@primary/graph"
pool_size = [
  { node = "index_node_general_.*", size = 20 },
  { node = "index_node_special_.*", size = 30 },
  { node = "query_node_.*", size = 80 }
]

Rules are checked in order, and the first matching rule is used. If no rule matches, configuration loading fails.

Always run graphman config pools $all_nodes after changing pool configuration to verify the expected connection counts. Replace $all_nodes with a space-separated list of all node names using this configuration.

Chain Configuration

The [chains] section controls blockchain provider connections and metadata storage.

Chain Structure

Configure a chain named mainnet in the [chains.mainnet] section:

[chains]
ingestor = "block_ingestor_node"

[chains.mainnet]
shard = "vip"
protocol = "ethereum"
polling_interval = 500
amp = "ethereum-mainnet"
provider = [
  { label = "mainnet1", url = "http://ethereum-node-1:8545", features = [] },
  { label = "mainnet2", url = "http://ethereum-node-2:8545", features = ["archive", "traces"] }
]

Chain Parameters

• shard: Database shard where chain data is stored
• protocol: Protocol type (ethereum, near, cosmos, arweave, starknet). Default: ethereum
• polling_interval: Block ingestor polling interval in milliseconds. Default: 500
• amp: Network name used by AMP for this chain. Defaults to chain name. Set when AMP uses different naming (e.g., amp = "ethereum-mainnet" for chain named mainnet)
• provider: List of providers for this chain

Provider Configuration

Each provider has:

• label: Provider name appearing in logs
• details: Provider connection details

Web3 Provider

[chains.mainnet]
shard = "primary"
provider = [
  {
    label = "mainnet",
    url = "http://ethereum-node:8545",
    features = ["archive", "traces"],
    headers = { Authorization = "Bearer token123" }
  }
]

[chains.near-mainnet]
shard = "blocks_b"
protocol = "near"
provider = [
  {
    label = "near-firehose",
    details = {
      type = "firehose",
      url = "https://firehose.example.com",
      key = "api-key-here",
      features = ["compression", "filters"]
    }
  }
]

[chains]
ingestor = "block_ingestor_node"

[chains.mainnet]
shard = "vip"
amp = "ethereum-mainnet"
provider = [
  { label = "mainnet1", url = "http://eth-node-1:8545", features = [] },
  { label = "mainnet2", url = "http://eth-node-2:8545", features = ["archive", "traces"] }
]

[chains.sepolia]
shard = "primary"
provider = [
  { label = "sepolia", url = "http://sepolia-node:8545", features = [] }
]

[chains.near-mainnet]
shard = "blocks_b"
protocol = "near"
provider = [
  {
    label = "near",
    details = {
      type = "firehose",
      url = "https://near-firehose.example.com",
      key = "api-key",
      features = ["compression", "filters"]
    }
  }
]

Provider Details

• type: web3 (default), firehose, or web3call
• transport: rpc (default), ws, or ipc
• url: Provider endpoint URL
• features: Array of supported features:
  • traces: Supports debug_traceBlockByNumber for call tracing
  • archive: Archive node with full historical state
  • no_eip1898: Doesn’t support EIP-1898 (block parameter by hash/number object)
  • no_eip2718: Doesn’t return type field in receipts (pre-EIP-2718 chains)
  • compression/<method>: Supports compression (gzip, brotli, or deflate)
  • For Firehose: compression and filters
• headers: HTTP headers for every request. Default: none
• limit: Maximum subgraphs using this provider. Default: unlimited
• token: Bearer token for Firehose providers
• key: API key for Firehose providers

Provider Limits (Experimental)

This feature is experimental and may be removed in future releases.

Limit the number of subgraphs per provider using node name patterns:

[chains.mainnet]
shard = "vip"
provider = [
  { label = "mainnet-0", url = "http://node-0:8545", features = [] },
  {
    label = "mainnet-1",
    url = "http://node-1:8545",
    features = [],
    match = [
      { name = "some_node_.*", limit = 10 },
      { name = "other_node_.*", limit = 0 }
    ]
  }
]

Nodes named some_node_.* use mainnet-1 for at most 10 subgraphs, then fall back to mainnet-0. Nodes named other_node_.* never use mainnet-1.

At least one provider should be unlimited. If a node’s name doesn’t match any rule, that provider is disabled for that node.

Deployment Configuration

The [deployment] section controls where new subgraph deployments are placed, determining both the storage shard and indexing node.

Deployment Rules

Rules are evaluated in order. The first matching rule determines placement.

[deployment]

# VIP subgraphs
[[deployment.rule]]
match = { name = "(vip|important)/.*" }
shard = "vip"
indexers = [ "index_node_vip_0", "index_node_vip_1" ]

# Kovan network subgraphs
[[deployment.rule]]
match = { network = "kovan" }
# No shard specified = uses 'primary'
indexers = [ "index_node_kovan_0" ]

# Multiple networks
[[deployment.rule]]
match = { network = [ "xdai", "poa-core" ] }
indexers = [ "index_node_other_0" ]

# Default catch-all rule (no match = matches everything)
[[deployment.rule]]
shards = [ "sharda", "shardb" ]
indexers = [
  "index_node_community_0",
  "index_node_community_1",
  "index_node_community_2",
  "index_node_community_3",
  "index_node_community_4",
  "index_node_community_5"
]

Rule Matching

The match element can contain:

• name: Regular expression matched against subgraph name
• network: String or list of strings compared to deployment’s network

The last rule must not have a match statement to ensure all deployments have a valid placement.

Rule Actions

• shard: Storage shard name (default: primary)
• shards: List of shards (system chooses the one with fewest active deployments)
• indexers: List of indexing nodes (deployment spreads evenly across listed nodes)

Indexer names must match the --node-id values used when starting index nodes.

Query Nodes

Configure nodes as query-only (no indexing) by adding to [general]:

[general]
query = "query_node_.*"

Nodes with --node-id matching the regex will:

• Only respond to queries
• Not connect to configured blockchain providers
• Not perform any indexing

Configuration Validation

Validate configuration file syntax and consistency:

graph-node --config config.toml config check

This checks for:

• Syntax errors
• Internal inconsistencies
• Undeclared shards referenced in deployment rules
• Invalid configuration combinations

Simulating Deployment Placement

Test where a subgraph would be deployed without making changes:

graphman --config config.toml config place some/subgraph mainnet

Output shows:

• Database shard for subgraph data
• List of potential indexing nodes
• Selection logic (node with fewest current subgraphs)

Complete Example

Full Production Configuration

# General settings
[general]
query = "query_node_.*"

# Store configuration
[store]
[store.primary]
connection = "postgresql://graph:${PGPASSWORD}@primary-db/graph"
weight = 0
pool_size = [
  { node = "index_node_.*", size = 20 },
  { node = "query_node_.*", size = 80 }
]

[store.primary.replicas.repl1]
connection = "postgresql://graph:${PGPASSWORD}@primary-repl1/graph"
weight = 1

[store.primary.replicas.repl2]
connection = "postgresql://graph:${PGPASSWORD}@primary-repl2/graph"
weight = 1

[store.vip]
connection = "postgresql://graph:${PGPASSWORD}@vip-db/graph"
weight = 1
pool_size = 25

[store.vip.replicas.repl1]
connection = "postgresql://graph:${PGPASSWORD}@vip-repl1/graph"
weight = 1

# Chain configuration
[chains]
ingestor = "block_ingestor_node"

[chains.mainnet]
shard = "vip"
amp = "ethereum-mainnet"
polling_interval = 500
provider = [
  {
    label = "mainnet-archive",
    url = "http://eth-archive:8545",
    features = ["archive", "traces"],
    headers = { Authorization = "Bearer ${ETH_API_TOKEN}" }
  },
  {
    label = "mainnet-regular",
    url = "http://eth-regular:8545",
    features = []
  }
]

[chains.sepolia]
shard = "primary"
provider = [
  { label = "sepolia", url = "http://sepolia:8545", features = [] }
]

# Deployment rules
[deployment]

[[deployment.rule]]
match = { name = "(vip|production)/.*" }
shard = "vip"
indexers = [ "index_node_vip_0", "index_node_vip_1" ]

[[deployment.rule]]
match = { network = "sepolia" }
indexers = [ "index_node_test_0" ]

[[deployment.rule]]
# Default catch-all
shards = [ "primary" ]
indexers = [
  "index_node_community_0",
  "index_node_community_1",
  "index_node_community_2"
]