Supabase Realtime Python Client

2.28.3 · active · verified Sun Apr 05

The `realtime` library is the official Python client for Supabase Realtime, offering capabilities for real-time communication. It allows applications to send and receive ephemeral messages via Broadcast, track and synchronize shared state with Presence, and listen for database changes using Postgres Change Data Capture (CDC). The current version is 2.28.3, and it receives frequent updates as part of the broader Supabase ecosystem.

Warnings

gotcha The `REALTIME_URL` format is crucial. For local development, it's typically `ws://localhost:4000/websocket`. For a deployed Supabase project, use `wss://<project_ref>.supabase.co/realtime/v1`. Using the incorrect URL can lead to connection failures.
Fix: Verify the `REALTIME_URL` against your Supabase project's Realtime connection string in the Supabase Dashboard, or the local Supabase CLI output.
breaking The protocol for `postgres_changes` has shifted from using the key 'events' to 'event' in the payload. Older clients expecting 'events' will fail to process real-time database changes correctly.
Fix: Update your code to access the change data using `payload['event']` instead of `payload['events']`. This change was noted in `supabase-py`'s v2.27.1 release, which the `realtime` client aligns with.
gotcha Realtime connections can experience timeouts or failed subscriptions, often due to network instability, incorrect API keys, or server-side issues. Common errors include 'keepalive ping timeout' or 'join push timeout'.
Fix: Implement robust error handling and reconnection logic. Ensure your `API_KEY` is valid and has the necessary JWT claims (e.g., `exp` and `role`). Monitor network conditions and Supabase service status. Review GitHub issues for known transient problems.
deprecated Python 3.8 support might be deprecated in future releases, following the general trend of the Supabase Python ecosystem. The library currently requires Python 3.9+.
Fix: Ensure your project uses Python 3.9 or higher. Regularly check the `realtime` PyPI page or GitHub repository for updated Python version requirements.
gotcha The `API_KEY` used for connecting to the Realtime server, especially for private channels, must be a JWT that includes `exp` (expiration) and `role` (database role) claims. An invalid or expired JWT will result in authorization failures.
Fix: When generating or using JWTs, ensure they are correctly signed, unexpired, and contain the appropriate `role` claim that matches your Row Level Security (RLS) policies in Supabase.

Install

pip install realtime Install `realtime`

Imports

AsyncRealtimeClient

from realtime import AsyncRealtimeClient

RealtimeSubscribeStates

from realtime import RealtimeSubscribeStates

Quickstart

This quickstart demonstrates how to establish a connection to the Supabase Realtime server, subscribe to a channel, listen for PostgreSQL database changes, and receive broadcast messages. Remember to replace placeholder `REALTIME_URL` and `SUPABASE_ANON_KEY` with your actual Supabase project details, typically retrieved from your project settings. Ensure your API key has the necessary permissions (e.g., 'anon' key for public read access or a 'service_role' key for elevated privileges).

import asyncio
import os
from typing import Optional
from realtime import AsyncRealtimeClient, RealtimeSubscribeStates

async def main():
    REALTIME_URL = os.environ.get('REALTIME_URL', 'ws://localhost:4000/websocket')
    API_KEY = os.environ.get('SUPABASE_ANON_KEY', 'YOUR_SUPABASE_ANON_KEY') # Or your service role key

    print(f"Connecting to {REALTIME_URL} with API Key: {API_KEY[:5]}...")

    socket = AsyncRealtimeClient(REALTIME_URL, API_KEY)
    channel = socket.channel("my_test_channel")

    def _on_subscribe(status: RealtimeSubscribeStates, err: Optional[Exception]):
        if status == RealtimeSubscribeStates.SUBSCRIBED:
            print("Connected to channel!")
        elif status == RealtimeSubscribeStates.CHANNEL_ERROR:
            print(f"Error subscribing to channel: {err}")
        elif status == RealtimeSubscribeStates.TIMED_OUT:
            print("Subscription timed out.")
        elif status == RealtimeSubscribeStates.CLOSED:
            print("Channel unexpectedly closed.")

    # Listen for database changes (example: all changes in 'public' schema)
    channel.on_postgres_changes(
        "*",
        schema="public",
        callback=lambda payload: print("Database change received:", payload)
    )

    # Listen for broadcast messages
    channel.on_broadcast("my-event", lambda payload: print("Broadcast received:", payload))

    await channel.subscribe(_on_subscribe)
    await asyncio.sleep(60) # Keep the client alive for 60 seconds
    await socket.disconnect()

if __name__ == "__main__":
    # Set these environment variables or replace placeholders for a live connection
    # os.environ['REALTIME_URL'] = 'wss://<project_ref>.supabase.co/realtime/v1'
    # os.environ['SUPABASE_ANON_KEY'] = 'eyJ...'
    asyncio.run(main())

view raw JSON →