Enable confirmed reads by default (#4390)

## 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`.

---------

Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

Author: 3 people

crates/cli/src/common_args.rs

@@ -41,7 +41,8 @@ pub fn confirmed() -> Arg {
     Arg::new("confirmed")
         .required(false)
         .long("confirmed")
-        .action(SetTrue)
+        .num_args(1)
+        .value_parser(value_parser!(bool))
         .help("Instruct the server to deliver only updates of confirmed transactions")
 }
 

crates/cli/src/subcommands/sql.rs

@@ -235,12 +235,12 @@ pub async fn exec(config: Config, args: &ArgMatches) -> Result<(), anyhow::Error
             }
         })?;
         let query = resolved.remaining_args.join(" ");
-        let confirmed = args.get_flag("confirmed");
+        let confirmed = args.get_one::<bool>("confirmed").copied();
 
         let con = parse_req(config, args, &resolved.database, resolved.server.as_deref()).await?;
         let mut api = ClientApi::new(con).sql();
-        if confirmed {
-            api = api.query(&[("confirmed", "true")]);
+        if let Some(confirmed) = confirmed {
+            api = api.query(&[("confirmed", if confirmed { "true" } else { "false" })]);
         }
 
         run_sql(api, &query, false).await?;

crates/cli/src/subcommands/subscribe.rs

@@ -148,7 +148,7 @@ pub async fn exec(config: Config, args: &ArgMatches) -> Result<(), anyhow::Error
     let num = args.get_one::<u32>("num-updates").copied();
     let timeout = args.get_one::<u32>("timeout").copied();
     let print_initial_update = args.get_flag("print_initial_update");
-    let confirmed = args.get_flag("confirmed");
+    let confirmed = args.get_one::<bool>("confirmed").copied();
     let resolved_server = server.or(resolved.server.as_deref());
 
     let mut config = config;
@@ -169,8 +169,9 @@ pub async fn exec(config: Config, args: &ArgMatches) -> Result<(), anyhow::Error
         unknown => unreachable!("Invalid URL scheme in `Connection::db_uri`: {unknown}"),
     })
     .unwrap();
-    if confirmed {
-        url.query_pairs_mut().append_pair("confirmed", "true");
+    if let Some(confirmed) = confirmed {
+        url.query_pairs_mut()
+            .append_pair("confirmed", if confirmed { "true" } else { "false" });
     }
 
     // Create the websocket request.

crates/client-api/src/lib.rs

@@ -27,6 +27,11 @@ pub mod auth;
 pub mod routes;
 pub mod util;
 
+/// The default value for the `confirmed` reads parameter when the client does
+/// not specify it explicitly. When `true`, the server waits for durability
+/// confirmation before sending subscription updates and SQL results.
+pub const DEFAULT_CONFIRMED_READS: bool = true;
+
 /// Defines the state / environment of a SpacetimeDB node from the PoV of the
 /// client API.
 ///

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

@@ -496,7 +496,7 @@ pub struct SqlQueryParams {
     /// If `true`, return the query result only after its transaction offset
     /// is confirmed to be durable.
     #[serde(default)]
-    pub confirmed: bool,
+    pub confirmed: Option<bool>,
 }
 
 pub async fn sql_direct<S>(
@@ -518,7 +518,8 @@ where
         .authorize_sql(caller_identity, database.database_identity)
         .await?;
 
-    host.exec_sql(auth, database, confirmed, sql).await
+    host.exec_sql(auth, database, confirmed.unwrap_or(crate::DEFAULT_CONFIRMED_READS), sql)
+        .await
 }
 
 pub async fn sql<S>(

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

@@ -92,7 +92,7 @@ pub struct SubscribeQueryParams {
     ///
     /// If `false`, send them immediately.
     #[serde(default)]
-    pub confirmed: bool,
+    pub confirmed: Option<bool>,
 }
 
 pub fn generate_random_connection_id() -> ConnectionId {
@@ -170,7 +170,7 @@ where
         version: negotiated.version,
         compression,
         tx_update_full: !light,
-        confirmed_reads: confirmed,
+        confirmed_reads: confirmed.unwrap_or(crate::DEFAULT_CONFIRMED_READS),
     };
 
     // TODO: Should also maybe refactor the code and the protocol to allow a single websocket

crates/pg/src/pg_server.rs

@@ -161,7 +161,7 @@ where
             database::sql_direct(
                 self.ctx.clone(),
                 db,
-                SqlQueryParams { confirmed: true },
+                SqlQueryParams { confirmed: Some(true) },
                 params.caller_identity,
                 query.to_string(),
             )

crates/smoketests/src/lib.rs

@@ -1136,6 +1136,7 @@ log = "0.4"
             "--server",
             &self.server_url,
             "--confirmed",
+            "true",
             identity.as_str(),
             query,
         ])
@@ -1375,16 +1376,26 @@ log = "0.4"
     /// This matches Python's subscribe semantics - start subscription first,
     /// perform actions, then call the handle to collect results.
     pub fn subscribe_background(&self, queries: &[&str], n: usize) -> Result<SubscriptionHandle> {
-        self.subscribe_background_opts(queries, n, false)
+        self.subscribe_background_opts(queries, n, None)
     }
 
     /// Starts a subscription in the background with --confirmed flag.
     pub fn subscribe_background_confirmed(&self, queries: &[&str], n: usize) -> Result<SubscriptionHandle> {
-        self.subscribe_background_opts(queries, n, true)
+        self.subscribe_background_opts(queries, n, Some(true))
+    }
+
+    /// Starts a subscription in the background with --confirmed flag.
+    pub fn subscribe_background_unconfirmed(&self, queries: &[&str], n: usize) -> Result<SubscriptionHandle> {
+        self.subscribe_background_opts(queries, n, Some(false))
     }
 
     /// Internal helper for background subscribe with options.
-    fn subscribe_background_opts(&self, queries: &[&str], n: usize, confirmed: bool) -> Result<SubscriptionHandle> {
+    fn subscribe_background_opts(
+        &self,
+        queries: &[&str],
+        n: usize,
+        confirmed: Option<bool>,
+    ) -> Result<SubscriptionHandle> {
         use std::io::{BufRead, BufReader};
 
         let identity = self
@@ -1410,8 +1421,9 @@ log = "0.4"
             n.to_string(),
             "--print-initial-update".to_string(),
         ];
-        if confirmed {
+        if let Some(confirmed) = confirmed {
             args.push("--confirmed".to_string());
+            args.push(confirmed.to_string());
         }
         args.push("--".to_string());
         cmd.args(&args)

crates/smoketests/tests/auto_migration.rs

@@ -343,7 +343,13 @@ fn test_add_table_columns() {
     // Subscribe to person table changes multiple times to simulate active clients
     let mut subs = Vec::with_capacity(NUM_SUBSCRIBERS);
     for _ in 0..NUM_SUBSCRIBERS {
-        subs.push(test.subscribe_background(&["select * from person"], 5).unwrap());
+        // We need unconfirmed reads for the updates to arrive properly.
+        // Otherwise, there's a race between module teardown in publish, vs subscribers
+        // getting the row deletion they expect.
+        subs.push(
+            test.subscribe_background_unconfirmed(&["select * from person"], 5)
+                .unwrap(),
+        );
     }
 
     // Insert under initial schema

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

@@ -18,6 +18,7 @@ SpacetimeDB 2.0 introduces a new WebSocket protocol (v2) and SDK with several br
 2. **`light_mode` removed** -- no longer necessary since reducer events are no longer broadcast
 3. **`CallReducerFlags` removed** -- `NoSuccessNotify` and `set_reducer_flags()` are gone
 4. **Event tables introduced** -- a new table type for publishing transient events to subscribers
+5. **Confirmed reads enabled by default** -- subscription updates and SQL results are only sent after the transaction is confirmed durable
 
 ## Reducer Callbacks
 
@@ -1295,6 +1296,69 @@ In 2.0, the success notification is lightweight (just `request_id` and `timestam
 </TabItem>
 </Tabs>
 
+## Confirmed Reads Enabled by Default
+
+### What changed
+
+In 1.0, subscription updates and SQL query results were sent to the client immediately, before the underlying transaction was confirmed to be durable. This meant a client could observe a row that was later lost if the server crashed before persisting it.
+
+In 2.0, **confirmed reads are enabled by default**. The server waits until a transaction is confirmed durable before sending updates to clients. This ensures that any data a client receives will survive a server restart.
+
+### Impact
+
+- **Slightly higher latency**: Subscription updates and SQL results may arrive a few milliseconds later, as the server waits for durability confirmation before sending them.
+- **Stronger consistency**: Clients will never observe data that could be lost due to a crash.
+- **No code changes required**: This is a server-side default change. Existing client code works without modification.
+
+### Opting out
+
+If your application prioritizes low latency over durability guarantees (for example, a real-time game where occasional data loss on crash is acceptable), you can opt out by passing `confirmed=false` in the connection URL:
+
+<Tabs groupId="client-language" queryString>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript
+DbConnection.builder()
+    .withUri("https://maincloud.spacetimedb.com")
+    .withDatabaseName("my-database")
+    .withConfirmedReads(false) // opt out of confirmed reads
+    .build()
+```
+
+</TabItem>
+<TabItem value="csharp" label="C#">
+
+```csharp
+DbConnection.Builder()
+    .WithUri("https://maincloud.spacetimedb.com")
+    .WithDatabaseName("my-database")
+    .WithConfirmedReads(false) // opt out of confirmed reads
+    .Build();
+```
+
+</TabItem>
+<TabItem value="rust" label="Rust">
+
+```rust
+DbConnection::builder()
+    .with_uri("https://maincloud.spacetimedb.com")
+    .with_database_name("my-database")
+    .with_confirmed_reads(false) // opt out of confirmed reads
+    .build()
+    .expect("Failed to connect");
+```
+
+</TabItem>
+</Tabs>
+
+For the CLI:
+
+```bash
+# SQL without confirmed reads
+spacetime sql <database> "SELECT * FROM my_table"
+# The --confirmed flag is no longer needed (it is the default)
+```
+
 ## Quick Migration Checklist
 
 - [ ] Remove all `ctx.reducers.on_<reducer>()` calls
@@ -1320,3 +1384,4 @@ In 2.0, the success notification is lightweight (just `request_id` and `timestam
 - [ ] Remove `with_light_mode()` from `DbConnectionBuilder`
 - [ ] Remove `set_reducer_flags()` calls and `CallReducerFlags` imports
 - [ ] Remove `unstable::CallReducerFlags` from imports
+- [ ] Note that confirmed reads are now enabled by default (no action needed unless you want to opt out with `.withConfirmedReads(false)`)