Federation

Federation lets one instance, the consumer, read tables that live on another instance, the host, without copying them. The consumer sees each host table as a read-only external relation and forwards every read of it to the host. Reads are forwarded live, and a source can also mirror a host table locally.

consumer

• credential (the minted token)
• source → external relations
• read-only, forwarded

wss://

host

• application access
• minted secret
• table grants with a row predicate

On the host: application access

• An application access names one remote instance allowed to connect.
• ALTER APPLICATION ACCESS … MINT SECRET returns its secret, a token starting with nyxa1_, exactly once. The host stores only a digest of it.
• Minting again rotates the secret: sessions opened with the old secret end.
• DISABLE and DROP end the access's sessions; on the consumer the source then reports unavailable until the access is enabled or re-created.
• What the access may read is granted per table, and every table grant carries a row predicate (WHERE col = literal or WHERE col IN (…)). The actions are read and subscribe.
• max_session_ms bounds each session's lifetime (default 24 hours, at most 30 days), and max_live_sessions bounds concurrent sessions.

On the consumer: credential and source

• CREATE CREDENTIAL <uuid> SECRET '…' stores the minted token as a file with mode 0600 under the node's federation credentials directory (gateway.federation.credentials_directory). The secret is never echoed and is redacted from query history.
• CREATE SOURCE … KIND nyxdb_instance connects to the host endpoint with that credential and registers the exposed host tables as external relations under local names. The host schema is probed when the source is declared and checked again on reconnect.
• External relation names share one namespace with tables, views and transformations, so each name is unique.
• ALTER SOURCE pauses, resumes, detaches one relation or exposes more; DROP SOURCE removes the source and its relations.

Reads and streams

• A SELECT on an external relation is authorized locally and forwarded whole to the host, with only the relation name rewritten.
• External relations are read-only: writes go to the host. They join with local tables and read AS OF COMMIT like local relations.
• A STREAM SELECT on an external relation becomes one subscription on the host. Local subscribers of the same statement share it.
• A forwarded stream does not resume: after a disconnect, open a new STREAM SELECT.
• When the host is unreachable, reads fail with unavailable and a reason naming the source, while the consumer reconnects with backoff. Recovery is automatic.

Network rules

• The endpoint host must match a suffix in gateway.federation.allowed_endpoint_suffixes; an empty list turns federation off.
• wss:// is required for any endpoint other than loopback.
• Federation statements run on WebSocket sessions, and federated reads run over both HTTP and WebSocket.

Permissions

Source statements need relation_ddl or source_manage. Application-access and credential statements need credential_manage or source_manage, and application-access grants need data_grant_manage or source_manage. See Governance.

Observe

The statements are listed with examples in SQL: federation.