{"id":30172917,"url":"https://github.com/tealbase/realtime","last_synced_at":"2026-05-15T01:11:49.800Z","repository":{"id":304724190,"uuid":"1019681284","full_name":"Tealbase/realtime","owner":"Tealbase","description":"Broadcast, Presence, and Postgres Changes via WebSockets","archived":false,"fork":false,"pushed_at":"2025-07-25T12:54:31.000Z","size":3770,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T19:37:03.196Z","etag":null,"topics":["cdc","change-data-capture","crdt","distributed-systems","elixir","phoenix","phoenix-framework","postgres","postgresql","pubsub","realtime"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tealbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["supabase"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-07-14T17:48:07.000Z","updated_at":"2025-07-25T12:54:38.000Z","dependencies_parsed_at":"2025-07-15T00:05:38.169Z","dependency_job_id":"0df32dcb-4ffc-4682-ade9-419499d80dd5","html_url":"https://github.com/Tealbase/realtime","commit_stats":null,"previous_names":["tealbase/realtime"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Tealbase/realtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tealbase%2Frealtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tealbase%2Frealtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tealbase%2Frealtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tealbase%2Frealtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tealbase","download_url":"https://codeload.github.com/Tealbase/realtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tealbase%2Frealtime/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269970136,"owners_count":24505478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdc","change-data-capture","crdt","distributed-systems","elixir","phoenix","phoenix-framework","postgres","postgresql","pubsub","realtime"],"created_at":"2025-08-11T23:18:17.890Z","updated_at":"2025-10-26T20:47:37.317Z","avatar_url":"https://github.com/Tealbase.png","language":"Elixir","funding_links":["https://github.com/sponsors/supabase"],"categories":[],"sub_categories":[],"readme":"\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n \u003ca href=\"https://tealbase.io\"\u003e\n \u003cpicture\u003e\n \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/tealbase/tealbase/master/packages/common/assets/images/tealbase-logo-wordmark--dark.svg\"\u003e\n \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/tealbase/tealbase/master/packages/common/assets/images/tealbase-logo-wordmark--light.svg\"\u003e\n \u003cimg alt=\"tealbase Logo\" width=\"300\" src=\"https://raw.githubusercontent.com/tealbase/tealbase/master/packages/common/assets/images/logo-preview.jpg\"\u003e\n \u003c/picture\u003e\n \u003c/a\u003e\n\n \u003ch1 align=\"center\"\u003etealbase Realtime\u003c/h1\u003e\n\n \u003cp align=\"center\"\u003e\n Send ephemeral messages, track and synchronize shared state, and listen to Postgres changes all over WebSockets.\n \u003cbr /\u003e\n \u003ca href=\"https://multiplayer.dev\"\u003eMultiplayer Demo\u003c/a\u003e\n ·\n \u003ca href=\"https://github.com/tealbase/realtime/issues/new?assignees=\u0026labels=enhancement\u0026template=2.Feature_request.md\"\u003eRequest Feature\u003c/a\u003e\n ·\n \u003ca href=\"https://github.com/tealbase/realtime/issues/new?assignees=\u0026labels=bug\u0026template=1.Bug_report.md\"\u003eReport Bug\u003c/a\u003e\n \u003cbr /\u003e\n \u003c/p\u003e\n\u003c/p\u003e\n\n## Status\n\n| Features | v1 | v2 | Status |\n| ---------------- | --- | --- | ------ |\n| Postgres Changes | ✔ | ✔ | GA |\n| Broadcast | | ✔ | Beta |\n| Presence | | ✔ | Beta |\n\nThis repository focuses on version 2 but you can still access the previous version's [code](https://github.com/tealbase/realtime/tree/v1) and [Docker image](https://hub.docker.com/layers/tealbase/realtime/v1.0.0/images/sha256-e2766e0e3b0d03f7e9aa1b238286245697d0892c2f6f192fd2995dca32a4446a). For the latest Docker images go to https://hub.docker.com/r/tealbase/realtime.\n\nThe codebase is under heavy development and the documentation is constantly evolving. Give it a try and let us know what you think by creating an issue. Watch [releases](https://github.com/tealbase/realtime/releases) of this repo to get notified of updates. And give us a star if you like it!\n\n## Overview\n\n### What is this?\n\nThis is a server built with Elixir using the [Phoenix Framework](https://www.phoenixframework.org) that enables the following functionality:\n\n- Broadcast: Send ephemeral messages from client to clients with low latency.\n- Presence: Track and synchronize shared state between clients.\n- Postgres Changes: Listen to Postgres database changes and send them to authorized clients.\n\nFor a more detailed overview head over to [Realtime guides](https://tealbase.com/docs/guides/realtime).\n\n### Does this server guarantee message delivery?\n\nThe server does not guarantee that every message will be delivered to your clients so keep that in mind as you're using Realtime.\n\n## Quick start\n\nYou can check out the [Multiplayer demo](https://multiplayer.dev) that features Broadcast, Presence and Postgres Changes under the demo directory: https://github.com/tealbase/realtime/tree/main/demo.\n\n## Client libraries\n\n- JavaScript: [@tealbase/realtime-js](https://github.com/tealbase/realtime-js)\n- Dart: [@tealbase/realtime-dart](https://github.com/tealbase/realtime-dart)\n\n## Server Setup\n\nTo get started, spin up your Postgres database and Realtime server containers defined in `docker-compose.yml`. As an example, you may run `docker-compose -f docker-compose.yml up`.\n\n\u003e **Note**\n\u003e tealbase runs Realtime in production with a separate database that keeps track of all tenants. However, a schema, `_realtime`, is created when spinning up containers via `docker-compose.yml` to simplify local development.\n\nA tenant has already been added on your behalf. You can confirm this by checking the `_realtime.tenants` and `_realtime.extensions` tables inside the database.\n\nYou can add your own by making a `POST` request to the server. You must change both `name` and `external_id` while you may update other values as you see fit:\n\n```bash\n curl -X POST \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIiLCJpYXQiOjE2NzEyMzc4NzMsImV4cCI6MTcwMjc3Mzk5MywiYXVkIjoiIiwic3ViIjoiIn0._ARixa2KFUVsKBf3UGR90qKLCpGjxhKcXY4akVbmeNQ' \\\n -d $'{\n \"tenant\" : {\n \"name\": \"realtime-dev\",\n \"external_id\": \"realtime-dev\",\n \"jwt_secret\": \"a1d99c8b-91b6-47b2-8f3c-aa7d9a9ad20f\",\n \"extensions\": [\n {\n \"type\": \"postgres_cdc_rls\",\n \"settings\": {\n \"db_name\": \"postgres\",\n \"db_host\": \"host.docker.internal\",\n \"db_user\": \"postgres\",\n \"db_password\": \"postgres\",\n \"db_port\": \"5432\",\n \"region\": \"us-west-1\",\n \"poll_interval_ms\": 100,\n \"poll_max_record_bytes\": 1048576\n }\n }\n ]\n }\n }' \\\n http://localhost:4000/api/tenants\n```\n\n\u003e **Note**\n\u003e The `Authorization` token is signed with the secret set by `API_JWT_SECRET` in `docker-compose.yml`.\n\nIf you want to listen to Postgres changes, you can create a table and then add the table to the `tealbase_realtime` publication:\n\n```sql\ncreate table test (\n id serial primary key\n);\n\nalter publication tealbase_realtime add table test;\n```\n\nYou can start playing around with Broadcast, Presence, and Postgres Changes features either with the client libs (e.g. `@tealbase/realtime-js`), or use the built in Realtime Inspector on localhost, `http://localhost:4000/inspector/new` (make sure the port is correct for your development environment).\n\nThe WebSocket URL must contain the subdomain, `external_id` of the tenant on the `_realtime.tenants` table, and the token must be signed with the `jwt_secret` that was inserted along with the tenant.\n\nIf you're using the default tenant, the URL is `ws://realtime-dev.localhost:4000/socket` (make sure the port is correct for your development environment), and you can use `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDMwMjgwODcsInJvbGUiOiJwb3N0Z3JlcyJ9.tz_XJ89gd6bN8MBpCl7afvPrZiBH6RB65iA1FadPT3Y` for the token. The token must have `exp` and `role` (database role) keys.\n\n**Environment Variables**\n\n| Variable | Type | Description |\n| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| PORT | number | Port which you can connect your client/listeners |\n| DB_HOST | string | Database host URL |\n| DB_PORT | number | Database port |\n| DB_USER | string | Database user |\n| DB_PASSWORD | string | Database password |\n| DB_NAME | string | Postgres database name |\n| DB_ENC_KEY | string | Key used to encrypt sensitive fields in \\_realtime.tenants and \\_realtime.extensions tables. Recommended: 16 characters. |\n| DB_AFTER_CONNECT_QUERY | string | Query that is run after server connects to database. |\n| DB_IP_VERSION | string | Sets the IP Version to be used. Allowed values are \"ipv6\" and \"ipv4\". If none are set we will try to infer the correct version |\n| API_JWT_SECRET | string | Secret that is used to sign tokens used to manage tenants and their extensions via HTTP requests. |\n| SECRET_KEY_BASE | string | Secret used by the server to sign cookies. Recommended: 64 characters. |\n| ERL_AFLAGS | string | Set to either \"-proto_dist inet_tcp\" or \"-proto_dist inet6_tcp\" depending on whether or not your network uses IPv4 or IPv6, respectively. |\n| APP_NAME | string | A name of the server. |\n| DNS_NODES | string | Node name used when running server in a cluster. |\n| MAX_CONNECTIONS | string | Set the soft maximum for WebSocket connections. Defaults to '16384'. |\n| MAX_HEADER_LENGTH | string | Set the maximum header length for connections (in bytes). Defaults to '4096'. |\n| NUM_ACCEPTORS | string | Set the number of server processes that will relay incoming WebSocket connection requests. Defaults to '100'. |\n| DB_QUEUE_TARGET | string | Maximum time to wait for a connection from the pool. Defaults to '5000' or 5 seconds. See for more info: [DBConnection](https://hexdocs.pm/db_connection/DBConnection.html#start_link/2-queue-config). |\n| DB_QUEUE_INTERVAL | string | Interval to wait to check if all connections were checked out under DB_QUEUE_TARGET. If all connections surpassed the target during this interval than the target is doubled. Defaults to '5000' or 5 seconds. See for more info: [DBConnection](https://hexdocs.pm/db_connection/DBConnection.html#start_link/2-queue-config). |\n| DB_POOL_SIZE | string | Sets the number of connections in the database pool. Defaults to '5'. |\n| SLOT_NAME_SUFFIX | string | This is appended to the replication slot which allows making a custom slot name. May contain lowercase letters, numbers, and the underscore character. Together with the default `tealbase_realtime_replication_slot`, slot name should be up to 64 characters long. |\n| TENANT_MAX_BYTES_PER_SECOND | string | The default value of maximum bytes per second that each tenant can support, used when creating a tenant for the first time. Defaults to '100_000'. |\n| TENANT_MAX_CHANNELS_PER_CLIENT | string | The default value of maximum number of channels each tenant can support, used when creating a tenant for the first time. Defaults to '100'. |\n| TENANT_MAX_CONCURRENT_USERS | string | The default value of maximum concurrent users per channel that each tenant can support, used when creating a tenant for the first time. Defaults to '200'. |\n| TENANT_MAX_EVENTS_PER_SECOND | string | The default value of maximum events per second that each tenant can support, used when creating a tenant for the first time. Defaults to '100'. |\n| TENANT_MAX_JOINS_PER_SECOND | string | The default value of maximum channel joins per second that each tenant can support, used when creating a tenant for the first time. Defaults to '100'. |\n| SEED_SELF_HOST | boolean | Seeds the system with default tenant |\n| SELF_HOST_TENANT_NAME | string | Tenant reference to be used for self host. Do keep in mind to use a URL compatible name |\n| LOG_LEVEL | string | Sets log level for Realtime logs. Defaults to info, supported levels are: info, emergency, alert, critical, error, warning, notice, debug |\n| RUN_JANITOR | boolean | Do you want to janitor tasks to run |\n| JANITOR_SCHEDULE_TIMER_IN_MS | number | Time in ms to run the janitor task |\n| JANITOR_SCHEDULE_RANDOMIZE | boolean | Adds a randomized value of minutes to the timer |\n| JANITOR_RUN_AFTER_IN_MS | number | Tells system when to start janitor tasks after boot |\n| JANITOR_CLEANUP_MAX_CHILDREN | number | Maximum number of concurrent tasks working on janitor cleanup |\n| JANITOR_CLEANUP_CHILDREN_TIMEOUT | number | Timeout for each async task for janitor cleanup |\n| JANITOR_CHUNK_SIZE | number | Number of tenants to process per chunk. Each chunk will be processed by a Task |\n| MIGRATION_PARTITION_SLOTS | number | Number of dynamic supervisor partitions used by the migrations process |\n| METRICS_CLEANER_SCHEDULE_TIMER_IN_MS | number | Time in ms to run the Metric Cleaner task |\n| REQUEST_ID_BAGGAGE_KEY | string | OTEL Baggage key to be used as request id |\n| OTEL_SDK_DISABLED | boolean | Disable OpenTelemetry tracing completely when 'true' |\n| OTEL_TRACES_EXPORTER | string | Possible values: `otlp` or `none`. See [https://github.com/open-telemetry/opentelemetry-erlang/tree/v1.4.0/apps#os-environment] for more details on how to configure the traces exporter. |\n| OTEL_TRACES_SAMPLER | string | Default to `parentbased_always_on` . More info [here](https://opentelemetry.io/docs/languages/erlang/sampling/#environment-variables) |\n\nThe OpenTelemetry variables mentioned above are not an exhaustive list of all [supported environment variables](https://opentelemetry.io/docs/languages/sdk-configuration/).\n\n## WebSocket URL\n\nThe WebSocket URL is in the following format for local development: `ws://[external_id].localhost:4000/socket/websocket`\n\nIf you're using tealbase's hosted Realtime in production the URL is `wss://[project-ref].tealbase.co/realtime/v1/websocket?apikey=[anon-token]\u0026log_level=info\u0026vsn=1.0.0\"`\n\n## WebSocket Connection Authorization\n\nWebSocket connections are authorized via symmetric JWT verification. Only supports JWTs signed with the following algorithms:\n\n- HS256\n- HS384\n- HS512\n\nVerify JWT claims by setting JWT_CLAIM_VALIDATORS:\n\n\u003e e.g. {'iss': 'Issuer', 'nbf': 1610078130}\n\u003e\n\u003e Then JWT's \"iss\" value must equal \"Issuer\" and \"nbf\" value must equal 1610078130.\n\n**Note:**\n\n\u003e JWT expiration is checked automatically. `exp` and `role` (database role) keys are mandatory.\n\n**Authorizing Client Connection**: You can pass in the JWT by following the instructions under the Realtime client lib. For example, refer to the **Usage** section in the [@tealbase/realtime-js](https://github.com/tealbase/realtime-js) client library.\n\n## Error Operational Codes\n\nThis is the list of operational codes that can help you understand your deployment and your usage.\n\n| Code | Description |\n| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| TopicNameRequired | You are trying to use Realtime without a topic name set |\n| RealtimeDisabledForConfiguration | The configuration provided to Realtime on connect will not be able to provide you any Postgres Changes |\n| TenantNotFound | The tenant you are trying to connect to does not exist |\n| ErrorConnectingToWebsocket | Error when trying to connect to the WebSocket server |\n| ErrorAuthorizingWebsocket | Error when trying to authorize the WebSocket connection |\n| TableHasSpacesInName | The table you are trying to listen to has spaces in its name which we are unable to support |\n| UnableToDeleteTenant | Error when trying to delete a tenant |\n| UnableToSetPolicies | Error when setting up Authorization Policies |\n| UnableCheckoutConnection | Error when trying to checkout a connection from the tenant pool |\n| UnableToSubscribeToPostgres | Error when trying to subscribe to Postgres changes |\n| ChannelRateLimitReached | The number of channels you can create has reached its limit |\n| ConnectionRateLimitReached | The number of connected clients as reached its limit |\n| ClientJoinRateLimitReached | The rate of joins per second from your clients as reached the channel limits |\n| RealtimeDisabledForTenant | Realtime has been disabled for the tenant |\n| UnableToConnectToTenantDatabase | Realtime was not able to connect to the tenant's database |\n| DatabaseLackOfConnections | Realtime was not able to connect to the tenant's database due to not having enough available connections |\n| TooManyConnectAttempts | Realtime restricted the amount of attempts when connecting to the tenants database |\n| RealtimeNodeDisconnected | Realtime is a distributed application and this means that one the system is unable to communicate with one of the distributed nodes |\n| MigrationsFailedToRun | Error when running the migrations against the Tenant database that are required by Realtime |\n| StartListenAndReplicationFailed | Error when starting the replication and listening of errors for database broadcasting |\n| ReplicationMaxWalSendersReached | Maximum number of WAL senders reached in tenant database, check how to increase this value in this [link](https://tealbase.com/docs/guides/database/custom-postgres-config#cli-configurable-settings) |\n| MigrationCheckFailed | Check to see if we require to run migrations fails |\n| PartitionCreationFailed | Error when creating partitions for realtime.messages |\n| ErrorStartingPostgresCDCStream | Error when starting the Postgres CDC stream which is used for Postgres Changes |\n| UnknownDataProcessed | An unknown data type was processed by the Realtime system |\n| ErrorStartingPostgresCDC | Error when starting the Postgres CDC extension which is used for Postgres Changes |\n| ReplicationSlotBeingUsed | The replication slot is being used by another transaction |\n| PoolingReplicationPreparationError | Error when preparing the replication slot |\n| PoolingReplicationError | Error when pooling the replication slot |\n| SubscriptionDeletionFailed | Error when trying to delete a subscription for postgres changes |\n| UnableToDeletePhantomSubscriptions | Error when trying to delete subscriptions that are no longer being used |\n| UnableToCheckProcessesOnRemoteNode | Error when trying to check the processes on a remote node |\n| UnableToCreateCounter | Error when trying to create a counter to track rate limits for a tenant |\n| UnableToIncrementCounter | Error when trying to increment a counter to track rate limits for a tenant |\n| UnableToDecrementCounter | Error when trying to decrement a counter to track rate limits for a tenant |\n| UnableToUpdateCounter | Error when trying to update a counter to track rate limits for a tenant |\n| UnableToFindCounter | Error when trying to find a counter to track rate limits for a tenant |\n| UnhandledProcessMessage | Unhandled message received by a Realtime process |\n| UnableToSetPolicies | We were not able to set policies for this connection |\n| UnableToTrackPresence | Error when handling track presence for this socket |\n| UnknownPresenceEvent | Presence event type not recognized by service |\n| IncreaseConnectionPool | The number of connections you have set for Realtime are not enough to handle your current use case |\n| RlsPolicyError | Error on RLS policy used for authorization |\n| ConnectionInitializing | Database is initializing connection |\n| DatabaseConnectionIssue | Database had connection issues and connection was not able to be established |\n| UnableToConnectToProject | Unable to connect to Project database |\n| InvalidJWTExpiration | JWT exp claim value it's incorrect |\n| JwtSignatureError | JWT signature was not able to be validated |\n| Unauthorized | Unauthorized access to Realtime channel |\n| RealtimeRestarting | Realtime is currently restarting |\n| UnableToProcessListenPayload | Payload sent in NOTIFY operation was JSON parsable |\n| UnableToListenToTenantDatabase | Unable to LISTEN for notifications against the Tenant Database |\n| UnprocessableEntity | Received a HTTP request with a body that was not able to be processed by the endpoint |\n| InitializingProjectConnection | Connection against Tenant database is still starting |\n| TimeoutOnRpcCall | RPC request within the Realtime server as timed out. |\n| ErrorOnRpcCall | Error when calling another realtime node |\n| ErrorExecutingTransaction | Error executing a database transaction in tenant database |\n| SynInitializationError | Our framework to syncronize processes has failed to properly startup a connection to the database |\n| JanitorFailedToDeleteOldMessages | Scheduled task for realtime.message cleanup was unable to run |\n| UnknownErrorOnController | An error we are not handling correctly was triggered on a controller |\n| UnknownErrorOnChannel | An error we are not handling correctly was triggered on a channel |\n\n## License\n\nThis repo is licensed under Apache 2.0.\n\n## Credits\n\n- [Phoenix](https://github.com/phoenixframework/phoenix) - `Realtime` server is built with the amazing Elixir framework.\n- [Phoenix Channels JavaScript Client](https://github.com/phoenixframework/phoenix/tree/master/assets/js/phoenix) - [@tealbase/realtime-js](https://github.com/tealbase/realtime-js) client library heavily draws from the Phoenix Channels client library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftealbase%2Frealtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftealbase%2Frealtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftealbase%2Frealtime/lists"}