Supabase Realtime

https://github.com/supabase/realtime
Admin
Supabase Realtime enables sending ephemeral messages, tracking shared state, and listening to...
Tokens:275,420
Snippets:1,788
Trust Score:10
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### First-time server setup with mise

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

First-time setup for the Realtime server. Run these commands in order: install Elixir and asset dependencies, start the realtime database and the realtime-dev tenant, then start the server. Data survives restarts via `mise run db-stop` and `db-start`; only `db-rm` discards it.

```bash
mix setup           # Elixir and asset deps
mise run db-start   # realtime database on 5432, migrations, and the realtime-dev tenant with its database on 5433
mise run dev        # server on http://localhost:4000, default tenant at ws://realtime-dev.localhost:4000/socket
```

--------------------------------

### start_link/1

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

OTP GenServer entry point, started under the Realtime.Tenants.Connect.Supervisor.

```APIDOC
## start_link/1

### Description
OTP GenServer entry point, started under the `Realtime.Tenants.Connect.Supervisor` (`CONNECT_PARTITION_SLOTS` partitions). `opts` requires a `:tenant_id`.

### Method
Function

### Endpoint
`Realtime.Tenants.Connect.start_link/1`

### Parameters
#### Path Parameters
- **opts** (`keyword()`) - Required - Options, must include `:tenant_id`.

### Returns
- `{:ok, pid()}` - The GenServer pid.

```

--------------------------------

### Manage feature flags via Realtime.Api

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/api_feature_flag.md

Usage examples for creating/updating, reading, and deleting feature flags through `Realtime.Api` functions. The create/update example sets `name`, `enabled`, `rollout_percentage`, and `bucket_key`.

```elixir
# Create or update
{:ok, flag} = Realtime.Api.upsert_feature_flag(%{
  name: "use_muster_channel_join",
  enabled: true,
  rollout_percentage: 50,
  bucket_key: "muster_join_v2"
})

# Read
flag = Realtime.Api.get_feature_flag("use_muster_channel_join")

# Delete
{:ok, _} = Realtime.Api.delete_feature_flag(flag)
```

--------------------------------

### Build and run binary with Bun

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Build the binary with Bun and then run it. Requires Bun installed.

```bash
bun install
bun run build
./realtime-check --project <ref> --publishable-key <key> --secret-key <key> --db-password <pw>
```

--------------------------------

### lookup_or_start_connection/2

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

Returns the tenant's managed DB connection, starting it if necessary. This is the function channels and broadcast handlers call to get a tenant DB connection.

```APIDOC
## lookup_or_start_connection/2

### Description
Returns `{:ok, db_conn_pid}` for the tenant's managed DB connection, or one of the error tuples below. This is **the** function channels and broadcast handlers call to get a tenant DB connection.

### Method
Function

### Endpoint
`Realtime.Tenants.Connect.lookup_or_start_connection/2`

### Parameters
#### Path Parameters
- **tenant_id** (`binary()`) - Required - Tenant `external_id`

#### Query Parameters
- **opts** (`keyword()`) - Optional - Default: `[]` - QoS meta (e.g. `tenant_id:`, for RPC)

### Returns
- `{:ok, pid()}` - The tenant's managed DB connection pid.
- `{:error, :tenant_not_found}` - Tenant not found.
- `{:error, :tenant_database_connection_initializing}` or `{:error, :initializing}` - Connection initializing.
- `{:error, :tenant_database_unavailable}` - Database unavailable.
- `{:error, :tenant_db_too_many_connections}` - Too many connections.
- `{:error, :connect_rate_limit_reached}` - Rate limit reached.
- `{:error, :rpc_error, reason}` - When proxying to the owning node.

```

--------------------------------

### Run realtime-check against local project

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Run the check against a local Supabase project. Requires a supabase/config.toml so supabase start works out of the box.

```bash
supabase start
./realtime-check --env local --publishable-key <anon-key> --secret-key <service-role-key>
```

--------------------------------

### Join payload example (JSON)

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/payloads.md

Example JSON payload for a join request, including config for broadcast, presence, postgres_changes, postgres_changes_options, private, and access/user tokens.

```json
{
  "config": {
    "broadcast": {
      "ack": true,
      "self": true,
      "replication_ready": false,
      "replay": {"limit": 25, "since": 0}
    },
    "presence": {"enabled": true, "key": "user-123"},
    "postgres_changes": [
      {"event": "INSERT", "schema": "public", "table": "messages", "filter": "status=eq.online"}
    ],
    "postgres_changes_options": {"wait": true, "timeout": 15000},
    "private": false
  },
  "access_token": "<anon JWT>",
  "user_token": "<user JWT>"
}

```

--------------------------------

### Realtime.Tenants.BatchBroadcast.broadcast/3

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/batch_broadcast.md

Documentation for the Realtime.Tenants.BatchBroadcast.broadcast/3 function, including usage examples and error handling.

```APIDOC
## Realtime.Tenants.BatchBroadcast.broadcast/3

### Description
Broadcasts a batch of messages to a tenant. Accepts either a Plug.Conn with pre-assigned claims or an explicit auth map, along with the tenant and a messages map.

### Method
Function call

### Endpoint
`Realtime.Tenants.BatchBroadcast.broadcast(conn_or_auth_params, tenant, messages)`

### Parameters
#### Arguments
- **conn_or_auth_params** (Plug.Conn | map) - Required - Either a Plug.Conn with claims already assigned by `RealtimeWeb.AuthTenant`, or a map with `:tenant_id`, `:headers`, `:claims`, `:role`, and `:sub` keys.
- **tenant** (Tenant struct) - Required - The tenant to broadcast to.
- **messages** (map) - Required - A map with a `"messages"` key containing a list of message maps. Each message map can have `"topic"`, `"event"`, `"payload"`, `"id"`, and `"private"` keys.

### Request Example
```elixir
messages = %{
  "messages" => [
    %{"topic" => "room:123", "event" => "message", "payload" => %{"text" => "hi"}, "id" => "abc-1"},
    %{"topic" => "dm:42", "event" => "message", "payload" => %{"text" => "secret"}, "private" => true}
  ]
}

auth_params = %{
  tenant_id: tenant.external_id,
  headers: [{"authorization", "Bearer ..."}],
  claims: claims,
  role: claims["role"],
  sub: claims["sub"]
}

:ok = Realtime.Tenants.BatchBroadcast.broadcast(auth_params, tenant, messages)
```

### Response
#### Success Response
- `:ok` - Broadcast succeeded.

#### Error Responses
- `{:error, %Ecto.Changeset{}}` - Validation error.
- `{:error, :forbidden, "Tenant is suspended"}` - Tenant is suspended.
- `{:error, :too_many_requests, msg}` - Rate limit exceeded.
- `{:error, :tenant_not_found}` - Tenant not found.
- `{:error, changeset}` - Other changeset error.

### Notes
- For public channels, every message is delivered even if a later message fails validation at the point of send — validation happens batch-wide before any send.
- Private messages with denied policies are silently dropped (no per-message error), matching the fire-and-forget broadcast semantics.
- Related: `RealtimeWeb.BroadcastController` (HTTP layer), `RealtimeWeb.TenantBroadcaster` (fan-out), `Realtime.Tenants.SingleBroadcast` (single-message variant).
```

--------------------------------

### Start Forum.Census in supervision tree

Source: https://github.com/supabase/realtime/blob/main/forum/README.md

Starts Forum.Census under a supervision tree with 8 partitions and a 5-second broadcast interval. The group name is :users.

```elixir
children = [
  {Forum.Census, [:users, partitions: 8, broadcast_interval_in_ms: 5_000]}
]
```

--------------------------------

### Export tenant schema with env vars

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/mix_tasks.md

Example of setting database connection environment variables and running the export task. Output shows the success message.

```bash
export DB_HOST=127.0.0.1 DB_PORT=5433 DB_NAME=postgres \
       DB_USER=supabase_admin DB_PASSWORD=postgres
mix realtime.export_tenant_schema
# [export_tenant_schema] wrote priv/repo/tenant_schema
```

--------------------------------

### Realtime.Tenants.SingleBroadcast.broadcast/6

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/single_broadcast.md

Documentation for the Realtime.Tenants.SingleBroadcast.broadcast/6 function, including parameters, usage examples, and error handling.

```APIDOC
## Realtime.Tenants.SingleBroadcast.broadcast/6

### Description
Broadcasts a message to a room in a tenant. Supports both public and private broadcasts, with optional persistence. Returns `:ok` on success or an error tuple.

### Method
Function call

### Endpoint
`Realtime.Tenants.SingleBroadcast.broadcast(auth_params, tenant, topic, event, payload, format, opts \\ [])`

### Parameters
- **auth_params** (map or nil) - Required - Authorization parameters built with `Authorization.build_authorization_params/1`. Use `nil` for public broadcast.
- **tenant** (struct) - Required - The tenant struct.
- **topic** (string) - Required - The room or channel topic, e.g., `"room:123"`.
- **event** (string) - Required - The event name, e.g., `"message"`.
- **payload** (any) - Required - The message payload. Can be a map for JSON or a binary for binary format.
- **format** (atom) - Required - The payload format: `:json` or `:binary`.
- **opts** (keyword list) - Optional - Options: `:private` (boolean) - if true, requires auth_params; `:persist` (boolean) - if true, persists the message.

### Request Example
```elixir
auth_params = Authorization.build_authorization_params(%{
  tenant_id: tenant.external_id,
  headers: conn.req_headers,
  claims: claims,
  role: claims["role"],
  sub: claims["sub"]
})

# Public JSON broadcast
:ok = Realtime.Tenants.SingleBroadcast.broadcast(
  nil,
  tenant,
  "room:123",
  "message",
  %{"text" => "hello world"},
  :json
)

# Private binary broadcast with persistence
case Realtime.Tenants.SingleBroadcast.broadcast(
       auth_params,
       tenant,
       "room:123",
       "message",
       <<1, 2, 3>>,
       :binary,
       private: true,
       persist: true
     ) do
  :ok -> :ok
  {:error, :forbidden, msg} -> Logger.error("denied: #{msg}")
  {:error, :too_many_requests, msg} -> Logger.error("rate limited: #{msg}")
  {:error, %Ecto.Changeset{} = cs} -> Logger.error(inspect(cs.errors))
end
```

### Response
#### Success Response
- `:ok` - Broadcast succeeded.

#### Error Responses
- `{:error, :forbidden, msg}` - Access denied.
- `{:error, :too_many_requests, msg}` - Rate limited.
- `{:error, %Ecto.Changeset{}}` - Validation error.

### HTTP Layer Mapping
When called via the HTTP controller (`RealtimeWeb.BroadcastSingleController`), error tuples are mapped to HTTP status codes:
- `:forbidden` → 403
- `:unprocessable_entity` → 422
- `:too_many_requests` → 429
- `:internal_server_error` → 500
- Changesets → 422
- Success → 202 with empty body
- Invalid content type → 415 (produced by `RealtimeWeb.Plugs.ValidateBroadcastContentType`)
```

--------------------------------

### Run check with Bun without building

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Run the check without building, using Bun. Requires Bun installed.

```bash
bun install
bun run check -- --project <ref> --publishable-key <key> --secret-key <key> --db-password <pw>
```

--------------------------------

### Realtime.Tenants.Connect usage examples

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

Shows the main public API of Realtime.Tenants.Connect: lookup_or_start_connection/1 for the channel join path, replication_status/1 for health reporting, and shutdown/1 for tenant teardown. The join path returns {:error, :tenant_database_unavailable} when the database is unreachable, and replication_status returns {:error, :not_connected} when replication is not active.

```elixir
# Channel join path — get the managed connection
case Realtime.Tenants.Connect.lookup_or_start_connection(tenant_id) do
  {:ok, db_conn} ->
    {:ok, policies} = Realtime.Tenants.Authorization.get_read_authorizations(policies, db_conn, ctx)

  {:error, :tenant_database_unavailable} ->
    # reject the join with "Realtime was unable to connect to the project database"
end

# Health reporting
case Realtime.Tenants.Connect.replication_status(tenant_id) do
  {:ok, _pid} -> %{replication_connected: true}
  {:error, :not_connected} -> %{replication_connected: false}
end

# Tenant teardown (used by the delete-tenant controller)
:ok = Realtime.Tenants.Connect.shutdown("tenant-1")
```

--------------------------------

### Usage examples - Enforce limits and report metrics

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/users_counter.md

Shows how to enforce max_concurrent_users on channel join, add a process after successful join, and report cluster-wide presence for ops dashboards.

```elixir
# Enforce max_concurrent_users on channel join (see RealtimeChannel.limit_max_users/2)
unless Realtime.UsersCounter.already_counted?(transport_pid, tenant.external_id) do
  if Realtime.UsersCounter.tenant_users(tenant.external_id) >= tenant.max_concurrent_users do
    {:error, :too_many_connections}
  end
end

# After a successful join
:ok = Realtime.UsersCounter.add(channel_pid, tenant.external_id)

# Cluster-wide presence for ops dashboards
for {tenant_id, count} <- Realtime.UsersCounter.tenant_counts() do
  Metrics.gauge("connected_users", count, %{tenant: tenant_id})
end
```

--------------------------------

### Run realtime-check with --test flag

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Shows how to run the realtime-check CLI with the --test flag to select test categories. The --env local flag is used, and --publishable-key and --secret-key are required. The three examples run connection and broadcast tests, all load tests, and all functional (non-load) tests respectively.

```bash
# Run only connection and broadcast tests
./realtime-check --env local --publishable-key <key> --secret-key <key> --test connection,broadcast

# Run all load tests
./realtime-check --env local --publishable-key <key> --secret-key <key> --test load

# Run all functional (non-load) tests
./realtime-check --env local --publishable-key <key> --secret-key <key> --test functional
```

--------------------------------

### Parse and compose wire filters with Realtime.Filter

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/filter.md

Shows parsing wire filters with Realtime.Filter.parse_all/1, composing a negated filter with compose_all/1, and handling parse failures with a case statement. The first example returns a list of condition maps with column, operator, value, and negated fields. The second example demonstrates negating a condition by setting negated to true, producing "archived=not.is.false". The third example shows a typical error-handling pattern where a raw string is used on parse failure.

```elixir
# Parse a wire filter
{:ok, conditions} = Realtime.Filter.parse_all("status=eq.online,age=gte.18,name=in.(alice,bob)")
# => [%{column: "status", operator: "eq", value: "online", negated: false},
#     %{column: "age", operator: "gte", value: "18", negated: false},
#     %{column: "name", operator: "in", value: "(alice,bob)", negated: false}]

# Build a filter for a UI picker
{:ok, conds} = Realtime.Filter.parse_all("archived=is.false")
conditions = [%{conds | negated: true}]
Realtime.Filter.compose_all(conditions)
# => "archived=not.is.false"

# Handle parse failures
case Realtime.Filter.parse_all(user_filter) do
  {:ok, conditions} -> do_query(conditions)
  :error -> use_raw_string(user_filter)
end
```

--------------------------------

### Usage examples for feature flags

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/feature_flags.md

Shows typical usage of the feature flag API: global check, per-tenant check with rollout, and managing overrides with set_tenant_flag/3 and clear_tenant_flag/2.

```elixir
# Global check (no tenant context)
if Realtime.FeatureFlags.enabled?("use_muster_channel_join") do
  # flag is globally enabled
end

# Per-tenant check with rollout
if Realtime.FeatureFlags.enabled?("broadcast_persistence", "tenant-1") do
  # tenant-1 either overrode the flag or is inside the rollout cohort
end

# Manage overrides
{:ok, _tenant} = Realtime.FeatureFlags.set_tenant_flag("broadcast_persistence", "tenant-1", true)
{:ok, _tenant} = Realtime.FeatureFlags.clear_tenant_flag("broadcast_persistence", "tenant-1")
```

--------------------------------

### GET /metrics

Source: https://github.com/supabase/realtime/blob/main/OBSERVABILITY_METRICS.md

Returns high-priority metrics including BEAM/VM, OS, Phoenix, distributed infrastructure, and global aggregated tenant totals (no `tenant` label). Recommended scrape interval is 30 seconds.

```APIDOC
## GET /metrics

### Description
Returns high-priority metrics including BEAM/VM, OS, Phoenix, distributed infrastructure, and global aggregated tenant totals (no `tenant` label). Recommended scrape interval is 30 seconds.

### Method
GET

### Endpoint
`/metrics`

### Authentication
Requires a `Bearer` JWT token in the `Authorization` header signed with `METRICS_JWT_SECRET`.

### Response
#### Success Response (200)
Metrics in Prometheus format.

#### Response Example
```
# HELP beam_utilization BEAM utilization
# TYPE beam_utilization gauge
beam_utilization 0.5
```
```

--------------------------------

### Run WALRUS regression suite

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

Run the WALRUS regression suite against the tenant realtime schema. The first command uses the database dump (what most tenants get), the second replays migrations (for orioledb tenants), and the third targets a specific major version.

```bash
mise run walrus               # from priv/repo/tenant_db_dump_<major>.sql, what most tenants get
mise run walrus --migrations  # by replaying the migrations, what an orioledb tenant gets
mise run walrus --major 15    # a major other than the newest in TENANT_DUMP_IMAGES
```

--------------------------------

### Forum.Muster Supervision

Source: https://github.com/supabase/realtime/blob/main/forum/README.md

How to start Forum.Muster under supervision with a scope name and configuration options.

```APIDOC
## Forum.Muster (Supervision)

### Description
Start Muster under supervision with a scope name. Use a different scope from any Census on the same node.

### Method
Supervision child specification

### Parameters
- **scope** (atom) - Required - The scope name.
- **partitions** (integer) - Required - Number of partitions.
- **vacancy_cooldown_ms** (integer) - Required - Cooldown period for vacancy.
- **vacant_flush_interval_ms** (integer) - Required - Interval for flushing vacant batches.

### Example
```elixir
children = [
  {Forum.Muster,
   [:topics, partitions: 8, vacancy_cooldown_ms: 30_000, vacant_flush_interval_ms: 5_000]}
]
```
```

--------------------------------

### GET /tenant-metrics

Source: https://github.com/supabase/realtime/blob/main/OBSERVABILITY_METRICS.md

Returns low-priority per-tenant labeled metrics (connection counts, channel events, replication, authorization). Recommended scrape interval is 60 seconds.

```APIDOC
## GET /tenant-metrics

### Description
Returns low-priority per-tenant labeled metrics (connection counts, channel events, replication, authorization). Recommended scrape interval is 60 seconds.

### Method
GET

### Endpoint
`/tenant-metrics`

### Authentication
Requires a `Bearer` JWT token in the `Authorization` header signed with `METRICS_JWT_SECRET`.

### Response
#### Success Response (200)
Metrics in Prometheus format with `tenant` labels.

#### Response Example
```
# HELP realtime_connection_count Connection count
# TYPE realtime_connection_count gauge
realtime_connection_count{tenant="tenant1"} 10
```
```

--------------------------------

### Run local check with tracing

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Run the check with tracing enabled. Starts Jaeger via docker compose and sends OTLP traces to http://localhost:4318.

```bash
supabase start
docker compose up -d  # starts Jaeger at http://localhost:16686
./realtime-check --env local --publishable-key <anon-key> --secret-key <service-role-key> --otel http://localhost:4318
```

--------------------------------

### Start Forum.Muster under supervision with scope

Source: https://github.com/supabase/realtime/blob/main/forum/README.md

Supervision child specification for Forum.Muster with a distinct scope name (`:topics`) and options. Use a different scope from any Census on the same node.

```elixir
children = [
  {Forum.Muster,
   [:topics, partitions: 8, vacancy_cooldown_ms: 30_000, vacant_flush_interval_ms: 5_000]}
]
```

--------------------------------

### Test rebalance convergence with Snabbkaffex check_trace

Source: https://github.com/supabase/realtime/blob/main/forum/README.md

Write a trace-based test with `use Snabbkaffex` (no options) to get the full API. The collector is a global singleton, so the test module must be `async: false`. `check_trace/2` runs the action, collects the trace, and passes it to the check function, which must use ordinary `assert` because it passes unless it raises. Trace-query helpers like `of_kind` take the trace as their first argument.

```elixir
use ExUnit.Case, async: false
use Snabbkaffex

test "rebalance converges" do
  check_trace(
    fn ->
      add_node(:node2)
      block_until(%{"$kind" => :muster_rebalance_done}, 1000)
    end,
    fn trace ->
      assert [%{members: members}] = of_kind(trace, :muster_rebalance_done)
      assert :node2 in members
    end
  )
end
```

--------------------------------

### Forward trace to remote node

Source: https://github.com/supabase/realtime/blob/main/forum/README.md

Forwards trace events from a remote node to the collector. Attach before remote work starts to avoid missing events; remote nodes need snabbkaffe on their code path but no collector of their own. Revert with unforward_trace/1 before a deliberate Node.disconnect/1 to prevent auto-reconnect.

```elixir
forward_trace(remote_node)
```

--------------------------------

### ready?/1

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

Returns whether the tenant's Connect process has finished provisioning.

```APIDOC
## ready?/1

### Description
Returns boolean — whether the tenant's `Connect` process has finished provisioning (`:ready?` call).

### Method
Function

### Endpoint
`Realtime.Tenants.Connect.ready?/1`

### Parameters
#### Path Parameters
- **tenant_id** (`binary()`) - Required - Tenant `external_id`

### Returns
- `boolean` - Whether the tenant's Connect process is ready.

```

--------------------------------

### GET /api/tenants

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Lists all tenants.

```APIDOC
## GET /api/tenants

### Description
Lists all tenants.

### Method
GET

### Endpoint
/api/tenants

### Authentication
- **Bearer token** - Required - Verified against `API_JWT_SECRET`/`API_JWT_SECRET_NEXT`.

### Response
#### Success Response (200)
- **data** (array) - List of `TenantResponseValue` objects.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### Open Realtime Inspector with mise run dev-inspector

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

Open the Realtime Inspector with host and token pre-filled for the current `TENANT`. Alternatively, fill in the connect line manually: Host `http://realtime-dev.localhost:4000`, Token from `mix realtime.gen_token`, and any Channel.

```bash
mise run dev-inspector   # opens the Inspector with host and token already filled in for TENANT
```

--------------------------------

### connect/2

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/postgres_cdc.md

Delegates to the driver's `handle_connect/1` callback to establish a connection for the given tenant.

```APIDOC
## connect/2

### Description
Delegates to the driver's `handle_connect/1` callback to establish a connection for the given tenant.

### Method
Function call

### Endpoint
`Realtime.PostgresCdc.connect(module, opts)`

### Parameters
- **module** (`module()`) - Required - Driver module (e.g. `Extensions.PostgresCdcRls`)
- **opts** (`term()`) - Required - `%{"region" => ..., "id" => tenant_id}` style args

### Returns
Driver-defined connection response or `nil`.

### Source
`lib/realtime/postgres_cdc.ex:19`
```

--------------------------------

### GET /api/ping

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Ping endpoint to check API availability.

```APIDOC
## GET /api/ping

### Description
Ping endpoint to check if the API is alive. Requires a valid tenant and is rate limited.

### Method
GET

### Endpoint
/api/ping

### Parameters
#### Auth
- **tenant_api** - Required - Tenant must exist (AssignTenant, else 401 with message "Tenant not found in database"), rate limited (429 when over max_events_per_second)

### Response
#### Success Response (200)
- **message** (string) - "Success"

#### Response Example
{
  "message": "Success"
}

### Headers
- **x-rate-rolling** - Rate limit rolling window
- **x-rate-limit** - Rate limit value
- **x-rate-limit-remaining** - Remaining rate limit
```

--------------------------------

### Manage tenant databases with TENANT env var

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

Add or remove a tenant database for isolation and code review. `TENANT` defaults to the checkout's directory name (e.g., `realtime.review` becomes `realtime-review`). Re-running `db-start` leaves existing tenant data and publication alone.

```bash
TENANT=review mise run db-start  # tenant named review, database on a port docker picks
TENANT=review mise run db-rm     # removes its database
```

--------------------------------

### GET /api/tenants/:tenant_id

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Retrieves a single tenant by ID.

```APIDOC
## GET /api/tenants/:tenant_id

### Description
Retrieves a single tenant by ID.

### Method
GET

### Endpoint
/api/tenants/:tenant_id

### Path Parameters
- **tenant_id** (string) - Required - The tenant identifier.

### Authentication
- **Bearer token** - Required - Verified against `API_JWT_SECRET`/`API_JWT_SECRET_NEXT`.

### Response
#### Success Response (200)
- **data** (object) - `TenantResponseValue` object.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### Realtime.Api.create_tenant/1

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/api.md

Creates a new tenant with the given parameters and runs its database migrations.

```APIDOC
## [POST] /tenants

### Description
Creates a new tenant with the specified configuration and runs its migrations.

### Method
POST

### Endpoint
/tenants

### Parameters
#### Request Body
- **external_id** (string) - Required - Unique identifier for the tenant.
- **name** (string) - Required - Display name of the tenant.
- **jwt_secret** (string) - Required - Secret key used for JWT signing.
- **extensions** (array) - Required - List of extension configurations.
  - **type** (string) - Required - Type of extension (e.g., "postgres_cdc_rls").
  - **settings** (object) - Required - Settings for the extension.
    - **db_host** (string) - Required - Database host.
    - **db_name** (string) - Required - Database name.
    - **db_port** (string) - Required - Database port.
    - **db_user** (string) - Required - Database user.
    - **db_password** (string) - Required - Database password.
    - **slot_name** (string) - Required - Replication slot name.
    - **publication** (string) - Required - Publication name.
  - **tenant_external_id** (string) - Required - External ID of the tenant.

### Request Example
{
  "external_id": "myproject",
  "name": "My Project",
  "jwt_secret": "super-secret-jwt-key",
  "extensions": [
    {
      "type": "postgres_cdc_rls",
      "settings": {
        "db_host": "db.internal",
        "db_name": "postgres",
        "db_port": "5432",
        "db_user": "postgres",
        "db_password": "password",
        "slot_name": "supabase_realtime_replication_slot",
        "publication": "supabase_realtime"
      },
      "tenant_external_id": "myproject"
    }
  ]
}

### Response
#### Success Response (200)
- **tenant** (object) - The created tenant object.

#### Response Example
{
  "tenant": {
    "external_id": "myproject",
    "name": "My Project",
    "jwt_secret": "super-secret-jwt-key",
    "extensions": [
      {
        "type": "postgres_cdc_rls",
        "settings": {
          "db_host": "db.internal",
          "db_name": "postgres",
          "db_port": "5432",
          "db_user": "postgres",
          "db_password": "password",
          "slot_name": "supabase_realtime_replication_slot",
          "publication": "supabase_realtime"
        },
        "tenant_external_id": "myproject"
      }
    ]
  }
}
```

--------------------------------

### GET /metrics

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Returns Prometheus metrics for the entire cluster.

```APIDOC
## GET /metrics

### Description
Returns Prometheus metrics in text exposition format, collected from every node in the cluster.

### Method
GET

### Endpoint
/metrics

### Authentication
- **Bearer token** - Required - JWT signed with `METRICS_JWT_SECRET`; tokens from `METRICS_TOKEN_BLOCKLIST` are rejected.

### Response
#### Success Response (200)
- **body** (string) - Prometheus exposition format, chunked.

#### Response Example
```
# HELP ...
# TYPE ...
```
```

--------------------------------

### Create table and add to supabase_realtime publication

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

Create a table and add it to the `supabase_realtime` publication so you can listen to Postgres changes. Use this after setting up a tenant.

```sql
create table test (
  id serial primary key
);

alter publication supabase_realtime add table test;
```

--------------------------------

### Create tenant and run migrations

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/api.md

Creates a tenant with a postgres_cdc_rls extension and runs its migrations. On success, migrations are executed; on failure, changeset errors are printed.

```elixir
tenant_params = %{
  "external_id" => "myproject",
  "name" => "My Project",
  "jwt_secret" => "super-secret-jwt-key",
  "extensions" => [
    %{
      "type" => "postgres_cdc_rls",
      "settings" => %{
        "db_host" => "db.internal",
        "db_name" => "postgres",
        "db_port" => "5432",
        "db_user" => "postgres",
        "db_password" => "password",
        "slot_name" => "supabase_realtime_replication_slot",
        "publication" => "supabase_realtime"
      },
      "tenant_external_id" => "myproject"
    }
  ]
}

case Realtime.Api.create_tenant(tenant_params) do
  {:ok, tenant} ->
    Realtime.Tenants.Migrations.run_migrations(tenant)

  {:error, changeset} ->
    IO.inspect(Ecto.Changeset.traverse_errors(changeset, &translate_error/1))
end
```

--------------------------------

### Join Payload

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/payloads.md

Example join payload and usage for the Realtime channel.

```APIDOC
## Join Payload

### Description
Example join payload for a Realtime channel, including broadcast, presence, postgres_changes, and authentication tokens.

### Example
```json
{
  "config": {
    "broadcast": {
      "ack": true,
      "self": true,
      "replication_ready": false,
      "replay": {"limit": 25, "since": 0}
    },
    "presence": {"enabled": true, "key": "user-123"},
    "postgres_changes": [
      {"event": "INSERT", "schema": "public", "table": "messages", "filter": "status=eq.online"}
    ],
    "postgres_changes_options": {"wait": true, "timeout": 15000},
    "private": false
  },
  "access_token": "<anon JWT>",
  "user_token": "<user JWT>"
}
```

### Usage Example
```elixir
{:ok, join} = RealtimeWeb.Channels.Payloads.Join.validate(payload)

case join do
  %{config: %Config{private: true}} ->
    # private channel: RLS authorization runs on join

  %{config: %Config{private: false}} ->
    # public channel
end

if RealtimeWeb.Channels.Payloads.Join.ack_broadcast?(join) do
  # the client wants a phx_reply ack after broadcasts
end
```
```

--------------------------------

### GET /api/tenants/:tenant_id/health

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Returns health information for a specific tenant.

```APIDOC
## GET /api/tenants/:tenant_id/health

### Description
Returns health information for a specific tenant.

### Method
GET

### Endpoint
/api/tenants/:tenant_id/health

### Path Parameters
- **tenant_id** (string) - Required - The tenant identifier.

### Authentication
- **Bearer token** - Required - Verified against `API_JWT_SECRET`/`API_JWT_SECRET_NEXT`.

### Response
#### Success Response (200)
- **data** (object) - Contains fields: `healthy`, `db_connected`, `replication_connected`, `connected_cluster`, `region`, `node`.

#### Response Example
```json
{
  "data": {
    "healthy": true,
    "db_connected": true,
    "replication_connected": true,
    "connected_cluster": "string",
    "region": "string",
    "node": "string"
  }
}
```
```

--------------------------------

### GET /metrics/:region

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Returns Prometheus metrics for a specific region.

```APIDOC
## GET /metrics/:region

### Description
Returns Prometheus metrics for a specific region.

### Method
GET

### Endpoint
/metrics/:region

### Path Parameters
- **region** (string) - Required - The region identifier.

### Authentication
- **Bearer token** - Required - JWT signed with `METRICS_JWT_SECRET`; tokens from `METRICS_TOKEN_BLOCKLIST` are rejected.

### Response
#### Success Response (200)
- **body** (string) - Prometheus exposition format, chunked.

#### Response Example
```
# HELP ...
# TYPE ...
```
```

--------------------------------

### get_status/1

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

Returns the connection pid for the tenant without starting a connection.

```APIDOC
## get_status/1

### Description
Returns `{:ok, pid()}` with the connection pid or an error. Unlike `lookup_or_start_connection`, it never starts a connection.

### Method
Function

### Endpoint
`Realtime.Tenants.Connect.get_status/1`

### Parameters
#### Path Parameters
- **tenant_id** (`binary()`) - Required - Tenant `external_id`

### Returns
- `{:ok, pid()}` - The connection pid.
- `{:error, :tenant_not_found}` - Tenant not found.
- `{:error, :tenant_database_connection_initializing}` - Connection initializing.

```

--------------------------------

### Build and run realtime-check with Nix

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Build with Nix and run the realtime-check binary. `bun run nix` calls `nix-build.sh`, which automatically updates the `outputHash` in `flake.nix` when `package.json` or `bun.lock` change.

```bash
bun run nix
./result/bin/realtime-check --project <ref> --publishable-key <key> --secret-key <key> --db-password <pw>
```

--------------------------------

### Enable Nix flakes in /etc/nix/nix.conf

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Add this line to /etc/nix/nix.conf to enable Nix flakes support, required for the Nix-based build and run workflow.

```text
experimental-features = nix-command flakes
```

--------------------------------

### Run WALRUS suite with mise

Source: https://github.com/supabase/realtime/blob/main/test/walrus/README.md

Run the WALRUS regression suite with mise. Use --migrations to replay tenant migrations, pass a test name to run one or more tests, and --major to select a Postgres major version. Without --major, the newest entry in TENANT_DUMP_IMAGES wins.

```bash
mise run walrus                     # whole suite, from the dump
mise run walrus --migrations        # whole suite, from the migrations
mise run walrus test_simple_insert  # one or more tests
mise run walrus --major 15          # a specific Postgres major
```

--------------------------------

### GET /healthcheck

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Health check endpoint that returns a plain text "ok" response.

```APIDOC
## GET /healthcheck

### Description
Returns a simple health check response to verify the service is running.

### Method
GET

### Endpoint
/healthcheck

### Response
#### Success Response (200)
- **body** (string) - The literal string "ok"

#### Response Example
```
ok
```
```

--------------------------------

### Exempt dependencies from cooldown

Source: https://github.com/supabase/realtime/blob/main/DEVELOPERS.md

Configure mix.exs to exempt specific repositories from the dependency cooldown, for example if you trust them especially.

```elixir
hex: [
  cooldown: "7d",
  cooldown_exclude_repos: ["repo"]
]
```

--------------------------------

### add/2

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/users_counter.md

Registers a process in the users scope for a tenant. Called on every successful channel join.

```APIDOC
## add/2

### Description
Registers the process in the `:users` scope for the tenant. Called on every successful channel join. Returns `:ok`.

### Method
Function

### Endpoint
`Realtime.UsersCounter.add(pid, tenant_id)`

### Parameters
- `pid` (`pid()`) - Required - The channel process (or transport) to count
- `tenant_id` (`string()`) - Required - Tenant external id

### Request Example
```elixir
:ok = Realtime.UsersCounter.add(channel_pid, tenant.external_id)
```

### Response
Returns `:ok`.
```

--------------------------------

### GET /tenant-metrics/:region

Source: https://github.com/supabase/realtime/blob/main/OBSERVABILITY_METRICS.md

Returns the same metrics as `/tenant-metrics` but scoped to a specific region. Recommended scrape interval is 60 seconds.

```APIDOC
## GET /tenant-metrics/:region

### Description
Returns the same metrics as `/tenant-metrics` but scoped to a specific region. Recommended scrape interval is 60 seconds.

### Method
GET

### Endpoint
`/tenant-metrics/:region`

### Path Parameters
- **region** (string) - Required - The region to scope metrics to.

### Authentication
Requires a `Bearer` JWT token in the `Authorization` header signed with `METRICS_JWT_SECRET`.

### Response
#### Success Response (200)
Metrics in Prometheus format with `tenant` labels scoped to the specified region.

#### Response Example
```
# HELP realtime_connection_count Connection count
# TYPE realtime_connection_count gauge
realtime_connection_count{tenant="tenant1",region="us-east-1"} 10
```
```

--------------------------------

### GET /metrics/:region

Source: https://github.com/supabase/realtime/blob/main/OBSERVABILITY_METRICS.md

Returns the same metrics as `/metrics` but scoped to a specific region. Recommended scrape interval is 30 seconds.

```APIDOC
## GET /metrics/:region

### Description
Returns the same metrics as `/metrics` but scoped to a specific region. Recommended scrape interval is 30 seconds.

### Method
GET

### Endpoint
`/metrics/:region`

### Path Parameters
- **region** (string) - Required - The region to scope metrics to.

### Authentication
Requires a `Bearer` JWT token in the `Authorization` header signed with `METRICS_JWT_SECRET`.

### Response
#### Success Response (200)
Metrics in Prometheus format scoped to the specified region.

#### Response Example
```
# HELP beam_utilization BEAM utilization
# TYPE beam_utilization gauge
beam_utilization{region="us-east-1"} 0.5
```
```

--------------------------------

### Generate and use token with curl

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/mix_tasks.md

Example workflow: set API_JWT_SECRET, generate a token, and use it in a curl request to the health endpoint.

```bash
export API_JWT_SECRET="$(mise run print-api-jwt-secret)"
TOKEN=$(mix realtime.gen_token --role service_role --ttl 3600)
curl -H "Authorization: Bearer $TOKEN" http://localhost:4000/api/tenants/health
```

--------------------------------

### Run realtime-check against remote project

Source: https://github.com/supabase/realtime/blob/main/test/e2e/README.md

Run the check against a remote Supabase project. Requires project ref, publishable key, secret key, and database password.

```bash
./realtime-check --project <project-ref> --publishable-key <anon-key> \
  --secret-key <service-role-key> --db-password <password>
```

--------------------------------

### POST /api/tenants

Source: https://github.com/supabase/realtime/blob/main/_autodocs/endpoints.md

Creates a new tenant.

```APIDOC
## POST /api/tenants

### Description
Creates a new tenant.

### Method
POST

### Endpoint
/api/tenants

### Authentication
- **Bearer token** - Required - Verified against `API_JWT_SECRET`/`API_JWT_SECRET_NEXT`.

### Request Body
- **tenant** (object) - Required - Tenant parameters.

### Request Example
```json
{
  "tenant": {
    "external_id": "string",
    "jwt_secret": "string"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - `TenantResponseValue` object.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### after_connect/5

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/postgres_cdc.md

Delegates to the driver's `handle_after_connect/4` callback. Called by the channel after a successful `connect/2` to set up the CDC tree for the given subscription params.

```APIDOC
## after_connect/5

### Description
Delegates to the driver's `handle_after_connect/4` callback. Called by the channel after a successful `connect/2` to set up the CDC tree for the given subscription params.

### Method
Function call

### Endpoint
`Realtime.PostgresCdc.after_connect(module, connect_response, extension, params, tenant)`

### Parameters
- **module** (`module()`) - Required - Driver module
- **connect_response** - Required - Response from `connect/2`
- **extension** - Required - Extension settings
- **params** - Required - Subscription parameters
- **tenant** - Required - Tenant record

### Source
`lib/realtime/postgres_cdc.ex:23`
```

--------------------------------

### whereis/1

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants_connect.md

Returns the Connect process pid for the tenant, or nil.

```APIDOC
## whereis/1

### Description
Returns the `Connect` process pid for the tenant, or `nil`.

### Method
Function

### Endpoint
`Realtime.Tenants.Connect.whereis/1`

### Parameters
#### Path Parameters
- **tenant_id** (`binary()`) - Required - Tenant `external_id`

### Returns
- `pid() | nil` - The Connect process pid or nil.

```

--------------------------------

### Configure RealtimeWeb.UserSocket

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/user_socket.md

Sets up the RealtimeWeb.UserSocket module with a maximum of 99,999 channels per transport, registers the realtime:* channel, and sets the default log level to :error.

```elixir
use RealtimeWeb.Socket, max_channels_per_transport: 99_999
channel "realtime:*", RealtimeChannel
@default_log_level :error
```

--------------------------------

### tenant_topic/3

Source: https://github.com/supabase/realtime/blob/main/_autodocs/api-reference/tenants.md

Builds the PubSub topic used to fan out messages. Public example: `"tenant_id:sub_topic"`; private: `"tenant_id-private:sub_topic"`. Source: `lib/realtime/tenants.ex:510`.

```elixir
@spec tenant_topic(Tenant.t() | binary(), String.t(), boolean()) :: String.t()
def tenant_topic(external_id, sub_topic, public? \\ true)

def tenant_topic(%Tenant{external_id: external_id}, sub_topic, public?), do: tenant_topic(external_id, sub_topic, public?)

def tenant_topic(external_id, sub_topic, false), do: "#{external_id}-private:#{sub_topic}"

def tenant_topic(external_id, sub_topic, true), do: "#{external_id}:#{sub_topic}"
```
Tokens:
Raw