Getting started with ENSDb

Vision

Get the whole onchain state of ENS in your database.

Core Philosophy

Open Standard

ENSDb is an open standard for bi-directional ENS integration. It defines a carefully crafted set of database schema designs, rules, and constraints for storing the entire ENS onchain state in a PostgreSQL database — making the data accessible from any programming language.

Any app following the standard can:

• Perform write operations to produce an ENSDb instance.
• Perform read operations against the ENSDb instance.

Build in Any Language

Each ENSDb instance is a standard PostgreSQL database, so to interact with it, you can use any programming language that has a PostgreSQL driver. Python, Go, Rust, JavaScript, Ruby, Java, C# — the choice is yours.

Reference Implementation

ENSNode is the reference implementation of the ENSDb standard, providing a complete ecosystem of tools and services for building with ENSDb. Each ENSNode instance includes:

• ENSDb instance — The PostgreSQL database following the ENSDb standard.
• ENSIndexer instance — The reference ENSDb Writer implementation that writes data into the ENSDb instance.
• ENSApi instance — The reference ENSDb Reader implementation that serves GraphQL and REST APIs.

flowchart LR
    subgraph ENSNode["ENSNode Environment"]
        subgraph ENSNodeMainnet["ENSNode 'Mainnet' instance"]
            direction LR
            ENSIndexerMainnet[ENSIndexer 'Mainnet' instance]
            ENSApiMainnet@{ shape: procs, label: "ENSApi Mainnet instances" }
        end

        subgraph ENSNodeSepolia["ENSNode 'Sepolia' instance"]
            direction LR
            ENSIndexerSepolia[ENSIndexer 'Sepolia' instance]
            ENSApiSepolia[ENSApi 'Sepolia' instance]
        end
    end

    subgraph PostgreSQLServer["PostgreSQL Server instance"]
        ENSDbMainnet[(ENSDb 'Mainnet' instance)]
        PSMainnet(Ponder Schema)
        NSMainnet(ENSNode Schema)
        EISMainnet@{ shape: procs, label: "ENSIndexer Schema" }

        ENSDbMainnet -->|1..1| PSMainnet
        ENSDbMainnet -->|1..1| NSMainnet
        ENSDbMainnet -->|1..*| EISMainnet


        ENSDbSepolia[(ENSDb 'Sepolia' instance)]
        PSSepolia(Ponder Schema)
        NSSepolia(ENSNode Schema)
        EISSepolia@{ shape: procs, label: "ENSIndexer Schema" }

        ENSDbSepolia -->|1..1| PSSepolia
        ENSDbSepolia -->|1..1| NSSepolia
        ENSDbSepolia -->|1..*| EISSepolia
    end
    
    ENSIndexerMainnet -->|Write| ENSDbMainnet
    ENSIndexerSepolia -->|Write| ENSDbSepolia
    ENSApiMainnet -->|Read| ENSDbMainnet
    ENSApiSepolia -->|Read| ENSDbSepolia

Build Your Own

You can build custom writers, readers, or both. The standard is implementation-agnostic.

What is an ENSDb Instance?

An ENSDb instance is a PostgreSQL database that follows the ENSDb open standard. Key characteristics:

Aspect	Description
What it is	A PostgreSQL database (logical database within a server)
Where it runs	Served from a PostgreSQL server
Multi-tenancy	One ENSDb instance can store data from multiple ENSIndexer instances (tenants)
Contains	Complete indexed ENS state, and ENSNode Metadata

Example: Multi-Instance Server

A single PostgreSQL server can serve multiple ENSDb instances for different ENS Namespaces. This allows you to have separate ENSDb instances based on your needs. For example:

• Your production environment can have a dedicated ENSDb instance for ENS data from the ENS Namespace “mainnet”.
• Your staging environment can have a separate ENSDb instance for ENS data from the ENS Namespace “sepolia”.
• Your local development environment can have its own ENSDb instance for testing with local or ephemeral data from the ENS Namespace “ens-test-env”.

flowchart TB
    subgraph PGServer["PostgreSQL Server"]
        direction TB
        Mainnet[(ENSDb Mainnet instance)]
        Testnet[(ENSDb Sepolia instance)]
        Devnet[(ENSDb ENS Test Env instance)]
    end

Each ENSDb instance is an independent database containing complete ENS data for its respective environment.

What You Get

Complete ENS State

An ENSDb instance contains the entire onchain state of ENS:

• All domains (ENSv1 and ENSv2)
• All registrations and renewals
• All resolver records and text records
• All events and ownership history
• All NFT/token data for names

PostgreSQL Benefits

By building on a PostgreSQL database, ENSDb inherits world-class capabilities:

• ACID transactions — Data integrity guarantees
• Complex queries — Joins, aggregations, window functions
• Scalability — Replication, sharding, connection pooling
• Ecosystem — Mature tools, ORMs, dashboards, analytics platforms
• Reliability — Decades of production-proven technology

What You Can Build

ENSDb unlocks a new universe of ENS applications:

Custom APIs

Build specialized GraphQL or REST APIs tailored to your use case. Query exactly the data you need with full SQL power.

Analytics & Dashboards

Create real-time dashboards and analytics pipelines. Better than Dune — you have the full ENS state locally with sub-second query latency.

CLIs & Developer Tools

Build command-line tools for ENS operations. Query domains, check expiration, analyze name patterns — all from your terminal.

Event-Based Engines

Build reactive systems that respond to ENS state changes. Monitor registration lifecycles, ownership transfers, resolver updates.

Data Pipelines

Feed ENS data into your existing data infrastructure. Sync to data warehouses, trigger webhooks, populate search indexes.

AI & ML Models

Train machine learning models on complete ENS datasets. Predict name values, detect patterns, analyze market trends.

Quick Start

Connect with Any PostgreSQL Client

Connect to an ENSDb instance (a PostgreSQL database). The examples below assume you that ENSDb instances are served from a PostgreSQL server at host:5432 with databases named ensdb_mainnet, ensdb_testnet, and ensdb_devnet:

# Production environment (mainnet data)
psql postgresql://user:password@host:5432/ensdb_mainnet

# Pre-production environment (testnet data)
psql postgresql://user:password@host:5432/ensdb_testnet

# Staging / local development environment
psql postgresql://user:password@host:5432/ensdb_devnet

Discover Available Schemas

Once connected to an ENSDb instance, discover its ENSIndexer Schemas:

SELECT DISTINCT ens_indexer_schema_name
FROM ensnode.metadata;

Query Indexed Data

Query data from a specific ENSIndexer Schema within your ENSDb instance:

-- Get domains from the ENSIndexer Schema with the `ensindexer_mainnet` ENSIndexer Schema Name
SELECT * FROM ensindexer_mainnet.v1_domains LIMIT 10;

-- Get indexing status for the ENSNode Schema with the `ensindexer_mainnet` ENSIndexer Schema Name
SELECT * FROM "ensnode"."metadata"
WHERE ens_indexer_schema_name = 'ensindexer_mainnet'
AND key = 'ensindexer_indexing_status'
AND value -> 'data' -> 'omnichainSnapshot' ->> 'omnichainStatus' = 'omnichain-following';

Use the TypeScript SDK

For TypeScript projects, the ENSDb SDK provides typed access:

import { EnsDbReader } from '@ensnode/ensdb-sdk';

// Connect to a specific ENSDb instance by providing its connection string and
// the ENSIndexer Schema Name you want to query
const ensDbReader =  new EnsDbReader(ensDbConnectionString, ensIndexerSchemaName);

// Get domains from the ENSIndexer Schema
const v1Domains = await
 ensDbReader.ensDb.select()
  .from(ensDbReader.ensIndexerSchema.v1Domain)
  .limit(10);

// Get indexing status
const indexingStatus = await ensDbReader.getIndexingStatusSnapshot()

Documentation Structure

Concepts Understand ENSDb architecture, schemas, and data flow

Related Projects

• ENSIndexer — The reference ENSDb Writer implementation
• ENSApi — The reference ENSDb Reader implementation