Skip to content

fix(realtime): confirm subscribe on the join reply unless waitsForSubscription is set - #1869

Merged
grdsdev merged 2 commits into
mainfrom
claude/realtime-subscribed-wait-f14833
Nov 18, 2026
Merged

grdsdev merged 2 commits into
mainfrom
claude/realtime-subscribed-wait-f14833

Conversation

@grdsdev

@grdsdev grdsdev commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Problem

With waitsForSubscription false (the default), subscribe() waited for the "Subscribed to PostgreSQL" system message whenever the channel had Postgres changes bindings. A system error, or no message in time, failed the subscribe and left the channel.

That does not match realtime-js or the server:

  • realtime-js reports SUBSCRIBED on the join reply ok. It passes system messages only to on('system') listeners.
  • Without postgres_changes_options.wait, the Realtime server replies ok at once and sets up the bindings after that. On failure it sends a system postgres_changes error, and for most errors it tries again every 5–10 s. So one error is not final.
  • With wait, the server holds the reply until the bindings are live and refuses the join itself on failure or timeout.

Change

  • The join reply ok confirms the join. The SDK's own wait is removed: the .postgres join stage, its timer, and the internal postgresChangesTimeout error.
  • A system ok or error after the join reaches events() as postgresChangesReady or postgresChangesFailed(_:). The channel stays subscribed.
  • With waitsForSubscription true, behavior is the same as before: the server holds the reply, and subscribe() throws if the bindings cannot be set up.
  • The live query channel (SupabaseClient+Stream.swift) sets waitsForSubscription = true, so its first fetch does not start before changes are live.
  • DocC for subscribe(), waitsForSubscription and subscriptionTimeout describes the two modes.
  • docs/migrations/v3/Realtime.md: removes the "subscribe() waits for Postgres changes" silent change. This PR reverts that v3 change, so v2 behavior stays.

No public symbol changes, so sdk-compliance.yaml is unchanged.

Tests

  • Unit tests cover both settings: confirm on the reply, a system ok or error after the join (event only), a system ok before the reply, and a late reply for a timed-out join.
  • Integration: a refused binding (missing table, and each refused typed filter) is now an event on a subscribed channel. A new test checks that waitsForSubscription makes subscribe() throw for a refused binding.
  • RealtimeTests + SupabaseTests: 824 pass. RealtimeIntegrationTests: 42 pass on a local stack.
  • format.sh, swiftlint lint --strict, spell-check.sh and check-compliance.sh are clean.

…scription is set

With waitsForSubscription false, subscribe() waited for the
"Subscribed to PostgreSQL" system message. realtime-js reports SUBSCRIBED
on the join reply, and the server sends that message after the reply and
retries most setup errors, so one error is not final.

subscribe() now returns on the join reply ok. A later system ok or error
is delivered as postgresChangesReady or postgresChangesFailed(_:) and the
channel stays subscribed. With waitsForSubscription true, the server holds
the reply until the bindings are live and refuses the join on failure.

The live query channel sets waitsForSubscription so its first fetch does
not start before changes are live.
@github-actions github-actions Bot added the Realtime Work related to realtime package label Nov 18, 2026
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Realtime
    • subscribe() now returns when the server accepts the channel join by default. Postgres changes readiness and failure are reported later through channel events, without changing the channel’s subscribed status.
    • Set waitsForSubscription to make subscribe() wait for Postgres changes setup; setup failures during that wait still cause the join to fail.
    • Live queries now wait for Postgres changes to be ready before starting the initial fetch.
  • Documentation
    • Updated subscription guidance to explain readiness events, the wait option, and its timeout behavior.

Join replies now confirm channel subscription without waiting for Postgres readiness by default. Later Postgres readiness and failure messages are emitted as channel events without changing the subscribed state. When waitsForSubscription is enabled, the server holds the join reply until binding setup completes. The change removes the separate Postgres join stage, timeout, and timeout error. The live-query channel now enables waitsForSubscription.

Sequence Diagram(s)

sequenceDiagram
  participant RealtimeChannel
  participant RealtimeCore
  participant RealtimeServer
  participant ChannelEvents
  RealtimeChannel->>RealtimeCore: subscribe and send join
  RealtimeCore->>RealtimeServer: phx_join
  RealtimeServer-->>RealtimeCore: join reply
  RealtimeCore-->>RealtimeChannel: confirm subscribed
  RealtimeServer-->>RealtimeCore: Postgres readiness or failure
  RealtimeCore-->>ChannelEvents: emit readiness or failure event
Loading

Possibly related PRs

Suggested labels: Realtime

Change: Bug fix

Merge Risk: Minimal · up to 35e0d

Subscribe now returns when the server accepts the join, and Postgres readiness or failure arrives as events. Callers who need to wait for live changes can set waitsForSubscription. The change is consistent across code, docs and tests, and no merge-blocking risk is evident.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 7f06e9bb-ebb3-4d2b-b5e2-67ed700f4c3a
Commits

Reviewing files that changed from the base of the PR and between 2c1517d and 35e0d9e.

Files selected for processing: 2

  • Sources/Realtime/Types.swift
  • Tests/RealtimeTests/Core/RealtimeCorePostgresTests.swift

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

Finishing Touches
Fix failing CI checks

  • Commit to this branch
  • Create a new PR

@coveralls

coveralls commented Nov 18, 2026 •

Copy link
Copy Markdown

Coverage Report for CI Build 44399892263

Coverage decreased (-0.03%) to 96.176%

Details

  • Coverage decreased (-0.03%) from the base build.
  • Patch coverage: 20 of 20 lines across 4 files are fully covered (100%).
  • 5 coverage regressions across 2 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

5 previously-covered lines in 2 files lost coverage.

File Lines Losing Coverage Coverage
Sources/Helpers/JSONValue/JSONValue.swift 3 97.52%
Sources/Helpers/Task+Named.swift 2 71.43%

Coverage Stats

Coverage Status
Relevant Lines: 17154
Covered Lines: 16498
Line Coverage: 96.18%
Coverage Strength: 532568.31 hits per line

💛 - Coveralls

@grdsdev
grdsdev merged commit da4f9b0 into main Nov 18, 2026
49 of 50 checks passed
@grdsdev
grdsdev deleted the claude/realtime-subscribed-wait-f14833 branch November 18, 2026 21:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Realtime Work related to realtime package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants