# 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](/docs/concepts/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

```sql
CREATE APPLICATION ACCESS analytics_reader
```

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

```sql
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

```sql
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.

```sql
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.

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

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

Views are granted with `invoke_view`:

```sql
GRANT invoke_view ON VIEW token_volume TO APPLICATION ACCESS analytics_reader
```

```sql
REVOKE read, subscribe
  ON TABLE transfers
  FROM APPLICATION ACCESS analytics_reader
```

## Host: drop the access

```sql
DROP APPLICATION ACCESS analytics_reader
```

## Consumer: install the credential

```sql
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:

```sql
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

```sql
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`:

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

```sql
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

```sql
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.

```sql
ALTER SOURCE ledger EXPOSE (transfers AS ledger_transfers)
```

## Consumer: pause, resume, drop

```sql
ALTER SOURCE ledger PAUSE
```

```sql
ALTER SOURCE ledger RESUME
```

```sql
DROP SOURCE ledger
```

Source names are case-insensitive.

## Catalog statements

```sql
SHOW SOURCE CATALOG FOR ledger
```

```sql
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.

---

Source: https://nyxdb.io/docs/sql/federation/