diff --git a/docs/ensnode.io/config/integrations/starlight.ts b/docs/ensnode.io/config/integrations/starlight.ts index ba0bdc30f3..3c9b5e2f55 100644 --- a/docs/ensnode.io/config/integrations/starlight.ts +++ b/docs/ensnode.io/config/integrations/starlight.ts @@ -118,11 +118,30 @@ export function starlight(): AstroIntegration { label: "Overview", items: [ { - label: "Coming soon", + label: "Getting started", link: "/ensdb", }, ], }, + { + label: "Concepts", + collapsed: false, + autogenerate: { directory: "ensdb/concepts" }, + }, + { + label: "Using ENSDb", + collapsed: false, + autogenerate: { directory: "ensdb/usage" }, + }, + { + label: "Integrations", + collapsed: false, + autogenerate: { directory: "ensdb/integrations" }, + }, + { + label: "FAQ", + link: "/ensdb/faq", + }, ], }, { diff --git a/docs/ensnode.io/mindmap.md b/docs/ensnode.io/mindmap.md new file mode 100644 index 0000000000..b9f5962e28 --- /dev/null +++ b/docs/ensnode.io/mindmap.md @@ -0,0 +1,80 @@ +```mermaid +mindmap + root((ENSDb)) + Vision + Bi-directional ENS integration + Writers provide data about ENS + ENSIndexer indexes onchain data for ENS + Readers query data about ENS + ENSAwards queries ENS referrals to build dashboards + ENSApi queries data about resolver records to enable Protocol Acceleration + + Foundations + ENSDb instance + Database Schema + Ponder Schema + Exactly one per ENSDb instance + Schema Lifecycle managed by Ponder runtime + Shared + Among apps writing to the ENSDb instances + ENSIndexer instances + Among apps reading from the ENSDb instance + ENSApi instances + ENSNode Schema + Exactly one per ENSDb instance + Schema Lifecycle managed by ENSIndexer runtime + Shared + Among apps writing to the ENSDb instances + ENSIndexer instances + Among apps reading from the ENSDb instance + ENSApi instances + ENSIndexer Schema + At least one per ENSDb instance + Schema Lifecycle managed by Ponder runtime + Isolated writer + A single ENSIndexer can write data + Shared readers + Any number of readers can read data + + Operations + Infrastructure + Database Server + Serves at least one ENSDb instance + Writers + ENSIndexer instance + Writes into the ENSDb instance + Cached RPC requests + Ponder Schema + Indexed ENS onchain data + ENSIndexer Schema + ENSNode Metadata + ENSNode Schema + Readers + ENSApi instance + Reads from the ENSDb instance + Indexed ENS onchain data + ENSNode Metadata + Provides powerful APIs for querying data about ENS + Possible future ENS primitives + Event notifications + Cache invalidations + Advanced Dashboards + + Tools + Snapshot tool + Capabilities + Takes a snapshot of a selected ENSDb instance + Restores the ENSDb instance from the snapshot + Goals + Cut the cost of RPC requests + Cut the time needed to complete indexing from scratch + + Integrations + TypeScript + ENSDb SDK + ENSDb Reader + Drizzle client + ENSDb Writer + Any tech-stack + PostgreSQL client +``` diff --git a/docs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdx b/docs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdx new file mode 100644 index 0000000000..8c86f17571 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdx @@ -0,0 +1,10 @@ +--- +title: Architecture +description: Understanding the architecture of ENSDb, including its modular design and data flow. +sidebar: + label: Architecture + order: 3 +keywords: [ensdb, architecture, design, data flow] +--- + +This section explains the architecture of ENSDb, including its modular design and how data flows through the system. Understanding this architecture will help you work effectively with ENSDb. diff --git a/docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx b/docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx new file mode 100644 index 0000000000..4793bf7f6b --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx @@ -0,0 +1,10 @@ +--- +title: Database Schemas +description: Detailed explanation of all database schemas that make up ENSDb. +sidebar: + label: Database Schemas + order: 4 +keywords: [ensdb, database schemas, ponder schema, ensnode schema, ensindexer schema] +--- + +This section explains the different database schemas used in ENSDb, including the Ponder Schema, ENSNode Schema, and the modular ENSIndexer Schema. diff --git a/docs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdx b/docs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdx new file mode 100644 index 0000000000..44a79a6fce --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdx @@ -0,0 +1,219 @@ +--- +title: Glossary +description: Core terminology used throughout ENSDb documentation. +sidebar: + label: Glossary + order: 2 +keywords: [ensdb, glossary, terminology, definitions] +--- + +import { Aside } from '@astrojs/starlight/components'; + +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). + +### PostgreSQL Database + +A PostgreSQL database is an isolated collection of [database objects](#database-objects) managed by a [PostgreSQL server](#postgresql-server). + +### Database Schema + +A container that groups related [database objects](#database-objects). There can be multiple database schemas within a single [PostgreSQL database](#postgresql-database). Each database schema has a unique name within the [PostgreSQL database](#postgresql-database). + + + +### Database Objects + +Objects contained within a [database schema](#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](#postgresql-database) +- Rules and constraints for writers and readers +- A modular architecture enabling interoperability + +Any [PostgreSQL database](#postgresql-database) following the ENSDb Standard is an [ENSDb instance](#ensdb-instance). + +## ENSDb Concepts + +### Schema Definition + +For ENSDb, a Drizzle ORM object that defines the structure of [database objects](#database-objects) within a [database schema](#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](#schema-definition). Used to detect when the schema structure and/or semantics change. + +### ENSDb Instance + +A [PostgreSQL database](#postgresql-database) that follows the [ENSDb Standard](#ensdb-standard). An ENSDb instance stores indexed ENS data and is composed of three types of database schemas: + +- Exactly one [Ponder Schema](#ponder-schema) +- Exactly one [ENSNode Schema](#ensnode-schema) +- One or more [ENSIndexer Schemas](#ensindexer-schema) + +Multiple [ENSDb instances](#ensdb-instance) can be hosted on the same [PostgreSQL server](#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](#ensdb-instance) is multi-tenant because it can store data from multiple [ENSIndexer instances](#ensindexer-instance) (tenants) in isolated [ENSIndexer Schemas](#ensindexer-schema). + +Within a single [ENSDb instance](#ensdb-instance): +- Each [ENSIndexer instance](#ensindexer-instance) gets its own [ENSIndexer Schema](#ensindexer-schema) — fully isolated data following the [ENSIndexer Schema Definition](#schema-definition) that was current when the ENSIndexer instance started. +- All [ENSIndexer instances](#ensindexer-instance) share the [Ponder Schema](#ponder-schema), including the RPC cache. +- Metadata of all [ENSIndexer instances](#ensindexer-instance) is tracked in the [ENSNode Schema](#ensnode-schema) + +This enables separate indexing by multiple [ENSIndexer instance](#ensindexer-instance) with different configs. The configs may require indexing just certain chains. For example, one [ENSIndexer instance](#ensindexer-instance) is configured to index data just from the Ethereum Mainnet, while another [ENSIndexer instance](#ensindexer-instance) is configured to index data from both, Ethereum Mainnet, and Base Mainnet. Each of these [ENSIndexer instances](#ensindexer-instance) would have its own [ENSIndexer Schema](#ensindexer-schema) in the same [ENSDb instance](#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](#ponder-schema). The Ponder runtime also performs writes to the [ENSIndexer Schema](#ensindexer-schema) owned by the ENSIndexer instance. + +### Ponder Schema + +A [database schema](#database-schema) in the [ENSDb instance](#ensdb-instance) following the [Ponder Schema Definition](#ponder-schema-definition). It has a fixed `ponder_sync` name, and it serves as a shared RPC cache for all [ENSIndexer instances](#ensindexer-instance) connected to the [ENSDb instance](#ensdb-instance). It's lifecycle is managed by Ponder runtime. + +The Ponder Schema enables multiple [ENSIndexer instances](#ensindexer-instance) to share RPC cache, reducing costs and improving indexing speed. + +#### Ponder Schema Definition + +A [Schema Definition](#schema-definition) that defines the structure of the [Ponder Schema](#ponder-schema) in the [ENSDb instance](#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](#database-schema) in the [ENSDb instance](#ensdb-instance) following the [ENSNode Schema Definition](#ensnode-schema-definition). It has a fixed `ensnode` name, and it serves as a registry for all [ENSIndexer instances](#ensindexer-instance) that have ever connected to the [ENSDb instance](#ensdb-instance). It also stores metadata about these [ENSIndexer instances](#ensindexer-instance). + +### ENSNode Schema Definition + +A [Schema Definition](#schema-definition) that defines the structure of the [ENSNode Schema](#ensnode-schema) in the [ENSDb instance](#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](#ensnode-metadata-table). + +### ENSIndexer Schema + +A [database schema](#database-schema) within an [ENSDb instance](#ensdb-instance), used to store indexed ENS data. Each [ENSIndexer instance](#ensindexer-instance) owns exactly one ENSIndexer Schema, whose structure follows the [ENSIndexer Schema Definition](#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-name). + +#### ENSIndexer Schema Definition + +A [Schema Definition](#schema-definition) that defines the structure of an [ENSIndexer Schema](#ensindexer-schema). It is part of the ENSDb standard, maintained in the [ENSDb SDK](#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](#ensindexer-schema) in the [ENSDb instance](#ensdb-instance). This name is dynamic and determined by the [ENSIndexer instance](#ensindexer-instance) that owns the schema. + +Multiple [ENSIndexer Schema Names](#ensindexer-schema-name) exist in an [ENSDb instance](#ensdb-instance) when multiple [ENSIndexer instances](#ensindexer-instance) are connected. + +### ENSNode Metadata Table + +A table within the [ENSNode Schema](#ensnode-schema) that tracks all [ENSIndexer instances](#ensindexer-instance) that have ever connected to the [ENSDb instance](#ensdb-instance). + +| Column | Type | Purpose | +|--------|------|---------| +| `ens_indexer_schema_name` | `text` | References the [ENSIndexer Schema Name](#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](#indexing-metadata-context) of the [ENSIndexer instance](#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](#ensindexer-instance). + - `ensDbPublicConfig`: the public config of the [ENSDb instance](#ensdb-instance) that this [ENSIndexer instance](#ensindexer-instance) is connected to. + - `ensIndexerPublicConfig`: the public config of the [ENSIndexer instance](#ensindexer-instance) that this metadata record belongs to. + - `ensRainbowPublicConfig`: the public config of the ENSRainbow instance that this [ENSIndexer instance](#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](#ensdb-instance). + +- Any [ENSApi instance](#ensapi-instance) can connect to any [ENSDb instance](#ensdb-instance) +- Multiple [ENSApi instances](#ensapi-instance) can connect to the same [ENSDb instance](#ensdb-instance) for improved availability + +### ENSIndexer Instance + +A running ENSIndexer process that indexes onchain ENS data and writes to an [ENSIndexer Schema](#ensindexer-schema) in ENSDb. + +- Each [ENSIndexer instance](#ensindexer-instance) owns exactly one [ENSIndexer Schema](#ensindexer-schema) +- Multiple [ENSIndexer instances](#ensindexer-instance) can connect to one [ENSDb instance](#ensdb-instance) +- Each ENSIndexer instance has a row in the [ENSNode Metadata Table](#ensnode-metadata-table) + +### Indexing Status + +The status of an [ENSIndexer instance](#ensindexer-instance)'s indexing progress. + +The Indexing Status affects database behavior: + +- During **Backfill**, [indexes](#database-objects) on the [ENSIndexer Schema](#ensindexer-schema), if any, are dropped to optimize write performance. +- When transitioning to **Following**, [indexes](#database-objects) on the [ENSIndexer Schema](#ensindexer-schema) are created to optimize read performance. + +## Schema Discovery + +The process of finding all [ENSIndexer Schemas](#ensindexer-schema) in an [ENSDb instance](#ensdb-instance) by querying the [ENSNode Metadata Table](#ensnode-metadata-table): + +```sql +SELECT DISTINCT ens_indexer_schema_name +FROM ensnode.metadata; +``` + +This returns all [ENSIndexer Schema Names](#ensindexer-schema-name) that have been used by [ENSIndexer instances](#ensindexer-instance) connected to this [ENSDb instance](#ensdb-instance). + +## ENSDb SDK + + +A TypeScript package published as [`@ensnode/ensdb-sdk`](https://www.npmjs.com/package/@ensnode/ensdb-sdk) providing utilities for interacting with the [ENSDb instance](#ensdb-instance). + +The ENSDb SDK includes: + +- [EnsDbReader](#ensdb-reader) — Reader implementation for querying ENSDb Metadata, and building custom queries against the [ENSDb instance](#ensdb-instance). +- [EnsDbWriter](#ensdb-writer) — Writer implementation for ENSNode Metadata and ENSNode migrations. +- [Schema Definitions](#schema-definition) — Drizzle schemas for [ENSIndexer Schema](#ensindexer-schema) and [ENSNode Schema](#ensnode-schema) +- [Schema Checksums](#schema-checksum) — Deterministic checksums for ENSIndexer and ENSNode schema definitions. + + +### ENSDb Reader + +A class in [ENSDb SDK](#ensdb-sdk) for querying data from the [ENSDb instance](#ensdb-instance). + +### ENSDb Writer + +A class in [ENSDb SDK](#ensdb-sdk) that extends [ENSDb Reader](#ensdb-reader) with write capabilities. + +## Related Documentation + +- [Architecture](/ensdb/concepts/architecture) — How schemas relate and data flows +- [Database Schemas](/ensdb/concepts/database-schemas) — Deep dive on schema types diff --git a/docs/ensnode.io/src/content/docs/ensdb/concepts/index.mdx b/docs/ensnode.io/src/content/docs/ensdb/concepts/index.mdx new file mode 100644 index 0000000000..e288d32de5 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/concepts/index.mdx @@ -0,0 +1,44 @@ +--- +title: Overview +description: Understanding the fundamentals of ENSDb architecture, schemas, and data flow. +sidebar: + label: Overview + order: 1 +--- + +import { LinkCard } from '@astrojs/starlight/components'; + +## Who Should Read This + +- **Developers integrating with ENSDb** — Understand the schema structure to write effective queries +- **DevOps operators running ENSNode** — Understand how ENSDb behaves during different indexing phases +- **Anyone building custom writers or readers** — Learn the architecture for implementing the standard + +## Core Concepts + +Understanding these fundamentals will help you work effectively with ENSDb, whether you're querying data, integrating with third-party services, or operating an ENSNode instance. + + + + + + + +## Next Steps + +After understanding these concepts: + +1. **[Query ENSDb with SQL](/ensdb/usage/sql)** — Language-agnostic SQL examples +2. **[Use the TypeScript SDK](/ensdb/usage/sdk)** — Type-safe database access diff --git a/docs/ensnode.io/src/content/docs/ensdb/faq.mdx b/docs/ensnode.io/src/content/docs/ensdb/faq.mdx new file mode 100644 index 0000000000..e4ff4ccc82 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/faq.mdx @@ -0,0 +1,8 @@ +--- +title: Frequently Asked Questions +sidebar: + label: FAQ + order: 90 +--- + +This page answers the most common questions about ENSDb. diff --git a/docs/ensnode.io/src/content/docs/ensdb/index.mdx b/docs/ensnode.io/src/content/docs/ensdb/index.mdx index 55dc1f3656..cc815db2b9 100644 --- a/docs/ensnode.io/src/content/docs/ensdb/index.mdx +++ b/docs/ensnode.io/src/content/docs/ensdb/index.mdx @@ -1,7 +1,119 @@ --- -title: ENSDb Overview +title: Getting started with ENSDb +description: ENSDb is an open standard for bi-directional ENS integration. An ENSDb instance is a PostgreSQL database served from a PostgreSQL server — and a single server can serve multiple ENSDb instances. +sidebar: + label: Overview + order: 1 --- -:::caution[Work in Progress] -This documentation is under active development. -::: +import { LinkCard, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +## 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. + + + +## 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: + + + +Build specialized GraphQL or REST APIs tailored to your use case. Query exactly the data you need with full SQL power. + + +Create real-time dashboards and analytics pipelines. Better than Dune — you have the full ENS state locally with sub-second query latency. + + +Build command-line tools for ENS operations. Query domains, check expiration, analyze name patterns — all from your terminal. + + +Build reactive systems that respond to ENS state changes. Monitor registration lifecycles, ownership transfers, resolver updates. + + +Feed ENS data into your existing data infrastructure. Sync to data warehouses, trigger webhooks, populate search indexes. + + +Train machine learning models on complete ENS datasets. Predict name values, detect patterns, analyze market trends. + + + +## Quick Start + + + + + +## Documentation Structure + + + + + + + + + +## Related Projects + +- **[ENSIndexer](/ensindexer/)** — The reference ENSDb Writer implementation +- **[ENSApi](/ensapi/)** — The reference ENSDb Reader implementation diff --git a/docs/ensnode.io/src/content/docs/ensdb/integrations/ensnode.mdx b/docs/ensnode.io/src/content/docs/ensdb/integrations/ensnode.mdx new file mode 100644 index 0000000000..ceb9dd9307 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/integrations/ensnode.mdx @@ -0,0 +1,81 @@ +--- +title: ENSNode Reference Implementation +description: Overview of ENSNode, the reference implementation of the ENSDb standard, including its components and architecture. +sidebar: + label: ENSNode Reference Implementation + order: 1 +--- +import { Aside } from '@astrojs/starlight/components'; + +ENSNode is the reference implementation of the [ENSDb standard](/ensdb/concepts/glossary#ensdb-standard), providing a complete ecosystem of tools and services for building with ENSDb. Each ENSNode instance includes: +- At least one [ENSDb instance](/ensdb/concepts/glossary#ensdb-instance) — The PostgreSQL database following the ENSDb standard. +- At least one [ENSIndexer instance](/ensdb/concepts/glossary#ensindexer-instance) — The reference ENSDb Writer implementation that writes data into the ENSDb instance. +- At least one [ENSApi instance](/ensdb/concepts/glossary#ensapi-instance) — The reference ENSDb Reader implementation that serves GraphQL and REST APIs. + +```mermaid +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 + +``` + + + + +### Single PostgreSQL Server, Multiple ENSDb Instances + +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". + +```mermaid +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. diff --git a/docs/ensnode.io/src/content/docs/ensdb/usage/index.mdx b/docs/ensnode.io/src/content/docs/ensdb/usage/index.mdx new file mode 100644 index 0000000000..dd999644c7 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/usage/index.mdx @@ -0,0 +1,22 @@ +--- +title: Using ENSDb +description: Guides for integrating and using ENSDb in your applications. +sidebar: + label: Overview + order: 1 +--- +import { LinkCard } from '@astrojs/starlight/components'; + +You can interact with the ENSDb instance using the dedicated TypeScript SDK or the regular PostgreSQL interface. This section provides guides for both methods, as well as troubleshooting tips and answers to frequently asked questions. + + + + diff --git a/docs/ensnode.io/src/content/docs/ensdb/usage/sdk.mdx b/docs/ensnode.io/src/content/docs/ensdb/usage/sdk.mdx new file mode 100644 index 0000000000..6960983b1b --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/usage/sdk.mdx @@ -0,0 +1,41 @@ +--- +title: ENSDb SDK +sidebar: + label: ENSDb SDK + order: 2 +--- + +This page provides an overview of the ENSDb SDK and how to use it in your applications. + +## Intro + +For TypeScript projects, the [ENSDb SDK](/ensdb/concepts/glossary#ensdb-sdk) provides a convenient and efficient way to interact with your ENSDb instance. + +### Installation + +You can install the [`@ensnode/ensdb-sdk`](https://www.npmjs.com/package/@ensnode/ensdb-sdk) package from the NPM registry, using your preferred package manager: + +```bash +npm install @ensnode/ensdb-sdk +pnpm install @ensnode/ensdb-sdk +yarn add @ensnode/ensdb-sdk +``` + +### Example Usage + +```typescript +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() +``` diff --git a/docs/ensnode.io/src/content/docs/ensdb/usage/sql.mdx b/docs/ensnode.io/src/content/docs/ensdb/usage/sql.mdx new file mode 100644 index 0000000000..ada38d026b --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/usage/sql.mdx @@ -0,0 +1,50 @@ +--- +title: ENSDb SQL +sidebar: + label: ENSDb SQL + order: 3 +--- + +## Intro +This page provides an overview of the ENSDb SQL interface and how to use it in your applications. + +## Example Queries + +### 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`: + +```bash +# 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: + +```sql +SELECT DISTINCT ens_indexer_schema_name +FROM ensnode.metadata; +``` + +### Query Data + +Query data from your ENSDb instance: + +```sql +-- 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'; +``` diff --git a/docs/ensnode.io/src/content/docs/ensdb/usage/troubleshooting.mdx b/docs/ensnode.io/src/content/docs/ensdb/usage/troubleshooting.mdx new file mode 100644 index 0000000000..61c0dd8e80 --- /dev/null +++ b/docs/ensnode.io/src/content/docs/ensdb/usage/troubleshooting.mdx @@ -0,0 +1,8 @@ +--- +title: Troubleshooting +sidebar: + label: Troubleshooting + order: 99 +--- + +This page aggregates the most common issues users run into when operating an ENSDb instance. diff --git a/docs/ensnode.io/src/styles/starlight.css b/docs/ensnode.io/src/styles/starlight.css index 05b677b047..0e26f97508 100644 --- a/docs/ensnode.io/src/styles/starlight.css +++ b/docs/ensnode.io/src/styles/starlight.css @@ -87,10 +87,12 @@ max-width: var(--max-width-page); margin-inline: auto; } + nav.sidebar .sidebar-pane { position: sticky; height: calc(100vh - var(--sl-nav-height)); } + div.main-frame { padding-inline-start: initial; flex: 1; @@ -121,7 +123,7 @@ a[rel="prev"]:hover { color: var(--sl-color-accent); } -.content-panel + .content-panel { +.content-panel+.content-panel { border-top: 0; padding-top: 0; } @@ -136,14 +138,15 @@ a[rel="prev"]:hover { color: var(--sl-color-accent-high); } -.sl-markdown-content a:hover:not(:where(.not-content *)) > span { +.sl-markdown-content a:hover:not(:where(.not-content *))>span { color: var(--sl-color-accent); } -.sl-markdown-content :is(h1, h2, h3, h4, h5, h6) > a { +.sl-markdown-content :is(h1, h2, h3, h4, h5, h6)>a { color: var(--sl-color-white); display: inline; text-decoration: none; + &:hover { text-decoration: underline; } @@ -156,11 +159,17 @@ a[rel="prev"]:hover { .sl-markdown-content ul { list-style: disc; color: var(--sl-color-text); + list-style-position: inside; +} + +.sl-markdown-content ul ul { + margin-left: 1rem; } .sl-markdown-content ol { list-style: decimal; color: var(--sl-color-text); + list-style-position: inside; } .sl-markdown-content ol li::marker, @@ -179,7 +188,7 @@ a[rel="prev"]:hover { justify-content: space-between; margin-top: 3rem; - & > a { + &>a { flex-basis: unset; flex-grow: unset; width: fit-content; @@ -197,7 +206,7 @@ a[rel="prev"]:hover { margin-left: auto; } - & > span { + &>span { font-size: 0.75rem; .link-title { @@ -205,7 +214,7 @@ a[rel="prev"]:hover { } } - & > svg { + &>svg { align-self: self-end; color: var(--pagination-arrow-color); font-size: 1.25rem; @@ -213,7 +222,7 @@ a[rel="prev"]:hover { } } - & > a:hover > svg { + &>a:hover>svg { color: var(--sl-color-white); } } @@ -225,20 +234,22 @@ a[rel="prev"]:hover { } /* Styling for the list items to prepare for lines */ -#starlight__sidebar > div > ul > li { - position: relative; /* For absolute positioning of ::before */ +#starlight__sidebar>div>ul>li { + position: relative; + /* For absolute positioning of ::before */ } /* * Add padding-left only to items that will get a line, to make space for it. * Note, including :not(:last-child) to de-indent ENSAdmin. */ -#starlight__sidebar > div > ul > li:not(:first-child):not(:last-child) { - padding-left: 20px; /* Space for the line and content */ +#starlight__sidebar>div>ul>li:not(:first-child):not(:last-child) { + padding-left: 20px; + /* Space for the line and content */ } /* Add margin-bottom for the gap to all LIs except the very last one in the UL */ -#starlight__sidebar > div > ul > li:not(:last-child) { +#starlight__sidebar>div>ul>li:not(:last-child) { margin-bottom: var(--sidebar-item-gap); } @@ -246,17 +257,21 @@ a[rel="prev"]:hover { * Vertical line segment for relevant list items * Note, including :not(:last-child) to de-indent ENSAdmin. */ -#starlight__sidebar > div > ul > li:not(:first-child):not(:last-child)::before { +#starlight__sidebar>div>ul>li:not(:first-child):not(:last-child)::before { content: ""; position: absolute; - left: 8px; /* X-position of the vertical line */ + left: 8px; + /* X-position of the vertical line */ top: 0; - width: 1px; /* Thickness of the vertical line */ - background-color: var(--sl-color-hairline-light); /* Line color */ - height: 100%; /* Default height, covers the item itself */ + width: 1px; + /* Thickness of the vertical line */ + background-color: var(--sl-color-hairline-light); + /* Line color */ + height: 100%; + /* Default height, covers the item itself */ } -#starlight__sidebar > div > ul > li:not(:first-child):not(:last-child)::before { +#starlight__sidebar>div>ul>li:not(:first-child):not(:last-child)::before { height: calc(100% + var(--sidebar-item-gap)); } @@ -265,7 +280,8 @@ a[rel="prev"]:hover { /* Styles to replace the default Starlight sidebar icon with a custom image */ .starlight-sidebar-topics-icon svg { - display: none; /* Hide the default SVG icon */ + display: none; + /* Hide the default SVG icon */ } /* Default sidebar icon (parent) */