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 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 ENSDb Writers, ENSDb Metadata Writers, and ENSDb Readers
A modular architecture enabling interoperability

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

ENSNode Plugin

An abstract specification that determines how a specific aspect of the ENS namespace is indexed into ENSDb. A plugin defines: a name, datasources (which onchain contracts to index as a function of the ENS namespace), dependency relationships with other plugins, an indexed data model with indexes, and standards and invariants for how onchain events are translated into that indexed data model during indexing. Any ENSDb Writer can have multiple plugins implementing the ENSNode Plugin standard.

ENSDb Writer

Any application that implements one or more standard-compliant ENSNode Plugins and also implements an ENSDb Metadata Writer. An ENSDb Writer is responsible for writing ENS data into an ENSDb instance following the ENSDb Standard. For example, ENSIndexer is a reference implementation of an ENSDb Writer. Other implementations of ENSDb Writers can be built in any language, and can use different indexing frameworks (i.e. Ponder, Envio, rindexer, Amp from Edge & Node, etc.), as long as they follow the ENSDb Standard.

ENSDb Metadata Writer

Any application that writes metadata about an ENSDb Writer into an ENSDb instance following the ENSDb Standard. For example, ENSIndexer is a reference implementation of an ENSDb Metadata Writer, which writes Indexing Metadata Context records into the ENSNode Metadata Table for each ENSIndexer instance that has ever connected to the ENSDb instance. Other implementations of ENSDb Metadata Writers can be built in any language, as long as they follow the ENSDb Standard.

ENSDb Reader

Any application that reads ENS data from an ENSDb instance following the ENSDb Standard. It knows how to read state from ENSDb, including overall metadata from the relevant ENSDb Writer instance(s) and (where relevant) data associated with the ENSNode Plugins relevant to the specific ENSDb Reader implementation. For example, ENSApi is a reference implementation of an ENSDb Reader. Other implementations of ENSDb Readers can be built in any language, as long as they follow the ENSDb Standard. Any implementation of an ENSDb Reader can support different types of interfaces (i.e. MCP, CLI, GraphQL, REST, gRPC, etc.), depending on the use case it is designed for.

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

ENSDb Instance

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

Exactly one ENSNode Schema
One or more ENSDb Writer Schemas

Multi-Tenant ENSDb instance

This example is based on reference implementations, but the ENSDb standard is implementation-agnostic, so this is just one possible design.

An ENSDb instance is considered multi-tenant when it stores data from multiple ENSDb Writer instances (tenants) in isolated ENSDb Writer Schemas.

Within a single ENSDb instance:

Each ENSDb Writer instance gets its own ENSDb Writer Schema — fully isolated data following the ENSDb Writer Schema Definition that was current when the instance started.
Metadata of all ENSDb Writer instances is tracked in the ENSNode Schema

This enables separate indexing by multiple ENSDb Writer instances with different configs. The configs may require indexing just certain chains. For example, one ENSDb Writer instance is configured to index data just from the Ethereum Mainnet, while another ENSDb Writer instance is configured to index data from both, Ethereum Mainnet, and Base Mainnet. Each of these ENSDb Writer instances would have its own ENSDb Writer 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 ENSDb Writer Schema owned by the ENSIndexer instance.

Ponder Schema

A database schema in the ENSDb instance following the Ponder Schema Definition. It is an implementation detail of ENSIndexer. It has a fixed ponder_sync name, and it serves as a shared RPC cache for all ENSIndexer instances connected to the ENSDb instance. Its 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 it 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 ENSDb Writer instances that have ever connected to the ENSDb instance. It also stores metadata about these ENSDb Writer 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.

ENSDb Writer Schema

A database schema within an ENSDb instance, used to store indexed ENS data. Each ENSDb Writer instance owns exactly one ENSDb Writer Schema, whose structure follows the ENSNode Plugins implemented by the instance. The schema’s name is determined at startup, when the ENSDb Writer instance connects to the ENSDb instance and creates its schema using the configured ENSDb Writer Schema Name.

ENSDb Writer Schema Definition

A Schema Definition that defines the structure of an ENSDb Writer Schema. It specifies the core tables and columns used to store indexed ENS data and is configured by the ENSNode Plugins implemented by the ENSDb Writer instance that owns this ENSDb Writer Schema. Each time a new version of an ENSNode Plugin is released with changes to the indexed data model, the ENSDb Writer Schema Definition may be updated to reflect those changes.

ENSDb Writer Schema Name

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

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

ENSNode Metadata Table

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

Column	Type	Purpose
`ens_indexer_schema_name`	`text`	References the ENSDb Writer Schema Name of the ENSDb Writer 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 for the ENSDb Writer instance

Indexing Metadata Context

A data model that describes indexing metadata context. The actual context data structure may evolve over time as the needs of the ENSNode stack evolve. The data model may include fields such as:

version: The version of the Indexing Metadata Context structure
indexingStatus: the current Indexing Status of the ENSDb Writer instance (i.e. the Indexing Status of the ENSDb Writer instance).
stackInfo: describes the ENSDb Writer instance and its config, dependencies, etc.

ENSApi

A reference implementation of an ENSDb Reader that serves GraphQL and REST APIs from an ENSDb instance. It is a backend app built on top of Hono.

ENSApi Instance

A running ENSApi process.

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

ENSIndexer

A reference implementation of an ENSDb Writer that indexes onchain ENS data and writes to an ENSDb instance. It is built on top of Ponder, a modular blockchain indexing framework. ENSIndexer is also an implementation of an ENSDb Metadata Writer. It writes metadata about itself into the ENSNode Metadata Table in the ENSDb instance.

ENSIndexer Instance

A running ENSIndexer process.

Each ENSIndexer instance owns exactly one ENSDb Writer Schema
Each ENSIndexer instance writes to and reads from the shared Ponder Schema
Multiple ENSIndexer instances can connect to one ENSDb instance
Each ENSIndexer instance owns exactly one row in the ENSNode Metadata Table and writes to it regularly via its ENSDb Metadata Writer implementation.

Indexing Status

The status of an ENSDb Writer instance’s indexing progress.

The Indexing Status affects database behavior:

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

Schema Discovery

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

SELECT DISTINCT ens_indexer_schema_name
FROM ensnode.metadata;

This returns all ENSDb Writer Schema Names that have been used by ENSDb Writer instances ever 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:

ENSDb Reader Client — An ENSDb client implementation for querying ENSDb Metadata, and building custom queries against the ENSDb instance.
ENSDb Writer Client — An ENSDb client implementation for writing ENSNode Metadata and executing ENSNode migrations.
Schema Definitions — Drizzle schemas for ENSDb Writer Schema and ENSNode Schema.

ENSDb Reader Client

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

ENSDb Writer Client

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

Database Schemas — Deep dive on schema types