**⚠ WARNING: v0.10.0 Breaking Change **
Channels connections are secured by default in production. See Channels Authorization for more info.
Listens to changes in a PostgreSQL Database and broadcasts them over websockets.
Contents
Supabase is hiring an Elixir expert to work full-time on this repo. If you have the experience, get in touch.
This repo is still under heavy development and the documentation is evolving. You're welcome to try it, but expect some breaking changes. Watch "releases" of this repo to get notified of major updates. And give us a star if you like it!
import { Socket } = '@supabase/realtime-js'
var socket = new Socket(process.env.REALTIME_URL)
socket.connect()
// Listen to all changes to user ID 99
var allChanges = this.socket.channel('realtime:public:users:id.eq.99')
.join()
.on('*', payload => { console.log('Update received!', payload) })
// Listen to only INSERTS on the 'users' table in the 'public' schema
var allChanges = this.socket.channel('realtime:public:users')
.join()
.on('INSERT', payload => { console.log('Update received!', payload) })
// Listen to all updates from the 'public' schema
var allChanges = this.socket.channel('realtime:public')
.join()
.on('UPDATE', payload => { console.log('Update received!', payload) })
// Listen to all changes in the database
let allChanges = this.socket.channel('realtime:*')
.join()
.on('*', payload => { console.log('Update received!', payload) })
This is an Elixir server (Phoenix) that allows you to listen to changes in your database via websockets.
It works like this:
NOTIFY
?A few reasons:
We have set up some simple examples that show how to use this server:
There are a some requirements for your database
wal_level
set to logical. You can check this by running SHOW wal_level;
. To set the wal_level
, you can call ALTER SYSTEM SET wal_level = logical;
max_replication_slots
to at least 1: ALTER SYSTEM SET max_replication_slots = 5;
PUBLICATION
for this server to listen to: CREATE PUBLICATION supabase_realtime FOR ALL TABLES;
REPLICA IDENTITY
to FULL
like this: ALTER TABLE your_table REPLICA IDENTITY FULL;
. This has to be set for each table unfortunately.The easiest way to get started is just to use our docker image. We will add more deployment methods soon.
# Update the environment variables to point to your own database
docker run \
-e DB_HOST='docker.for.mac.host.internal' \
-e DB_NAME='postgres' \
-e DB_USER='postgres' \
-e DB_PASSWORD='postgres' \
-e DB_PORT=5432 \
-e PORT=4000 \
-e HOSTNAME='localhost' \
-e JWT_SECRET='SOMETHING_SUPER_SECRET' \
-p 4000:4000 \
supabase/realtime
OPTIONS
DB_HOST # {string} Database host URL
DB_NAME # {string} Postgres database name
DB_USER # {string} Database user
DB_PASSWORD # {string} Database password
DB_PORT # {number} Database port
SLOT_NAME # {string} A unique name for Postgres to track where this server has "listened until". If the server dies, it can pick up from the last position. This should be lowercase.
PORT # {number} Port which you can connect your client/listeners
SECURE_CHANNELS # {string} (options: 'true' or 'false') Enable/Disable channels authorization via JWT verification.
JWT_SECRET # {string} HS algorithm octet key (e.g. "95x0oR8jq9unl9pOIx"). Only required if SECURE_CHANNELS is set to true.
JWT_CLAIM_VALIDATORS # {string} Expected claim key/value pairs compared to JWT claims via equality checks in order to validate JWT. e.g. '{"iss": "Issuer", "nbf": 1610078130}'. This is optional but encouraged.
EXAMPLE: RUNNING SERVER WITH ALL OPTIONS
# Update the environment variables to point to your own database
docker run \
-e DB_HOST='docker.for.mac.host.internal' \
-e DB_NAME='postgres' \
-e DB_USER='postgres' \
-e DB_PASSWORD='postgres' \
-e DB_PORT=5432 \
-e PORT=4000 \
-e HOSTNAME='localhost' \
-e JWT_SECRET='SOMETHING_SUPER_SECRET' \
-p 4000:4000 \
-e SECURE_CHANNELS='true' \
-e JWT_SECRET='jwt-secret' \
-e JWT_CLAIM_VALIDATORS='{"iss": "Issuer", "nbf": 1610078130}' \
supabase/realtime
Channels connections are authorized via JWT verification. Only supports JWTs signed with the following algorithms:
Verify JWT claims by setting JWT_CLAIM_VALIDATORS:
e.g. {'iss': 'Issuer', 'nbf': 1610078130}
Then JWT's "iss" value must equal "Issuer" and "nbf" value must equal 1610078130.
NOTE: JWT expiration is checked automatically.
Development: Channels are not secure by default. Set SECURE_CHANNELS to true
to test JWT verification locally.
Production: Channels are secure by default and you must set JWT_SECRET. Set SECURE_CHANNELS to false
to proceed without checking authorization.
mix.exs
To trigger a release you must tag the commit, then push to origin.
git tag -a 0.x.x -m "Some release details / link to release notes"
git push origin 0.x.x
This repo is licensed under Apache 2.0.
We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves. Thanks to these sponsors who are making the OSS ecosystem better for everyone.