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

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

ENSDb Writer

Any application that writes 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, rindexer), as long as they follow the ENSDb Standard.

ENSDb Reader

Any application that reads ENS data from an ENSDb instance following the ENSDb Standard. For example, ENSApi is a reference implementation of an ENSDb Reader. Other implementations of ENSDb Readers can be built in any language, and can serve different types of APIs (GraphQL, REST, gRPC, etc.), as long as they follow the ENSDb Standard.

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 ENSIndexer 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 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 instances 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 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 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 indexing metadata context. The actual context data, whose structure may evolve over time as the needs of the ENSNode stack evolve. The object may include fields such as:

• version: The version of the Indexing Metadata Context structure
• indexingStatus: the current Indexing Status of the ENSIndexer instance.
• stackInfo: a group of public config objects that describe the ENSIndexer instance and its dependencies.

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 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

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 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
• Each ENSIndexer instance writes to and reads from the Ponder 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 Client — An ENSDb client implementation for querying ENSDb Metadata, and building custom queries against the ENSDb instance.
• EnsDbWriter Client — An ENSDb client implementation for writing ENSNode Metadata and executing ENSNode migrations.
• Schema Definitions — Drizzle schemas for ENSIndexer 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.

Related Documentation

• Database Schemas — Deep dive on schema types