peeringdb-plus

PeeringDB Plus

A high-performance, globally distributed, read-only mirror of PeeringDB data. Syncs all PeeringDB objects on a configurable schedule, stores them in SQLite with edge replication via LiteFS on Fly.io, and serves the data through five API surfaces.

Live instance: peeringdb-plus.fly.dev

API Surfaces

The root endpoint (GET /) returns a JSON service discovery document. Terminal clients receive help text; browsers redirect to the Web UI.

Quick Start

Local (Go)

go build -o peeringdb-plus ./cmd/peeringdb-plus
./peeringdb-plus
# Listening on :8080, syncing from api.peeringdb.com every hour

Local (Docker)

docker build -t peeringdb-plus .
docker run -p 8080:8080 peeringdb-plus

The database is stored at /data/peeringdb-plus.db inside the container. Mount a volume to persist data across restarts:

docker run -p 8080:8080 -v pdbdata:/data peeringdb-plus

Prerequisites

• Go 1.26+

All code generation tools (buf, templ, gqlgen) are Go tool dependencies declared in go.mod and require no separate installation.

Data Sync

PeeringDB data is synced automatically on a configurable interval (default: hourly). The sync runs on the primary node only; replicas receive updates via LiteFS replication.

• Modes: full (complete re-fetch, default) or incremental (only modified objects since last sync).
• On-demand trigger: POST /sync with X-Sync-Token header (requires PDBPLUS_SYNC_TOKEN to be set). Accepts ?mode=full|incremental.
• Readiness: /readyz reports unhealthy until the first sync completes and degrades if sync data exceeds the staleness threshold (default: 24h).

Configuration

All configuration is via environment variables, validated at startup (fail-fast).

Standard OTEL_* environment variables are also supported (autoexport).

ConnectRPC / gRPC

All 13 PeeringDB entity types are available via ConnectRPC with Get, List, and Stream RPCs. The server supports Connect, gRPC, and gRPC-Web protocols on the same endpoints.

Service Discovery

# List all services (requires grpcurl or buf curl)
grpcurl -plaintext localhost:8080 list

# Describe a service
grpcurl -plaintext localhost:8080 describe peeringdb.v1.NetworkService

gRPC reflection (v1 and v1alpha) and health checks are enabled.

Unary RPCs

# Get a single network by ID
buf curl --protocol grpc --http2-prior-knowledge \
  http://localhost:8080/peeringdb.v1.NetworkService/GetNetwork \
  -d '{"id": 42}'

# List networks with filters and pagination
buf curl --protocol grpc --http2-prior-knowledge \
  http://localhost:8080/peeringdb.v1.NetworkService/ListNetworks \
  -d '{"page_size": 10, "status": "ok"}'

Streaming RPCs

All entity types support server-streaming for bulk data retrieval, eliminating manual pagination. Streams accept the same filters as List RPCs.

# Stream all networks
buf curl --protocol grpc --http2-prior-knowledge \
  http://localhost:8080/peeringdb.v1.NetworkService/StreamNetworks \
  -d '{}'

# Stream with filter
buf curl --protocol grpc --http2-prior-knowledge \
  http://localhost:8080/peeringdb.v1.NetworkService/StreamNetworks \
  -d '{"asn": 15169}'

The grpc-total-count response header contains the approximate total matching records. Streams have a server-side timeout (default 60s, configurable via PDBPLUS_STREAM_TIMEOUT) and can be cancelled by the client at any time.

Content Types

PeeringDB Compat API

The /api/ endpoint is a drop-in replacement for the PeeringDB REST API:

# List networks
curl https://peeringdb-plus.fly.dev/api/net

# Get a specific network
curl https://peeringdb-plus.fly.dev/api/net/42

# Search with query parameters
curl 'https://peeringdb-plus.fly.dev/api/net?q=cloudflare&limit=5'

Supports depth, limit, skip, fields, since, and q query parameters.

Development

go build ./...                    # Build all packages
go test -race ./...               # Run tests with race detector
go generate ./...                 # Full codegen pipeline (ent, templ, proto)
go vet ./...                      # Vet
golangci-lint run                 # Lint
govulncheck ./...                 # Vulnerability check

Technology

• Go 1.26+ with entgo ORM
• SQLite via modernc.org/sqlite (pure Go, no CGO)
• LiteFS for edge replication on Fly.io
• ConnectRPC for gRPC/Connect/gRPC-Web on standard net/http
• OpenTelemetry for tracing, metrics, and structured logging
• templ + htmx + Tailwind CSS for the web UI
• gqlgen via entgql for GraphQL
• entrest for OpenAPI-compliant REST
• Chainguard base images for minimal container footprint

License

BSD 3-Clause. See LICENSE.