Federation

The SQL that connects two NYXDB instances — application access and grants on the host, credentials and sources on the consumer.

Federation statements configure one instance (the consumer) to read tables of another (the host). They run on a WebSocket session and take literal values. For the model, see Federation.

The examples use the access analytics_reader on the host and the source ledger on the consumer, over the host's balances and transfers tables.

Host: application access

CREATE APPLICATION ACCESS analytics_reader

Access names are case-insensitive and unique. Options bound the sessions an access opens:

CREATE APPLICATION ACCESS analytics_reader WITH (max_session_ms = 3600000)

Option	Meaning	Range
`max_session_ms`	Lifetime of each session opened with the access. Default 24 hours.	101 ms to 30 days
`max_live_sessions`	Sessions that may be open at once. Default 65,536.	1 to 1,048,576

Host: mint the secret

ALTER APPLICATION ACCESS analytics_reader MINT SECRET

The result row carries the secret, a token that starts with nyxa1_. It is returned once; the host keeps only its digest. Minting again rotates the secret, and sessions opened with the previous token end.

ALTER APPLICATION ACCESS analytics_reader ENABLE | DISABLE switches the access on or off.

ALTER APPLICATION ACCESS analytics_reader DISABLE

Host: grants

A table grant names the actions (read, subscribe) and a row policy: one column compared with a literal, or one column with an IN list of literals. The consumer sees exactly the rows the policy admits.

GRANT read, subscribe
  ON TABLE balances
  WHERE chain_id = 1
  TO APPLICATION ACCESS analytics_reader

GRANT read, subscribe
  ON TABLE transfers
  WHERE chain_id IN (1, 10, 137)
  TO APPLICATION ACCESS analytics_reader

Views are granted with invoke_view:

GRANT invoke_view ON VIEW token_volume TO APPLICATION ACCESS analytics_reader

REVOKE read, subscribe
  ON TABLE transfers
  FROM APPLICATION ACCESS analytics_reader

Host: drop the access

DROP APPLICATION ACCESS analytics_reader

Consumer: install the credential

CREATE
  CREDENTIAL 6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
  SECRET 'nyxa1_<token minted on the host>'

The credential is named by a UUID; the secret is the token from MINT SECRET. The statement stores the token in a private file in the federation credentials directory and never echoes it. Replace a credential with:

CREATE OR REPLACE
  CREDENTIAL 6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
  SECRET 'nyxa1_<token minted on the host>'

DROP CREDENTIAL <uuid> removes a credential.

Consumer: declare the source

CREATE SOURCE ledger
  KIND nyxdb_instance
  OPTIONS (
    endpoint 'wss://ledger.example.com/client',
    credential '6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f'
  )
  EXPOSING (balances AS ledger_balances, transfers AS ledger_transfers)

Clause	Meaning
`KIND nyxdb_instance`	The source is another NYXDB instance.
`endpoint`	The host's WebSocket endpoint (`/client`), matching `gateway.federation.allowed_endpoint_suffixes`.
`credential`	The UUID of a credential installed with `CREATE CREDENTIAL`.
`certificate_sha256`	Optional: pins the host certificate (DER) by its SHA-256, 64 hex digits.
`per_user_subjects`	Optional `true` or `false`: when true, every local principal gets its own host subject. Default `false`.
`EXPOSING (host_table AS local_name [MODE forward], …)`	1 to 64 host tables and their local names.

Each local name becomes an external relation, read with ordinary SELECT and STREAM SELECT:

SELECT token, SUM(amount) AS total
FROM ledger_balances
WHERE chain_id = 1
GROUP BY token

STREAM SELECT token, SUM(amount) AS volume
FROM ledger_transfers
WHERE chain_id = 1
GROUP BY token

External relations are read-only: writes go to the host.

Consumer: change the exposed set

ALTER SOURCE ledger DETACH ledger_transfers

Detaching ends the relation's open streams and releases the name; the other relations keep serving on the same host session.

ALTER SOURCE ledger EXPOSE (transfers AS ledger_transfers)

Consumer: pause, resume, drop

ALTER SOURCE ledger PAUSE

ALTER SOURCE ledger RESUME

DROP SOURCE ledger

Source names are case-insensitive.

Catalog statements

SHOW SOURCE CATALOG FOR ledger

SHOW SOURCE CATALOG AT 'wss://ledger.example.com/client'
  CREDENTIAL '6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f'

SHOW SOURCE CATALOG FOR lists the host tables a declared source may read, with their granted actions and column definitions. The AT … CREDENTIAL … form probes an endpoint before any source exists. On the host, SHOW APPLICATION CATALOG lists what the calling application access is granted.

On this page