Enable confirmed reads by default by clockwork-labs-bot · Pull Request #4390 · clockworklabs/SpacetimeDB

clockwork-labs-bot · 2026-02-22T06:07:31Z

Summary

Enable confirmed reads by default for all WebSocket subscriptions and SQL queries. This is a 2.0 breaking change that improves data integrity.

What changed

Previously, subscription updates and SQL results were sent to clients immediately, before the transaction was confirmed durable. A server crash could cause clients to have observed data that was lost.

Now the server defaults to confirmed=true. Clients receive updates only after durability is confirmed. This adds a small latency cost but guarantees that any data a client receives will survive a server restart.

Changes

Server (2 files, 2 lines each):

subscribe.rs: SubscribeQueryParams.confirmed defaults to true
database.rs: SqlQueryParams.confirmed defaults to true

Documentation:

Migration guide updated with "Confirmed Reads Enabled by Default" section
Added to overview list and quick migration checklist

Opt-out

Clients can opt out by explicitly passing ?confirmed=false in the WebSocket URL or using .withConfirmedReads(false) / .WithConfirmedReads(false) / .with_confirmed_reads(false) in SDKs.

Smoketest impact

Smoketests that don't explicitly pass --confirmed will now get confirmed reads via the server default. This should not cause failures -- confirmed reads only add a small wait for durability confirmation before sending results. The confirmed_reads.py smoketest explicitly passes --confirmed and continues to work as before.

SDK impact

No SDK changes needed. SDKs only send the confirmed query parameter when explicitly set by the user. When not set, the server default applies -- which is now true.

Subscription updates and SQL query results are now only sent to clients after the underlying transaction is confirmed to be durable. This prevents clients from observing data that could be lost on server crash. Previously, confirmed reads were opt-in via ?confirmed=true query param. Now the server defaults to confirmed=true. Clients that need lower latency at the cost of durability guarantees can opt out with ?confirmed=false or .withConfirmedReads(false) in SDKs. Changes: - subscribe.rs: SubscribeQueryParams.confirmed defaults to true - database.rs: SqlQueryParams.confirmed defaults to true - Migration guide updated with new section and checklist item No SDK changes needed -- SDKs that don't send the param will inherit the server default. SDKs that explicitly set confirmed=true/false continue to work as before.

The CLI now always sends ?confirmed=true or ?confirmed=false in subscribe and SQL requests, rather than omitting the parameter when --confirmed is not passed. This ensures CLI behavior is deterministic regardless of the server-side default. Without this fix, smoketests that don't pass --confirmed would inherit the new server default (confirmed=true), causing race conditions in tests like test_add_table_columns where subscribers get disconnected before the durability-confirmed update arrives.

crates/cli/src/subcommands/sql.rs

Per Zeke's review — the CLI should only send ?confirmed when the user passes --confirmed. Otherwise it inherits the server default, which is the correct behavior. Sending confirmed=false explicitly would override the new server default for users who never asked for that.

clockwork-labs-bot

Good call — reverted the CLI commit. The CLI now only sends ?confirmed when --confirmed is explicitly passed, so it inherits the server default. Pushed ea1c16a94.

--confirmed or --confirmed=true sends ?confirmed=true --confirmed=false sends ?confirmed=false Omitting the flag defers to the server default. This lets users explicitly opt out of confirmed reads when needed, while inheriting the server default (now true) by default.

confirmed=True -> passes --confirmed=true confirmed=False -> passes --confirmed=false confirmed=None (default) -> omits flag, inherits server default

crates/cli/src/common_args.rs

crates/client-api/src/routes/subscribe.rs

crates/client-api/src/routes/database.rs

Per Kim's review: change the server-side confirmed field from bool-with-serde-default-true to Option<bool> with #[serde(default)]. The unwrap_or(true) now lives at the usage site (handle_websocket and sql_direct), making it easy to later add a server config option for the default.

crates/client-api/src/routes/subscribe.rs

crates/client-api/src/routes/database.rs

…g_value Per Kim's follow-up review: - Add const DEFAULT_CONFIRMED_READS: bool = true in client-api lib.rs - Use the constant in unwrap_or() at both usage sites - Remove default_missing_value from CLI --confirmed arg so bare --confirmed without a value is not accepted; only --confirmed=true or --confirmed=false explicitly set the parameter

crates/client-api/src/routes/database.rs

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

crates/client-api/src/routes/subscribe.rs

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

crates/cli/src/common_args.rs

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

crates/smoketests/tests/auto_migration.rs

docs/docs/00300-resources/00100-how-to/00600-migrating-to-2.0.md

smoketests/tests/auto_migration.py

bfops

LGTM

Cherry-picked from #4404 Better default for confirmed reads (which are the default since #4390).

# Description of Changes Reducing scope of #4390 to only apply to V2 clients. # API and ABI breaking changes I think this is an API change? # Expected complexity level and risk 1 # Testing  - [ ]  - [ ]  Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

Cherry-picked from #4404 Better default for confirmed reads (which are the default since #4390).

clockwork-labs-bot added the release-2.0 label Feb 22, 2026

cloutiertyler requested review from gefjon and kim February 22, 2026 17:40

clockwork-labs-bot requested review from bfops, cloutiertyler and jdetter as code owners February 22, 2026 17:43

bfops reviewed Feb 22, 2026

View reviewed changes

crates/cli/src/subcommands/sql.rs Outdated Show resolved Hide resolved

clockwork-labs-bot commented Feb 22, 2026

View reviewed changes

clockwork-labs-bot added 2 commits February 22, 2026 14:35

feat: make smoketest subscribe() confirmed param a tri-state

b295044

confirmed=True -> passes --confirmed=true confirmed=False -> passes --confirmed=false confirmed=None (default) -> omits flag, inherits server default

kim reviewed Feb 23, 2026

View reviewed changes

crates/cli/src/common_args.rs Outdated Show resolved Hide resolved

crates/client-api/src/routes/subscribe.rs Outdated Show resolved Hide resolved

crates/client-api/src/routes/database.rs Outdated Show resolved Hide resolved

kim reviewed Feb 23, 2026

View reviewed changes

crates/client-api/src/routes/subscribe.rs Outdated Show resolved Hide resolved

kim reviewed Feb 23, 2026

View reviewed changes

crates/client-api/src/routes/database.rs Outdated Show resolved Hide resolved

bfops reviewed Feb 23, 2026

View reviewed changes

crates/client-api/src/routes/database.rs Outdated Show resolved Hide resolved

Apply suggestion from @bfops

2e40c4f

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

bfops reviewed Feb 23, 2026

View reviewed changes

crates/client-api/src/routes/subscribe.rs Outdated Show resolved Hide resolved

bfops and others added 2 commits February 23, 2026 11:48

Apply suggestion from @bfops

d3ba141

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

[bot/confirmed-reads-default]: fix

20b515c

bfops reviewed Feb 23, 2026

View reviewed changes

crates/cli/src/common_args.rs Outdated Show resolved Hide resolved

bfops and others added 6 commits February 23, 2026 12:03

Apply suggestion from @bfops

5597eca

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

[bot/confirmed-reads-default]: update CLI docs

7fd7b58

[bot/confirmed-reads-default]: fix confirmed reads smoketests

4663686

[bot/confirmed-reads-default]: fix

3e73859

[bot/confirmed-reads-default]: fix

d20331a

[bot/confirmed-reads-default]: fix somehow?

c3ea722

bfops added 2 commits February 23, 2026 13:58

[bot/confirmed-reads-default]: fix with unconfirmed?

e46acd0

[bot/confirmed-reads-default]: fix more smoketests with unconfirmed

06b369c

bfops reviewed Feb 23, 2026

View reviewed changes

crates/smoketests/tests/auto_migration.rs Show resolved Hide resolved

bfops reviewed Feb 23, 2026

View reviewed changes

docs/docs/00300-resources/00100-how-to/00600-migrating-to-2.0.md Show resolved Hide resolved

bfops reviewed Feb 23, 2026

View reviewed changes

smoketests/tests/auto_migration.py Show resolved Hide resolved

[bot/confirmed-reads-default]: comments

124968b

bfops enabled auto-merge February 24, 2026 01:05

bfops approved these changes Feb 24, 2026

View reviewed changes

bfops added this pull request to the merge queue Feb 24, 2026

Merged via the queue into master with commit b002158 Feb 24, 2026
49 of 53 checks passed

bfops mentioned this pull request Feb 24, 2026

Confirmed reads default only for v2 connections #4419

Merged

2 tasks

kim added a commit that referenced this pull request Feb 24, 2026

durability: Default local durability sync interval to 50ms

e0c9df8

Cherry-picked from #4404 Better default for confirmed reads (which are the default since #4390).

kim mentioned this pull request Feb 24, 2026

durability: Default local durability sync interval to 50ms #4420

Merged

github-merge-queue bot pushed a commit that referenced this pull request Feb 24, 2026

durability: Default local durability sync interval to 50ms (#4420)

11a693d

Cherry-picked from #4404 Better default for confirmed reads (which are the default since #4390).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enable confirmed reads by default#4390

Enable confirmed reads by default#4390
bfops merged 19 commits intomasterfrom
bot/confirmed-reads-default

clockwork-labs-bot commented Feb 22, 2026

Uh oh!

Uh oh!

clockwork-labs-bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bfops left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

clockwork-labs-bot commented Feb 22, 2026

Summary

What changed

Changes

Opt-out

Smoketest impact

SDK impact

Uh oh!

Uh oh!

clockwork-labs-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bfops left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants