Glossary

This page defines the core terminology used throughout ENSDb documentation. If you encounter an unfamiliar term elsewhere, check here for its definition.

PostgreSQL Concepts

PostgreSQL Server

A running PostgreSQL server process that manages one or more databases.

PostgreSQL Database

A PostgreSQL database is an isolated collection of database objects managed by a PostgreSQL server.

Database Schema

A container that groups related database objects. There can be multiple database schemas within a single PostgreSQL database. Each database schema has a unique name within the PostgreSQL database.

Database Schema vs. Schema Definition

Database Schema is a PostgreSQL concept referring to a namespace for database objects. Schema Definition is a concept referring to a code-based object that defines the structure of database objects within a database schema.

Database Objects

Objects contained within a database schema, including:

• Tables
• Enums
• Indexes
• Constraints
• Relations

ENSDb Standard

An open standard for bi-directional ENS integration. The ENSDb Standard defines:

• Schema designs for storing ENS data in a PostgreSQL database
• Rules and constraints for writers and readers
• A modular architecture enabling interoperability

Any PostgreSQL database following the ENSDb Standard is an ENSDb instance.

ENSDb Concepts

Schema Definition

For ENSDb, a Drizzle ORM object that defines the structure of database objects within a database schema. Schema Definitions specify:

• Tables and their columns
• Column types
• Enums
• Indexes
• Constraints
• Relations

Schema Checksum

A deterministic checksum computed from a Schema Definition. Used to detect when the schema structure and/or semantics change.

ENSDb Instance

A PostgreSQL database that follows the ENSDb Standard. An ENSDb instance stores indexed ENS data and is composed of three types of database schemas:

• Exactly one Ponder Schema
• Exactly one ENSNode Schema
• One or more ENSIndexer Schemas

Multiple ENSDb instances can be hosted on the same PostgreSQL server. For example:

• One ENSDb instance could be used for production workloads and include data for the “mainnet” ENS Namespace.
• At the same time, another ENSDb instance could be used for testing workloads and include data for the “sepolia” ENS Namespace.
• At the same time, another ENSDb instance could be used for local development workloads and include data for the “ens-test-env” ENS Namespace.

Multi-Tenant ENSDb instance

An ENSDb instance is multi-tenant because it can store data from multiple ENSIndexer instances (tenants) in isolated ENSIndexer Schemas.

Within a single ENSDb instance:

• Each ENSIndexer instance gets its own ENSIndexer Schema — fully isolated data following the ENSIndexer Schema Definition that was current when the ENSIndexer instance started.
• All ENSIndexer instances share the Ponder Schema, including the RPC cache.
• Metadata of all ENSIndexer instances is tracked in the ENSNode Schema

This enables separate indexing by multiple ENSIndexer instance with different configs. The configs may require indexing just certain chains. For example, one ENSIndexer instance is configured to index data just from the Ethereum Mainnet, while another ENSIndexer instance is configured to index data from both, Ethereum Mainnet, and Base Mainnet. Each of these ENSIndexer instances would have its own ENSIndexer Schema in the same ENSDb instance.

Ponder runtime

Ponder runtime is executed by the ENSIndexer instance. It manages fetching onchain data, and having it cached in RPC cache inside the Ponder Schema. The Ponder runtime also performs writes to the ENSIndexer Schema owned by the ENSIndexer instance.

Ponder Schema

A database schema in the ENSDb instance following the Ponder Schema Definition. It has a fixed ponder_sync name, and it serves as a shared RPC cache for all ENSIndexer instances connected to the ENSDb instance. It’s lifecycle is managed by Ponder runtime.

The Ponder Schema enables multiple ENSIndexer instances to share RPC cache, reducing costs and improving indexing speed.

Ponder Schema Definition

A Schema Definition that defines the structure of the Ponder Schema in the ENSDb instance. This Schema Definition is an implementation detail of Ponder, so we treat is as an opaque black box in ENSDb documentation.

ENSNode Schema

A database schema in the ENSDb instance following the ENSNode Schema Definition. It has a fixed ensnode name, and it serves as a registry for all ENSIndexer instances that have ever connected to the ENSDb instance. It also stores metadata about these ENSIndexer instances.

ENSNode Schema Definition

A Schema Definition that defines the structure of the ENSNode Schema in the ENSDb instance. The ENSNode Schema Definition is part of the ENSDb standard and is maintained in the ENSDb SDK. It includes the definition of the ENSNode Metadata Table.

ENSIndexer Schema

A database schema within an ENSDb instance, used to store indexed ENS data. Each ENSIndexer instance owns exactly one ENSIndexer Schema, whose structure follows the ENSIndexer Schema Definition that was current when the instance first started. The schema’s name is determined at startup, when the ENSIndexer instance connects to the ENSDb instance and creates its schema using the configured ENSIndexer Schema Name.

ENSIndexer Schema Definition

A Schema Definition that defines the structure of an ENSIndexer Schema. It is part of the ENSDb standard, maintained in the ENSDb SDK, and specifies the core tables and columns used to store indexed ENS data.

ENSIndexer Schema Name

The name of a specific ENSIndexer Schema in the ENSDb instance. This name is dynamic and determined by the ENSIndexer instance that owns the schema.

Multiple ENSIndexer Schema Names exist in an ENSDb instance when multiple ENSIndexer instances are connected.

ENSNode Metadata Table

A table within the ENSNode Schema that tracks all ENSIndexer instances that have ever connected to the ENSDb instance.

Column	Type	Purpose
ens_indexer_schema_name	text	References the ENSIndexer Schema Name of the ENSIndexer instance that manages this metadata record
key	text	Type of metadata record
value	jsonb	The context object (configuration, status, etc.)

Primary key: (ens_indexer_schema_name, key)

The value column stores a JSON object which structure may evolve over time. To track this, the JSON object is guaranteed to always include a version field indicating the version of the structure. This allows for future-proofing as the metadata needs evolve.

Metadata Keys

The key column identifies the type of metadata:

Key	Description
indexing_metadata_context	Indexing metadata context of the ENSIndexer instance

Indexing Metadata Context

A JSON object that provides context about the ENSNode stack the Indexing Status. It includes:

• version: The version of the Indexing Metadata Context structure
• data: The actual context data, whose structure may evolve over time as the needs of the ENSNode stack evolve. The data object may include fields such as:
  • indexingStatus: the current Indexing Status of the ENSIndexer instance.
  • ensDbPublicConfig: the public config of the ENSDb instance that this ENSIndexer instance is connected to.
  • ensIndexerPublicConfig: the public config of the ENSIndexer instance that this metadata record belongs to.
  • ensRainbowPublicConfig: the public config of the ENSRainbow instance that this ENSIndexer instance is connected to. Might be null during the ENSNode stack cold start, when the ENSIndexer instance starts before the ENSRainbow instance.

ENSApi Instance

A running ENSApi process that serves GraphQL and REST APIs from an ENSDb instance.

• Any ENSApi instance can connect to any ENSDb instance
• Multiple ENSApi instances can connect to the same ENSDb instance for improved availability

ENSIndexer Instance

A running ENSIndexer process that indexes onchain ENS data and writes to an ENSIndexer Schema in ENSDb.

• Each ENSIndexer instance owns exactly one ENSIndexer Schema
• Multiple ENSIndexer instances can connect to one ENSDb instance
• Each ENSIndexer instance has a row in the ENSNode Metadata Table

Indexing Status

The status of an ENSIndexer instance’s indexing progress.

The Indexing Status affects database behavior:

• During Backfill, indexes on the ENSIndexer Schema, if any, are dropped to optimize write performance.
• When transitioning to Following, indexes on the ENSIndexer Schema are created to optimize read performance.

Schema Discovery

The process of finding all ENSIndexer Schemas in an ENSDb instance by querying the ENSNode Metadata Table:

SELECT DISTINCT ens_indexer_schema_name
FROM ensnode.metadata;

This returns all ENSIndexer Schema Names that have been used by ENSIndexer instances connected to this ENSDb instance.

ENSDb SDK

A TypeScript package published as @ensnode/ensdb-sdk providing utilities for interacting with the ENSDb instance.

The ENSDb SDK includes:

• EnsDbReader — Reader implementation for querying ENSDb Metadata, and building custom queries against the ENSDb instance.
• EnsDbWriter — Writer implementation for ENSNode Metadata and ENSNode migrations.
• Schema Definitions — Drizzle schemas for ENSIndexer Schema and ENSNode Schema
• Schema Checksums — Deterministic checksums for ENSIndexer and ENSNode schema definitions.

ENSDb Reader

A class in ENSDb SDK for querying data from the ENSDb instance.

ENSDb Writer

A class in ENSDb SDK that extends ENSDb Reader with write capabilities.

Related Documentation

• Architecture — How schemas relate and data flows
• Database Schemas — Deep dive on schema types