Database Reference

Status: Current

Last reviewed: 2026-05-10

This page reflects nexus-backend/migrations/001_initial_schema.sql through 014_unified_enc_credentials.sql.

Core Tables

nodes

Node inventory and agent connectivity.

Important columns:

• id
• name
• public_ip
• status
• last_heartbeat
• metadata
• iso_3166_code
• secret_hash
• connect_address
• multiplex
• multiplex_port

Historical note: WireGuard-specific columns were removed by migration 008. Region/datacenter/latitude/longitude were removed or replaced by migration 009.

node_links

Measured topology edges between nodes.

Important columns:

• from_node_id
• to_node_id
• latency_ms
• packet_loss
• bandwidth_mbps
• jitter_ms
• updated_at

routes

Legacy/unified route table. It still exists, but L4 chains are the primary gateway workflow.

Important columns include:

• name
• protocol
• domain
• port
• enabled
• priority
• l4_protocol
• l4_listen_addr
• l4_listen_port
• l4_tls
• l4_tls_cert_domain
• l7_protocol
• l7_host_match
• l7_path_match
• upstream_cluster_name
• lb_strategy
• rate_limit_rps
• timeout_ms
• retry_count
• server_names

Historical note: route_rules was merged into routes and later dropped by migration 010.

route_hops

Ordered hop metadata for legacy routes.

Important columns:

• route_id
• node_id
• hop_order
• action
• config

tunnel_chains

Current L4 chain storage.

Important columns:

• id
• name
• client_protocol
• enabled
• stages
• version
• created_at
• updated_at

stages is JSON and carries the per-hop chain model used by backend deployment.

upstream_clusters

Current upstream endpoint registry.

Important columns:

• id
• name
• endpoint
• health_check_path
• health_check_interval_ms
• enabled

Historical note: endpoints[] and upstream-local lb_strategy were simplified by migration 011.

enc_keys

Unified encryption credentials.

Important columns:

• id
• name
• public_key
• private_key
• key_type
• metadata
• created_at

Supported key types:

• udp_noise: X25519 key pair for UDP Noise / legacy ENC.
• tls_cert: TLS certificate/key PEM stored in public/private fields.
• reality: X25519 REALITY key material plus metadata.

auth_users

RBAC user accounts.

Important columns:

• username
• password_hash
• role
• totp_secret
• disabled
• last_login_at

audit_logs

Immutable audit trail.

Important columns:

• user_id
• action
• resource_type
• resource_id
• old_state
• new_state
• diff
• ip_address
• user_agent
• created_at

certificates

Certificate storage was created by the initial schema and is used by TLS APIs.

Current Gaps

The L3PTP roadmap requires future tables for L3 networks, endpoints, and routes. Those tables do not exist yet. See L3PTP REALITY.