Nethereum.BlockchainStore.Postgres 7.0.0

Nethereum.BlockchainStore.Postgres

PostgreSQL implementation of the Nethereum blockchain storage layer using Entity Framework Core and Npgsql.

Overview

Nethereum.BlockchainStore.Postgres provides the PostgreSQL-specific DbContext, context factory, and DI registration for storing indexed Ethereum blockchain data. It inherits from Nethereum.BlockchainStore.EFCore.BlockchainDbContextBase and configures Npgsql with lowercase naming conventions.

This package is used by the blockchain processing pipeline to persist blocks, transactions, logs, contracts, internal transactions, and chain state to PostgreSQL. It is also used by the Explorer to query indexed data.

Key Features

• PostgresBlockchainDbContext configured with UseNpgsql() and UseLowerCaseNamingConvention()
• PostgresBlockchainDbContextFactory implementing IBlockchainDbContextFactory for short-lived context creation
• AddPostgresBlockchainStorage() DI extension that registers the factory and all EFCore repositories
• EF Core migrations for the full blockchain schema (blocks, transactions, logs, contracts, internal transactions, chain state, account state, address transactions)
• Design-time factory for dotnet ef migrations tooling

Installation

dotnet add package Nethereum.BlockchainStore.Postgres

Targets net8.0 and net10.0. Uses Npgsql.EntityFrameworkCore.PostgreSQL 8.x on net8.0 and 10.x on net10.0.

Dependencies

• Nethereum.BlockchainStore.EFCore - Base BlockchainDbContextBase, entity builders, and repository implementations
• Npgsql.EntityFrameworkCore.PostgreSQL - PostgreSQL EF Core provider
• EFCore.NamingConventions - UseLowerCaseNamingConvention() for lowercase table/column names
• Microsoft.EntityFrameworkCore.Design - Design-time migration support (private asset)

Quick Start

using Nethereum.BlockchainStore.Postgres;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("PostgresConnection");

builder.Services.AddPostgresBlockchainStorage(connectionString);

This single call registers:

• IBlockchainDbContextFactory as PostgresBlockchainDbContextFactory
• All repository implementations via AddBlockchainRepositories() (IBlockRepository, ITransactionRepository, ITransactionLogRepository, IContractRepository, etc.)

Usage Examples

Run Migrations

cd src/Nethereum.BlockchainStore.Postgres

dotnet ef migrations add InitialCreate \
  --context PostgresBlockchainDbContext

dotnet ef database update \
  --context PostgresBlockchainDbContext

The design-time factory (PostgresBlockchainDesignTimeDbContextFactory) is used only by the dotnet ef tooling and returns a context with a hardcoded local connection string (Host=localhost;Database=design;Username=postgres;Password=postgres). It does not read appsettings.json. Point your tooling at a scratch design database, or edit the factory, when generating migrations.

Programmatic Migration

var factory = new PostgresBlockchainDbContextFactory(connectionString);
using var context = factory.CreateContext();
await context.Database.MigrateAsync();

Direct Context Usage

var factory = new PostgresBlockchainDbContextFactory(connectionString);
using var context = factory.CreateContext();

var latestBlock = await context.Blocks
    .Where(b => b.IsCanonical)
    .OrderByDescending(b => b.BlockNumber)
    .FirstOrDefaultAsync();

var txCount = await context.Transactions
    .Where(t => t.BlockNumber == latestBlock.BlockNumber && t.IsCanonical)
    .CountAsync();

With Block Storage Processor

var dbContextFactory = new PostgresBlockchainDbContextFactory(connectionString);
var repoFactory = new BlockchainStoreRepositoryFactory(dbContextFactory);

var steps = new BlockStorageProcessingSteps(repoFactory);
var orchestrator = new BlockCrawlOrchestrator(web3.Eth, steps);
orchestrator.ContractCreatedCrawlerStep.RetrieveCode = true;

var processor = new BlockchainProcessor(
    orchestrator,
    repoFactory.CreateBlockProgressRepository(),
    lastConfirmedBlockService);

await processor.ExecuteAsync(cancellationToken);

Connection String Resolution

The PostgresBlockchainDbContext constructor takes only an explicit connection string. The fallback resolution from configuration is performed by the static PostgresBlockchainDbContextFactory.Create(IConfigurationRoot) method, which resolves in this order:

1. ConnectionStrings:PostgresConnection from appsettings.json
2. ConnectionStrings:BlockchainDbStorage from appsettings.json (via GetBlockchainStorageConnectionString())

Database Schema

All table and column names use lowercase convention via EFCore.NamingConventions.

Tables

Numeric fields (blocknumber, timestamp, transactionindex, logindex, nonce, transactiontype) are stored as bigint (long). Gas and value fields remain as character varying(100) strings to accommodate full uint256 range.

Related Packages

Used By (Consumers)

• Nethereum.BlockchainStorage.Processors.Postgres - Hosted services that orchestrate the processing pipeline against this database
• Nethereum.Explorer - Blazor Server explorer that queries indexed data via IBlockchainDbContextFactory
• Nethereum.Aspire.Indexer - Aspire-hosted indexer worker

Dependencies

• Nethereum.BlockchainStore.EFCore - Base DbContext, entity builders, repositories

See Also

• Nethereum.BlockchainStore.EFCore - Database-agnostic EF Core base
• Nethereum.BlockchainStorage.Processors.Postgres - Processing hosted services
• Nethereum.BlockchainProcessing - Processing framework and entity definitions