Database Reference

Status: Current

Last reviewed: 2026-05-16

This page reflects nexus-backend/migrations/001_initial_schema.sql through 033_node_config_updated_at.sql.

Core Tables

nodes

Node inventory and agent connectivity.

The metadata JSON can include node_port_runtime_listeners and node_port_runtime_reported_at, written from agent heartbeat data. These fields back GET /api/nodes/ports/runtime and reflect the listener table the agent actually applied.

Important columns:

• id
• name
• public_ip
• public_ipv6
• status
• last_heartbeat
• metadata
• iso_3166_code
• control_psk_verifier
• control_psk_fingerprint
• control_psk_rotated_at
• manual_addresses
• detected_addresses
• multiplex
• multiplex_port
• secret_hash
• created_at
• updated_at
• config_updated_at

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

control_psk_verifier, control_psk_fingerprint, and control_psk_rotated_at are the current secure-control authentication fields. The plaintext PSK is returned once by API flows and is not stored.

config_updated_at is the node-scoped runtime config version input. It is bumped by node configuration edits that change the agent's desired runtime snapshot. Heartbeat data, runtime listener reports, and other operational metadata continue to update updated_at without forcing a config rollout.

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. Target stages now persist upstream_id when selected in the console, while the saved endpoint string remains as a legacy fallback for older data.

upstream_clusters

Current upstream endpoint registry.

Important columns:

• id
• name
• endpoint
• server_names
• health_check_interval_ms
• enabled

Historical note: endpoints[] and upstream-local lb_strategy were simplified by migration 011. server_names are normalized on write: trimmed, lowercased, and deduplicated. health_check_interval_ms defaults to 0, which means off. health_check_path was removed by migration 030.

enc_keys

Reusable X25519 key material.

Important columns:

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

Current normalized key type:

• x25519: reusable X25519 key pair.

udp_noise is a legacy alias normalized to x25519 by the unified credential API and migrated by migration 024. UDP Noise and REALITY both reference these X25519 keys.

reality_profiles

REALITY route/profile configuration, separated from X25519 key material.

Important columns:

• id
• name
• x25519_key_id
• target_host
• target_port
• server_names
• short_ids
• metadata
• created_at
• updated_at

x25519_key_id references enc_keys(id). A REALITY profile can be used by TCP/QUIC REALITY L4 chains and by L3 QUIC REALITY DATAGRAM tunnels.

node_port_policies

Per-node listener priority policy for Port Management. This table remains a compatibility store for API-managed policy. The current frontend Port Management page does not expose a policy save icon and uses agent runtime heartbeat state for preview.

Important columns:

• id
• node_id
• transport
• listen_addr
• listen_port
• priority_order
• enabled
• created_at
• updated_at

node_id references nodes(id) with cascade delete. transport is tcp or udp; QUIC shares the UDP listener namespace. priority_order is a JSONB array of protocol labels such as ["reality", "tls", "noise", "raw"]. The policy table is keyed by node_id + transport + listen_addr + listen_port.

The table enforces one policy per listener namespace:

UNIQUE (node_id, transport, listen_addr, listen_port)

Legacy L3 Product Tables

The old l3_networks, l3_endpoints, l3_routes, l3_key_material, and l3_key_epochs product tables were removed by migration 064. SD-WAN underlay profiles now own tunnel transport sessions. Generic TUN I/O, userspace WireGuard, QUIC DATAGRAM, offload, GSO, and GRO code remains in the agent as a shared dataplane foundation.

• updated_at

Supported directions:

• advertise
• install
• allowed_source

updated_at was added by migration 032 so L3 route edits participate in the runtime config snapshot version used for hot reload decisions.

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. Current TLS certificate UI/API access is through the unified /api/credentials route with key_type = tls_cert.

Important columns:

• id
• domain
• cert_pem
• key_pem_encrypted
• issuer
• expires_at
• auto_renew
• created_at
• updated_at

app_settings

Backend-owned key/value settings.

Important columns:

• key
• value
• updated_at

Current default key:

• node_offline_timeout_seconds

Current Gaps

User disable/delete and expanded audit revert tables are not implemented in the current schema/API surface. See User Guide for console-facing limitations.